Skip to content

Commit

Permalink
Merge pull request #16 from dmullis/for-blampe-4.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@blampe
blampe authored Aug 15, 2022
2 parents 7d77c4a + eb7ca65 commit 07bb911
Show file tree
Hide file tree
Showing 43 changed files with 6,306 additions and 1,965 deletions.
7 changes: 5 additions & 2 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,8 @@
vendor
examples/*.svg

goat
goat.test
cmd/tmpl-expand/tmpl-expand
cmd/goat/goat

*~
*.html
24 changes: 24 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,30 @@ No changes yet.

## [0.5.0] - 2022-02-07

### Update (@blampe)

I hacked together GoAT a number of years ago while trying to embed some
diagrams in a Hugo project I was playing with. Through an odd twist of fate
GoAT eventually made its way into the upstream Hugo project, and if you're
using [v0.93.0] you can embed these diagrams natively. Neat!

My original implementation was certainly buggy and not on par with markdeep.
I'm grateful for the folks who've helped smooth out the rough edges, and I've
updated this project to reflect the good changes made in the Hugo fork,
including a long-overdue `go.mod`.

There's a lot I would like to do with this project that I will never get to, so
instead I recommend you look at these forks:
* [@bep] is the fork currently used by Hugo, which I expect to be more active
over time.
* [@dmacvicar] has improved SVG/PNG/PDF rendering.
* [@sw46] has implemented a really wonderful hand-drawn style worth checking
out.

TODO
- Dashed lines signaled by `:` or `=`
- Bold lines signaled by ???

### Changed

* Merges changes made by @bep and @dmacvicar in their forks. This includes
Expand Down
167 changes: 87 additions & 80 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,102 +1,87 @@
# GoAT: Go ASCII Tool
<!--
NOTE to maintainers
---
SVG examples/ regeneration.
go test -run . -v -write

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

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

The @media query from SVG may be verified in Firefox by switching between Themes
"Light" and "Dark" in Firefox's "Add-ons Manager".
-->
- Tie together all three of:
1. Your code's major data structures or abstract data/control flows.
2. Related ASCII-art diagrams embedded in comments, adjacent to the source code.
3. Polished line diagrams in your user-facing high-level documentation, with inline links
to SVG produced by [goat](./cmd/goat).
For Markdown or similar formats, links may be expanded either at build-time or run-time,
as needed by your doc tool suite.

This is a Go implementation of [markdeep.mini.js]'s ASCII diagram
generation.
Your ASCII-art source persists as the single-point-of-truth, revision-controlled along with
the code that embeds it.
This README contains an [example](#library-data-flow).

## Update (2022-02-07)
## You Will Also Need

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

My original implementation was certainly buggy and not on par with markdeep.
I'm grateful for the folks who've helped smooth out the rough edges, and I've
updated this project to reflect the good changes made in the Hugo fork,
including a long-overdue `go.mod`.
#### A fixed-pitch font with 2:1 height:width ratio as presented by your editor and terminal emulator
Most fixed-pitch or "monospace" Unicode fonts maintain a 2:1 aspect ratio for
characters in the ASCII range,
and all GoAT drawing characters are ASCII.
However, certain Unicode graphical characters e.g. MIDDLE DOT may be useful, and
conform to the width of the ASCII range.

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

* [@bep] is the fork currently used by Hugo, which I expect to be more active
over time.
* [@dmacvicar] has improved SVG/PNG/PDF rendering.
* [@sw46] has implemented a really wonderful hand-drawn style worth checking
out.

## Usage

```bash
$ go get github.com/blampe/goat
$ cat my-cool-diagram.txt | goat > my-cool-diagram.svg
## Installation
```
$ go install github.com/blampe/goat/cmd/goat@latest
```

By default, the program reads from stdin, unless `-i infile` is given.

By default, the program writes to stdout, unless `-o outfile` is given or a
binary format with `-f` is selected.

By default, it writes in [SVG] format, unless another format is specified with
`-f`.

## TODO

- Dashed lines signaled by `:` or `=`.
- Bold lines signaled by ???.

## Examples

Here are some SVGs and the UTF-8 input they were generated from:

### Trees
Here are some snippets of
GoAT-formatted UTF-8
and the SVG each can generate.
The SVG you see below was linked to by
inline Markdown image references
([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),
[spec](https://github.github.com/gfm/#images)) from
GoAT's [README.md](README.md), then finally rendered to HTML ```<img>``` elements by Github's Markdown processor

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

### Trees
```
. . . .--- 1 .-- 1 / 1
/ \ | | .---+ .-+ +
/ \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2
+ + | | | | ---+ ---+ +
/ \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3
/ \ / \ | | | | | | | | '---+ '-+ +
1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4
```
### Overlaps
![Overlaps Example](https://cdn.rawgit.com/blampe/goat/main/examples/overlaps.svg)
```
![](./examples/trees.svg)

### Overlaps
```
.-. .-. .-. .-. .-. .-.
| | | | | | | | | | | |
.---------. .--+---+--. .--+---+--. .--| |--. .--+ +--. .------|--.
| | | | | | | | | | | | | | | | | |
'---------' '--+---+--' '--+---+--' '--| |--' '--+ +--' '--|------'
| | | | | | | | | | | |
'-' '-' '-' '-' '-' '-'
```
![](./examples/overlaps.svg)

### Line Decorations

![Line Decorations Example](https://cdn.rawgit.com/blampe/goat/main/examples/line-decorations.svg)

```
________ o * * .--------------.
*---+--. | | o o | ^ \ / | .----------. |
Expand All @@ -105,12 +90,11 @@ Here are some SVGs and the UTF-8 input they were generated from:
<--' ^ ^ | | | | | ^ \ | '--------' | |
\/ *-----' o |<----->| '-----' |__| v '------------' |
/\ *---------------'
```
![](./examples/line-decorations.svg)

### Line Ends

![Line Ends Example](https://cdn.rawgit.com/blampe/goat/main/examples/line-ends.svg)

```
o--o *--o / / * o o o o o * * * * o o o o * * * * o o o o * * * *
o--* *--* v v ^ ^ | | | | | | | | \ \ \ \ \ \ \ \ / / / / / / / /
Expand All @@ -122,26 +106,28 @@ Here are some SVGs and the UTF-8 input they were generated from:
* o | | * o \ \
<--o <--* <--> <--- ---o ---* ---> ---- *<-- o<-- -->o -->*
```
### Dot Grids
![Dot Grids Example](https://cdn.rawgit.com/blampe/goat/main/examples/dot-grids.svg)
```
![](./examples/line-ends.svg)

### Dot Grids
```
o o o o o * * * * * * * o o * o o o * * * o o o · * · · · · · ·
o o o o o * * * * * o o o o * o o o o * * * * * o * * · * * · · · · · ·
o o o o o * * * * * o * o o o o o o o o * * * * * o o o o o · o · · o · · * * ·
o o o o o * * * * * o * o o o o o o o * * * * o * o o · · · · o · · * ·
o o o o o * * * * * * * * * o o o o * * * o * o · · · · · · · *
```
Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character, encoded with UTF-8.
![](./examples/dot-grids.svg)

### Large Nodes

![Large Node Example](https://cdn.rawgit.com/blampe/goat/main/examples/large-nodes.svg)

```
.---. .-. .-. .-. .-.
| A +----->| 1 +<---->| 2 |<----+ 4 +------------------. | 8 |
'---' '-' '+' '-' | '-'
Expand All @@ -150,12 +136,12 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character,
.-. .-+-. .-. .-+-. .-. .+. .---.
| 3 +---->| B |<----->| 5 +---->| C +---->| 6 +---->| 7 |<---->| D |
'-' '---' '-' '---' '-' '-' '---'
```
![](./examples/large-nodes.svg)

### Small Grids

![Small Grids Example](https://cdn.rawgit.com/blampe/goat/main/examples/small-grids.svg)

![](./examples/small-grids.svg)
```
___ ___ .---+---+---+---+---. .---+---+---+---. .---. .---.
___/ \___/ \ | | | | | | / \ / \ / \ / \ / | +---+ |
Expand All @@ -164,12 +150,11 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character,
/ a \___/ \___/ +---+---+---+---+---+ +---+---+---+---+ +---+ b +---+
\___/ \___/ \ | | a | | | | / \ / \ / \ / \ / | a +---+ |
\___/ \___/ '---+---+---+---+---' '---+---+---+---' '---' '---'
```
### Big Grids
![Big Grids Example](https://cdn.rawgit.com/blampe/goat/main/examples/big-grids.svg)
```

### Big Grids
```
.----. .----.
/ \ / \ .-----+-----+-----.
Expand All @@ -182,12 +167,12 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character,
'----+ +----+ + | | | | +-----+-----+-----+-----+
\ / \ / | A | | | / / / / /
'----' '----' '-----+-----+-----' '-----+-----+-----+-----+
```
### Complicated
![Complicated Example](https://cdn.rawgit.com/blampe/goat/main/examples/complicated.svg)
```
![](./examples/big-grids.svg)

### Complicated
```
+-------------------+ ^ .---.
| A Box |__.--.__ __.--> | .-. | |
Expand All @@ -213,9 +198,31 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character,
.-. .---+--------. / A || B *bold* | ^
| | | Not a dot | <---+---<-- A dash--is not a line v |
'-' '---------+--' / Nor/is this. ---
```
![](./examples/complicated.svg)

### More examples are [here](examples)

## The GoAT Library

The core engine of ```goat``` is accessible as a Go library package, for inclusion in specialized
code of your own.
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/).

### library Data Flow
![](./goat.svg)

The diagram above was derived by [./make.sh](./make.sh) from ASCII-art in the Go
source file [./goat.go](./goat.go).

#### Project Tenets

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

[@bep]: https://github.com/bep/goat/
[@dmacvicar]: https://github.com/dmacvicar/goat
Expand Down
Loading

0 comments on commit 07bb911

Please sign in to comment.