Skip to content

Commit 9ff4c2b

Browse files
author
dmullis
committed
README.md.tmpl: Drop copy-pasted .txt diagrams; Rewrite
1 parent 8d29eae commit 9ff4c2b

File tree

2 files changed

+76
-152
lines changed

2 files changed

+76
-152
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,10 @@ instead I recommend you look at these forks:
2626
* [@sw46] has implemented a really wonderful hand-drawn style worth checking
2727
out.
2828

29+
TODO
30+
- Dashed lines signaled by `:` or `=`
31+
- Bold lines signaled by ???
32+
2933
### Changed
3034

3135
* Merges changes made by @bep and @dmacvicar in their forks. This includes

‎README.md.tmpl‎

Lines changed: 72 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,32 @@
11
# GoAT: Go ASCII Tool
22

3-
## What **goat** Can Do For You
3+
## What **GoAT** Can Do For You
44

5-
* From a chunky ASCII-art source drawing, render to a pretty SVG output file,
6-
with (goat)[./cmd/goat] run from the shell command line.
5+
- From a chunky ASCII-art source drawing, render polished, graphically-rich [SVG](#complicated),
6+
with the [goat](./cmd/goat) CLI command.
77

8-
* Build publication-ready illustrated documentation, in Markdown, directly
9-
from comments in Go source code.
10-
(goatdoc)[./cmd/goatdoc] reformats the output of 'go doc -all' into Github-flavored Markdown.
11-
Any embedded goat-format drawings are processed into SVG for inclusion within
12-
the Markdown.
8+
- Tie together all three of:
9+
1. Your code's major data structures or abstract data/control flows.
10+
2. Related ASCII-art diagrams embedded in comments, adjacent to the source code.
11+
3. Polished line diagrams in your user-facing high-level documentation, with inline links
12+
to SVG produced by [goat](./cmd/goat).
13+
For Markdown or similar formats, links may be expanded either at build-time or run-time,
14+
as needed by your doc tool suite.
15+
16+
Your ASCII-art source persists as the single-point-of-truth, revision-controlled along with
17+
the code that embeds it.
18+
This README contains an [example](#library-data-flow).
1319

1420
## You Will Also Need
1521

16-
#### Rectangle or Graphical editing capability
22+
#### Graphical- or Rectangle-oriented text editing capability
1723
Both **vim** and **emacs** offer useful support.
1824
In Emacs, see the built-in rectangle-editing commands, and ```picture-mode```.
1925

20-
#### A fixed-pitch font with 2:1 height:width, for your editor and terminal emulator both
21-
Most fixed-pitch ("monospace") Unicode fonts maintain a 2:1 aspect ratio for all
26+
#### A fixed-pitch font with 2:1 height:width ratio as presented by your editor and terminal emulator
27+
Most fixed-pitch or "monospace" Unicode fonts maintain a 2:1 aspect ratio for
2228
characters in the ASCII range,
23-
and all **goat** drawing characters are ASCII.
29+
and all GoAT drawing characters are ASCII.
2430
However, certain Unicode graphical characters e.g. MIDDLE DOT may be useful, and
2531
conform to the width of the ASCII range.
2632

@@ -29,185 +35,99 @@ Non-standard width characters are not in general composable on the left-right ax
2935
drawing, because the remainder of the line of text to their right is pushed out of alignment
3036
with rows above and below.
3137

32-
## Goat Library API
33-
34-
The core engine of ```goat``` is accessible as a Go package, for inclusion in specialized
35-
Go code of your own.
36-
Documented [here]({{.Root}}/API.html).
37-
The goat library is a Go implementation of [markdeep.mini.js]'s ASCII diagram generation.
38-
39-
## Project Tenets
40-
41-
1. Utility and ease of integration into existing projects are paramount.
42-
2. Compatibility with MarkDeep desired, but not required.
43-
3. TXT and SVG intelligibility are co-equal in priority.
44-
4. Composability of TXT not to be sacrificed -- only width-8 characters allowed.
45-
5. Per-platform support limited to a single widely-available fixed-pitch TXT font.
46-
47-
## TODO
48-
49-
- Dashed lines signaled by `:` or `=`.
50-
- Bold lines signaled by ???.
51-
52-
## Data Flow
53-
![]({{.Root}}/goat.svg)
38+
## Installation
39+
```
40+
$ go install github.com/{{.GithubUser}}/goat/cmd/goat@latest
41+
```
5442

5543
## Examples
5644

57-
Here are some SVGs, as linked to via HTML <img> elements within the Github-processed Markdown
58-
output of this README.md, along with the UTF-8 input they were generated from.
45+
Here are some snippets of
46+
GoAT-formatted UTF-8
47+
and the SVG each can generate.
48+
The SVG you see below was linked to by
49+
inline Markdown image references
50+
([howto](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#images),
51+
[spec](https://github.github.com/gfm/#images)) from
52+
GoAT's [README.md](README.md), then finally rendered to HTML ```<img>``` elements by Github's Markdown processor
5953

60-
### Trees
61-
62-
![Trees Example]({{.Root}}/examples/trees.svg)
6354

55+
### Trees
6456
```
65-
. . . .--- 1 .-- 1 / 1
66-
/ \ | | .---+ .-+ +
67-
/ \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2
68-
+ + | | | | ---+ ---+ +
69-
/ \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3
70-
/ \ / \ | | | | | | | | '---+ '-+ +
71-
1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4
57+
{{.trees_txt}}
7258
```
59+
![]({{.Root}}/examples/trees.svg)
7360

7461
### Overlaps
75-
76-
![Overlaps Example]({{.Root}}/examples/overlaps.svg)
77-
7862
```
79-
.-. .-. .-. .-. .-. .-.
80-
| | | | | | | | | | | |
81-
.---------. .--+---+--. .--+---+--. .--| |--. .--+ +--. .------|--.
82-
| | | | | | | | | | | | | | | | | |
83-
'---------' '--+---+--' '--+---+--' '--| |--' '--+ +--' '--|------'
84-
| | | | | | | | | | | |
85-
'-' '-' '-' '-' '-' '-'
63+
{{.overlaps_txt}}
8664
```
65+
![]({{.Root}}/examples/overlaps.svg)
8766

8867
### Line Decorations
89-
90-
![Line Decorations Example]({{.Root}}/examples/line-decorations.svg)
91-
9268
```
93-
________ o * * .--------------.
94-
*---+--. | | o o | ^ \ / | .----------. |
95-
| | '--* -+- | | v / \ / | | <------. | |
96-
| '-----> .---(---' --->*<--- / .+->*<--o----' | | | | |
97-
<--' ^ ^ | | | | | ^ \ | '--------' | |
98-
\/ *-----' o |<----->| '-----' |__| v '------------' |
99-
/\ *---------------'
69+
{{.line_decorations_txt}}
10070
```
71+
![]({{.Root}}/examples/line-decorations.svg)
10172

10273
### Line Ends
103-
104-
![Line Ends Example]({{.Root}}/examples/line-ends.svg)
105-
10674
```
107-
o--o *--o / / * o o o o o * * * * o o o o * * * * o o o o * * * *
108-
o--* *--* v v ^ ^ | | | | | | | | \ \ \ \ \ \ \ \ / / / / / / / /
109-
o--> *--> * o / / o * v ' o * v ' o * v \ o * v \ o * v / o * v /
110-
o--- *---
111-
^ ^ ^ ^ . . . . ^ ^ ^ ^ \ \ \ \ ^ ^ ^ ^ / / / /
112-
| | * o \ \ * o | | | | | | | | \ \ \ \ \ \ \ \ / / / / / / / /
113-
v v ^ ^ v v ^ ^ o * v ' o * v ' o * v \ o * v \ o * v / o * v /
114-
* o | | * o \ \
115-
116-
<--o <--* <--> <--- ---o ---* ---> ---- *<-- o<-- -->o -->*
75+
{{.line_ends_txt}}
11776
```
77+
![]({{.Root}}/examples/line-ends.svg)
11878

11979
### Dot Grids
120-
121-
![Dot Grids Example]({{.Root}}/examples/dot-grids.svg)
122-
12380
```
124-
o o o o o * * * * * * * o o * o o o * * * o o o · * · · · · · ·
125-
o o o o o * * * * * o o o o * o o o o * * * * * o * * · * * · · · · · ·
126-
o o o o o * * * * * o * o o o o o o o o * * * * * o o o o o · o · · o · · * * ·
127-
o o o o o * * * * * o * o o o o o o o * * * * o * o o · · · · o · · * ·
128-
o o o o o * * * * * * * * * o o o o * * * o * o · · · · · · · *
81+
{{.dot_grids_txt}}
12982
```
13083
Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character, encoded with UTF-8.
84+
![]({{.Root}}/examples/dot-grids.svg)
13185

13286
### Large Nodes
133-
134-
![Large Node Example]({{.Root}}/examples/large-nodes.svg)
135-
13687
```
137-
.---. .-. .-. .-. .-.
138-
| A +----->| 1 +<---->| 2 |<----+ 4 +------------------. | 8 |
139-
'---' '-' '+' '-' | '-'
140-
| ^ | ^
141-
v | v |
142-
.-. .-+-. .-. .-+-. .-. .+. .---.
143-
| 3 +---->| B |<----->| 5 +---->| C +---->| 6 +---->| 7 |<---->| D |
144-
'-' '---' '-' '---' '-' '-' '---'
88+
{{.large_nodes_txt}}
14589
```
90+
![]({{.Root}}/examples/large-nodes.svg)
14691

14792
### Small Grids
148-
149-
![Small Grids Example]({{.Root}}/examples/small-grids.svg)
150-
93+
![]({{.Root}}/examples/small-grids.svg)
15194
```
152-
___ ___ .---+---+---+---+---. .---+---+---+---. .---. .---.
153-
___/ \___/ \ | | | | | | / \ / \ / \ / \ / | +---+ |
154-
/ \___/ \___/ +---+---+---+---+---+ +---+---+---+---+ +---+ +---+
155-
\___/ b \___/ \ | | | b | | | \ / \a/ \b/ \ / \ | +---+ |
156-
/ a \___/ \___/ +---+---+---+---+---+ +---+---+---+---+ +---+ b +---+
157-
\___/ \___/ \ | | a | | | | / \ / \ / \ / \ / | a +---+ |
158-
\___/ \___/ '---+---+---+---+---' '---+---+---+---' '---' '---'
95+
{{.small_grids_txt}}
15996
```
16097

16198
### Big Grids
162-
163-
![Big Grids Example]({{.Root}}/examples/big-grids.svg)
164-
16599
```
166-
.----. .----.
167-
/ \ / \ .-----+-----+-----.
168-
+ +----+ +----. | | | | .-----+-----+-----+-----+
169-
\ / \ / \ | | | | / / / / /
170-
+----+ B +----+ + +-----+-----+-----+ +-----+-----+-----+-----+
171-
/ \ / \ / | | | | / / / / /
172-
+ A +----+ +----+ | | B | | +-----+-----+-----+-----+
173-
\ / \ / \ +-----+-----+-----+ / / A / B / /
174-
'----+ +----+ + | | | | +-----+-----+-----+-----+
175-
\ / \ / | A | | | / / / / /
176-
'----' '----' '-----+-----+-----' '-----+-----+-----+-----+
100+
{{.big_grids_txt}}
177101
```
102+
![]({{.Root}}/examples/big-grids.svg)
178103

179104
### Complicated
105+
```
106+
{{.complicated_txt}}
107+
```
108+
![]({{.Root}}/examples/complicated.svg)
109+
110+
### More examples are [here](examples)
180111

181-
![Complicated Example]({{.Root}}/examples/complicated.svg)
182-
183-
```
184-
+-------------------+ ^ .---.
185-
| A Box |__.--.__ __.--> | .-. | |
186-
| | '--' v | * |<--- | |
187-
+-------------------+ '-' | |
188-
Round *---(-. |
189-
.-----------------. .-------. .----------. .-------. | | |
190-
| Mixed Rounded | | | / Diagonals \ | | | | | |
191-
| & Square Corners | '--. .--' / \ |---+---| '-)-' .--------.
192-
'--+------------+-' .--. | '-------+--------' | | | | / Search /
193-
| | | | '---. | '-------' | '-+------'
194-
|<---------->| | | | v Interior | ^
195-
' <---' '----' .-----------. ---. .--- v |
196-
.------------------. Diag line | .-------. +---. \ / . |
197-
| if (a > b) +---. .--->| | | | | Curved line \ / / \ |
198-
| obj->fcn() | \ / | '-------' |<--' + / \ |
199-
'------------------' '--' '--+--------' .--. .--. | .-. +Done?+-'
200-
.---+-----. | ^ |\ | | /| .--+ | | \ /
201-
| | | Join \|/ | | Curved | \| |/ | | \ | \ /
202-
| | +----> o --o-- '-' Vertical '--' '--' '-- '--' + .---.
203-
<--+---+-----' | /|\ | | 3 |
204-
v not:line 'quotes' .-' '---'
205-
.-. .---+--------. / A || B *bold* | ^
206-
| | | Not a dot | <---+---<-- A dash--is not a line v |
207-
'-' '---------+--' / Nor/is this. ---
208-
```
209-
210-
More examples are available [here](examples).
112+
## The GoAT Library
113+
114+
The core engine of ```goat``` is accessible as a Go library package, for inclusion in specialized
115+
code of your own.
116+
The code implements a subset, and some extensions, of the ASCII diagram generation function of the browser-side Javascript in [Markdeep](http://casual-effects.com/markdeep/).
117+
118+
### library Data Flow
119+
![]({{.Root}}/goat.svg)
120+
121+
The diagram above was derived by [./make.sh](./make.sh) from ASCII-art in the Go
122+
source file [./goat.go](./goat.go).
123+
124+
#### Project Tenets
125+
126+
1. Utility and ease of integration into existing projects are paramount.
127+
2. Compatibility with MarkDeep desired, but not required.
128+
3. TXT and SVG intelligibility are co-equal in priority.
129+
4. Composability of TXT not to be sacrificed -- only width-8 characters allowed.
130+
5. Per-platform support limited to a single widely-available fixed-pitch TXT font.
211131

212132
[@bep]: https://github.com/bep/goat/
213133
[@dmacvicar]: https://github.com/dmacvicar/goat

0 commit comments

Comments
 (0)