Skip to content

Commit 07bb911

Browse files
blampeblampe
authored
Merge pull request #16 from dmullis/for-blampe-4.0
2 parents 7d77c4a + eb7ca65 commit 07bb911

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+6306
-1965
lines changed

‎.gitignore

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,8 @@
44
vendor
55
examples/*.svg
66

7-
goat
8-
goat.test
7+
cmd/tmpl-expand/tmpl-expand
8+
cmd/goat/goat
9+
10+
*~
11+
*.html

‎CHANGELOG.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,30 @@ No changes yet.
66

77
## [0.5.0] - 2022-02-07
88

9+
### Update (@blampe)
10+
11+
I hacked together GoAT a number of years ago while trying to embed some
12+
diagrams in a Hugo project I was playing with. Through an odd twist of fate
13+
GoAT eventually made its way into the upstream Hugo project, and if you're
14+
using [v0.93.0] you can embed these diagrams natively. Neat!
15+
16+
My original implementation was certainly buggy and not on par with markdeep.
17+
I'm grateful for the folks who've helped smooth out the rough edges, and I've
18+
updated this project to reflect the good changes made in the Hugo fork,
19+
including a long-overdue `go.mod`.
20+
21+
There's a lot I would like to do with this project that I will never get to, so
22+
instead I recommend you look at these forks:
23+
* [@bep] is the fork currently used by Hugo, which I expect to be more active
24+
over time.
25+
* [@dmacvicar] has improved SVG/PNG/PDF rendering.
26+
* [@sw46] has implemented a really wonderful hand-drawn style worth checking
27+
out.
28+
29+
TODO
30+
- Dashed lines signaled by `:` or `=`
31+
- Bold lines signaled by ???
32+
933
### Changed
1034

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

‎README.md

Lines changed: 87 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,87 @@
11
# GoAT: Go ASCII Tool
2-
<!--
3-
NOTE to maintainers
4-
---
5-
SVG examples/ regeneration.
6-
go test -run . -v -write
72

8-
Github home page README.md, specific to $USER:
9-
sed "s,{{\.Root}},https://cdn.rawgit.com/${USER}/goat/main," README.md.tmpl >README.md
3+
## What **GoAT** Can Do For You
104

11-
Local preview of home page:
12-
sed "s,https://cdn.rawgit.com/blampe/goat/main,.," README.md.tmpl >README.md
13-
# See https://github.github.com/gfm/#introduction
14-
(echo '<!DOCTYPE html>'; marked -gfm README.md) >README.html
5+
- From a chunky ASCII-art source drawing, render polished, graphically-rich [SVG](#complicated),
6+
with the [goat](./cmd/goat) CLI command.
157

16-
The @media query from SVG may be verified in Firefox by switching between Themes
17-
"Light" and "Dark" in Firefox's "Add-ons Manager".
18-
-->
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.
1915

20-
This is a Go implementation of [markdeep.mini.js]'s ASCII diagram
21-
generation.
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).
2219

23-
## Update (2022-02-07)
20+
## You Will Also Need
2421

25-
I hacked together GoAT a number of years ago while trying to embed some
26-
diagrams in a Hugo project I was playing with. Through an odd twist of fate
27-
GoAT eventually made its way into the upstream Hugo project, and if you're
28-
using [v0.93.0] you can embed these diagrams natively. Neat!
22+
#### Graphical- or Rectangle-oriented text editing capability
23+
Both **vim** and **emacs** offer useful support.
24+
In Emacs, see the built-in rectangle-editing commands, and ```picture-mode```.
2925

30-
My original implementation was certainly buggy and not on par with markdeep.
31-
I'm grateful for the folks who've helped smooth out the rough edges, and I've
32-
updated this project to reflect the good changes made in the Hugo fork,
33-
including a long-overdue `go.mod`.
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
28+
characters in the ASCII range,
29+
and all GoAT drawing characters are ASCII.
30+
However, certain Unicode graphical characters e.g. MIDDLE DOT may be useful, and
31+
conform to the width of the ASCII range.
3432

35-
There's a lot I would like to do with this project that I will never get to, so
36-
instead I recommend you look at these forks:
33+
CJK characters on the other hand are typically wider than 2:1.
34+
Non-standard width characters are not in general composable on the left-right axis within a plain-text
35+
drawing, because the remainder of the line of text to their right is pushed out of alignment
36+
with rows above and below.
3737

38-
* [@bep] is the fork currently used by Hugo, which I expect to be more active
39-
over time.
40-
* [@dmacvicar] has improved SVG/PNG/PDF rendering.
41-
* [@sw46] has implemented a really wonderful hand-drawn style worth checking
42-
out.
43-
44-
## Usage
45-
46-
```bash
47-
$ go get github.com/blampe/goat
48-
$ cat my-cool-diagram.txt | goat > my-cool-diagram.svg
38+
## Installation
39+
```
40+
$ go install github.com/blampe/goat/cmd/goat@latest
4941
```
50-
51-
By default, the program reads from stdin, unless `-i infile` is given.
52-
53-
By default, the program writes to stdout, unless `-o outfile` is given or a
54-
binary format with `-f` is selected.
55-
56-
By default, it writes in [SVG] format, unless another format is specified with
57-
`-f`.
58-
59-
## TODO
60-
61-
- Dashed lines signaled by `:` or `=`.
62-
- Bold lines signaled by ???.
6342

6443
## Examples
6544

66-
Here are some SVGs and the UTF-8 input they were generated from:
67-
68-
### Trees
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
6953

70-
![Trees Example](https://cdn.rawgit.com/blampe/goat/main/examples/trees.svg)
7154

55+
### Trees
7256
```
57+
7358
. . . .--- 1 .-- 1 / 1
7459
/ \ | | .---+ .-+ +
7560
/ \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2
7661
+ + | | | | ---+ ---+ +
7762
/ \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3
7863
/ \ / \ | | | | | | | | '---+ '-+ +
7964
1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4
80-
```
8165
82-
### Overlaps
8366
84-
![Overlaps Example](https://cdn.rawgit.com/blampe/goat/main/examples/overlaps.svg)
67+
```
68+
![](./examples/trees.svg)
8569

70+
### Overlaps
8671
```
72+
8773
.-. .-. .-. .-. .-. .-.
8874
| | | | | | | | | | | |
8975
.---------. .--+---+--. .--+---+--. .--| |--. .--+ +--. .------|--.
9076
| | | | | | | | | | | | | | | | | |
9177
'---------' '--+---+--' '--+---+--' '--| |--' '--+ +--' '--|------'
9278
| | | | | | | | | | | |
9379
'-' '-' '-' '-' '-' '-'
80+
9481
```
82+
![](./examples/overlaps.svg)
9583

9684
### Line Decorations
97-
98-
![Line Decorations Example](https://cdn.rawgit.com/blampe/goat/main/examples/line-decorations.svg)
99-
10085
```
10186
________ o * * .--------------.
10287
*---+--. | | o o | ^ \ / | .----------. |
@@ -105,12 +90,11 @@ Here are some SVGs and the UTF-8 input they were generated from:
10590
<--' ^ ^ | | | | | ^ \ | '--------' | |
10691
\/ *-----' o |<----->| '-----' |__| v '------------' |
10792
/\ *---------------'
93+
10894
```
95+
![](./examples/line-decorations.svg)
10996

11097
### Line Ends
111-
112-
![Line Ends Example](https://cdn.rawgit.com/blampe/goat/main/examples/line-ends.svg)
113-
11498
```
11599
o--o *--o / / * o o o o o * * * * o o o o * * * * o o o o * * * *
116100
o--* *--* v v ^ ^ | | | | | | | | \ \ \ \ \ \ \ \ / / / / / / / /
@@ -122,26 +106,28 @@ Here are some SVGs and the UTF-8 input they were generated from:
122106
* o | | * o \ \
123107
124108
<--o <--* <--> <--- ---o ---* ---> ---- *<-- o<-- -->o -->*
125-
```
126109
127-
### Dot Grids
128110
129-
![Dot Grids Example](https://cdn.rawgit.com/blampe/goat/main/examples/dot-grids.svg)
111+
```
112+
![](./examples/line-ends.svg)
130113

114+
### Dot Grids
131115
```
116+
132117
o o o o o * * * * * * * o o * o o o * * * o o o · * · · · · · ·
133118
o o o o o * * * * * o o o o * o o o o * * * * * o * * · * * · · · · · ·
134119
o o o o o * * * * * o * o o o o o o o o * * * * * o o o o o · o · · o · · * * ·
135120
o o o o o * * * * * o * o o o o o o o * * * * o * o o · · · · o · · * ·
136121
o o o o o * * * * * * * * * o o o o * * * o * o · · · · · · · *
122+
123+
137124
```
138125
Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character, encoded with UTF-8.
126+
![](./examples/dot-grids.svg)
139127

140128
### Large Nodes
141-
142-
![Large Node Example](https://cdn.rawgit.com/blampe/goat/main/examples/large-nodes.svg)
143-
144129
```
130+
145131
.---. .-. .-. .-. .-.
146132
| A +----->| 1 +<---->| 2 |<----+ 4 +------------------. | 8 |
147133
'---' '-' '+' '-' | '-'
@@ -150,12 +136,12 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character,
150136
.-. .-+-. .-. .-+-. .-. .+. .---.
151137
| 3 +---->| B |<----->| 5 +---->| C +---->| 6 +---->| 7 |<---->| D |
152138
'-' '---' '-' '---' '-' '-' '---'
139+
153140
```
141+
![](./examples/large-nodes.svg)
154142

155143
### Small Grids
156-
157-
![Small Grids Example](https://cdn.rawgit.com/blampe/goat/main/examples/small-grids.svg)
158-
144+
![](./examples/small-grids.svg)
159145
```
160146
___ ___ .---+---+---+---+---. .---+---+---+---. .---. .---.
161147
___/ \___/ \ | | | | | | / \ / \ / \ / \ / | +---+ |
@@ -164,12 +150,11 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character,
164150
/ a \___/ \___/ +---+---+---+---+---+ +---+---+---+---+ +---+ b +---+
165151
\___/ \___/ \ | | a | | | | / \ / \ / \ / \ / | a +---+ |
166152
\___/ \___/ '---+---+---+---+---' '---+---+---+---' '---' '---'
167-
```
168153
169-
### Big Grids
170154
171-
![Big Grids Example](https://cdn.rawgit.com/blampe/goat/main/examples/big-grids.svg)
155+
```
172156

157+
### Big Grids
173158
```
174159
.----. .----.
175160
/ \ / \ .-----+-----+-----.
@@ -182,12 +167,12 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character,
182167
'----+ +----+ + | | | | +-----+-----+-----+-----+
183168
\ / \ / | A | | | / / / / /
184169
'----' '----' '-----+-----+-----' '-----+-----+-----+-----+
185-
```
186170
187-
### Complicated
188171
189-
![Complicated Example](https://cdn.rawgit.com/blampe/goat/main/examples/complicated.svg)
172+
```
173+
![](./examples/big-grids.svg)
190174

175+
### Complicated
191176
```
192177
+-------------------+ ^ .---.
193178
| A Box |__.--.__ __.--> | .-. | |
@@ -213,9 +198,31 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character,
213198
.-. .---+--------. / A || B *bold* | ^
214199
| | | Not a dot | <---+---<-- A dash--is not a line v |
215200
'-' '---------+--' / Nor/is this. ---
201+
216202
```
203+
![](./examples/complicated.svg)
204+
205+
### More examples are [here](examples)
206+
207+
## The GoAT Library
208+
209+
The core engine of ```goat``` is accessible as a Go library package, for inclusion in specialized
210+
code of your own.
211+
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/).
212+
213+
### library Data Flow
214+
![](./goat.svg)
215+
216+
The diagram above was derived by [./make.sh](./make.sh) from ASCII-art in the Go
217+
source file [./goat.go](./goat.go).
218+
219+
#### Project Tenets
217220

218-
More examples are available [here](examples).
221+
1. Utility and ease of integration into existing projects are paramount.
222+
2. Compatibility with MarkDeep desired, but not required.
223+
3. TXT and SVG intelligibility are co-equal in priority.
224+
4. Composability of TXT not to be sacrificed -- only width-8 characters allowed.
225+
5. Per-platform support limited to a single widely-available fixed-pitch TXT font.
219226

220227
[@bep]: https://github.com/bep/goat/
221228
[@dmacvicar]: https://github.com/dmacvicar/goat

0 commit comments

Comments
 (0)