diff --git a/.github/workflows/make.yml b/.github/workflows/make.yml new file mode 100644 index 0000000..6ebc20b --- /dev/null +++ b/.github/workflows/make.yml @@ -0,0 +1,37 @@ +name: Make + +on: + push: + pull_request: + branches: [main] + +jobs: + build: + strategy: + matrix: + go-version: [1.21.x] + os: [ubuntu-latest] + runs-on: ${{ matrix.os }} + + steps: + - name: Install Go + uses: actions/setup-go@v4 + with: + go-version: ${{ matrix.go-version }} + + - name: Check Out code + uses: actions/checkout@v3 + + - name: Make + run: ./make.sh + + - name: Configure Git + run: | + git config --global user.name 'github-actions[bot]' + git config --global user.email 'github-actions[bot]@users.noreply.github.com' + + - name: Commit and Push documentation + run: | + git add README.md goat.svg trees.mid-blue.svg + git commit -m 'Commit Github-generated documentation files' + git push diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml deleted file mode 100644 index cb5d5b3..0000000 --- a/.github/workflows/test.yml +++ /dev/null @@ -1,23 +0,0 @@ -name: Test - -on: - push: - branches: [main] - pull_request: - branches: [main] -jobs: - build: - strategy: - matrix: - go-version: '1.20' - os: [ubuntu-latest, windows-latest] - runs-on: ${{ matrix.os }} - steps: - - name: Install Go - uses: actions/setup-go@v4 - with: - go-version: ${{ matrix.go-version }} - - name: Checkout code - uses: actions/checkout@v3 - - name: Test - run: go test -race -v . diff --git a/README.md b/README.md deleted file mode 100644 index 4b8f402..0000000 --- a/README.md +++ /dev/null @@ -1,270 +0,0 @@ -# GoAT: Go ASCII Tool - - -![](https://github.com/github/docs/actions/workflows/test.yml/badge.svg) - -## What **GoAT** Can Do For You - -- From a chunky ASCII-art source drawing, render polished, graphically-rich [SVG](#complicated), - with the [goat](#installation) CLI command. - - - -- 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. - - 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). - -## You Will Also Need - -#### 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```. - -#### 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. - -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. - -## Installation -``` - $ go install github.com/blampe/goat/cmd/goat@latest -``` - - -## Example Graphics - -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 `````` elements by Github's Markdown processor - - -### 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 - - -``` -![](./examples/trees.svg) - -### Trees -- mid-range color value -Setting a foreground color in the middle of the possible range of value or luminance -is one way to work around a limitation of certain browsers e.g. Safari. -Safari does not support inheritance of -the [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) -CSS property by -`goat`'s output `` element -from within an enclosing `` element such as are generated by Markdown. - - -![](./trees.mid-blue.svg) - -### Overlaps -``` - - .-. .-. .-. .-. .-. .-. - | | | | | | | | | | | | - .---------. .--+---+--. .--+---+--. .--| |--. .--+ +--. .------|--. - | | | | | | | | | | | | | | | | | | - '---------' '--+---+--' '--+---+--' '--| |--' '--+ +--' '--|------' - | | | | | | | | | | | | - '-' '-' '-' '-' '-' '-' - -``` -![](./examples/overlaps.svg) - -### Line Decorations -``` - ________ o * * .--------------. - *---+--. | | o o | ^ \ / | .----------. | - | | '--* -+- | | v / \ / | | <------. | | - | '-----> .---(---' --->*<--- / .+->*<--o----' | | | | | - <--' ^ ^ | | | | | ^ \ | '--------' | | - \/ *-----' o |<----->| '-----' |__| v '------------' | - /\ *---------------' - -``` -![](./examples/line-decorations.svg) - -### Line Ends -``` - o--o *--o / / * o o o o o * * * * o o o o * * * * o o o o * * * * - o--* *--* v v ^ ^ | | | | | | | | \ \ \ \ \ \ \ \ / / / / / / / / - o--> *--> * o / / o * v ' o * v ' o * v \ o * v \ o * v / o * v / - o--- *--- - ^ ^ ^ ^ . . . . ^ ^ ^ ^ \ \ \ \ ^ ^ ^ ^ / / / / - | | * o \ \ * o | | | | | | | | \ \ \ \ \ \ \ \ / / / / / / / / - v v ^ ^ v v ^ ^ o * v ' o * v ' o * v \ o * v \ o * v / o * v / - * o | | * o \ \ - - <--o <--* <--> <--- ---o ---* ---> ---- *<-- o<-- -->o -->* - - -``` -![](./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 -``` - - .---. .-. .-. .-. .-. - | A +----->| 1 +<---->| 2 |<----+ 4 +------------------. | 8 | - '---' '-' '+' '-' | '-' - | ^ | ^ - v | v | - .-. .-+-. .-. .-+-. .-. .+. .---. - | 3 +---->| B |<----->| 5 +---->| C +---->| 6 +---->| 7 |<---->| D | - '-' '---' '-' '---' '-' '-' '---' - -``` -![](./examples/large-nodes.svg) - -### Small Grids -``` - ___ ___ .---+---+---+---+---. .---+---+---+---. .---. .---. - ___/ \___/ \ | | | | | | / \ / \ / \ / \ / | +---+ | - / \___/ \___/ +---+---+---+---+---+ +---+---+---+---+ +---+ +---+ - \___/ b \___/ \ | | | b | | | \ / \a/ \b/ \ / \ | +---+ | - / a \___/ \___/ +---+---+---+---+---+ +---+---+---+---+ +---+ b +---+ - \___/ \___/ \ | | a | | | | / \ / \ / \ / \ / | a +---+ | - \___/ \___/ '---+---+---+---+---' '---+---+---+---' '---' '---' - - -``` -![](./examples/small-grids.svg) - -### Big Grids -``` - .----. .----. - / \ / \ .-----+-----+-----. - + +----+ +----. | | | | .-----+-----+-----+-----+ - \ / \ / \ | | | | / / / / / - +----+ B +----+ + +-----+-----+-----+ +-----+-----+-----+-----+ - / \ / \ / | | | | / / / / / - + A +----+ +----+ | | B | | +-----+-----+-----+-----+ - \ / \ / \ +-----+-----+-----+ / / A / B / / - '----+ +----+ + | | | | +-----+-----+-----+-----+ - \ / \ / | A | | | / / / / / - '----' '----' '-----+-----+-----' '-----+-----+-----+-----+ - - -``` -![](./examples/big-grids.svg) - -### Complicated -``` -+-------------------+ ^ .---. -| A Box |__.--.__ __.--> | .-. | | -| | '--' v | * |<--- | | -+-------------------+ '-' | | - Round *---(-. | - .-----------------. .-------. .----------. .-------. | | | - | Mixed Rounded | | | / Diagonals \ | | | | | | - | & Square Corners | '--. .--' / \ |---+---| '-)-' .--------. - '--+------------+-' .--. | '-------+--------' | | | | / Search / - | | | | '---. | '-------' | '-+------' - |<---------->| | | | v Interior | ^ - ' <---' '----' .-----------. ---. .--- v | - .------------------. Diag line | .-------. +---. \ / . | - | if (a > b) +---. .--->| | | | | Curved line \ / / \ | - | obj->fcn() | \ / | '-------' |<--' + / \ | - '------------------' '--' '--+--------' .--. .--. | .-. +Done?+-' - .---+-----. | ^ |\ | | /| .--+ | | \ / - | | | Join \|/ | | Curved | \| |/ | | \ | \ / - | | +----> o --o-- '-' Vertical '--' '--' '-- '--' + .---. - <--+---+-----' | /|\ | | 3 | - v not:line 'quotes' .-' '---' - .-. .---+--------. / 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/). - -A nicely formatted reference may be found at [pkg.go.dev](https://pkg.go.dev/github.com/blampe/goat). - -### Installation - -``` - $ go get -u github.com/blampe/goat/ -``` -### 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). - -#### Auto-formatted API docs - - - - - -### Project Tenets - -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 -[@sw46]: https://github.com/sw46/goat/ -[SVG]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics -[markdeep.mini.js]: http://casual-effects.com/markdeep/ -[v0.93.0]: https://github.com/gohugoio/hugo/releases/tag/v0.93.0 diff --git a/README.md.tmpl b/README.md.tmpl index 8c44774..f11b829 100644 --- a/README.md.tmpl +++ b/README.md.tmpl @@ -1,7 +1,7 @@ # GoAT: Go ASCII Tool - -![](https://github.com/github/docs/actions/workflows/test.yml/badge.svg) + +![](https://github.com/{{.GithubActor}}/goat/actions/workflows/make.yml/badge.svg) ## What **GoAT** Can Do For You @@ -42,7 +42,7 @@ with rows above and below. ## Installation ``` - $ go install github.com/{{.GithubUser}}/goat/cmd/goat@latest + $ go install github.com/{{.GithubActor}}/goat/cmd/goat@latest ``` @@ -133,12 +133,12 @@ The core engine of ```goat``` is accessible as a Go library package, for inclusi 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/). -A nicely formatted reference may be found at [pkg.go.dev](https://pkg.go.dev/github.com/{{.GithubUser}}/goat). +A nicely formatted reference may be found at [pkg.go.dev](https://pkg.go.dev/github.com/{{.GithubActor}}/goat). ### Installation ``` - $ go get -u github.com/{{.GithubUser}}/goat/ + $ go get -u github.com/{{.GithubActor}}/goat/ ``` ### Library Data Flow ![]({{.Root}}/goat.svg) @@ -150,13 +150,13 @@ source file [./goat.go](./goat.go). ### Project Tenets diff --git a/goat.svg b/goat.svg deleted file mode 100644 index ee43859..0000000 --- a/goat.svg +++ /dev/null @@ -1,239 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -p -o -r -c -e -l -a -i -n -A -P -I -B -u -i -l -d -A -n -d -W -r -i -t -e -S -V -G -( -) -A -S -C -I -I -- -a -r -t -M -a -r -k -d -o -w -n -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -· -p -l -u -m -b -i -n -g -A -P -I -C -a -n -v -a -s -{ -} -N -e -w -C -a -n -v -a -s -( -) -W -r -i -t -e -S -V -G -B -o -d -y -( -) -A -S -C -I -I -- -a -r -t -d -a -t -a -m -a -p -[ -x -, -y -] -r -u -n -e -S -V -G -{ -} -M -a -r -k -d -o -w -n -t -e -x -t -m -a -p -[ -x -, -y -] -r -u -n -e - - diff --git a/local.sh b/local.sh new file mode 100755 index 0000000..f12375f --- /dev/null +++ b/local.sh @@ -0,0 +1,5 @@ +#! /bin/sh + +# Render to HTML, for local inspection. +./markdown_to_html.sh README.md >README.html +./markdown_to_html.sh CHANGELOG.md >CHANGELOG.html diff --git a/make.sh b/make.sh index 3117777..feaaa80 100755 --- a/make.sh +++ b/make.sh @@ -4,14 +4,15 @@ # Certain output files should be committed to the SCM archive. # # Recall that an end-user eventually installing with 'go get ...' -# will trigger a compilation from source within the local environment. +# will trigger a compilation from source within the local environment, +# without help from this file. # XX Give this file a more descriptive name. set -e set -x usage () { printf "%s\n\n" "$*" - printf "usage: %s [-g GitHub_Username] [-w]\n" ${0##*/} + printf "usage: %s [-w]\n" ${0##*/} printf "\t%s\t%s\n" "" printf "\t%s\t%s\n" "$*" exit 1 @@ -22,12 +23,10 @@ svg_color_dark_scheme="#EEF" svg_color_light_scheme="#011" github_blue_color="#2F81F7" -# GOMOD=$(go env GOMOD) -# from_username=${GOMOD##*github.com/} -# githubuser=${from_username%%/*} -# -# X Is it acceptable to push to a PR branch files that refer to the owner's main branch? -githubuser=blampe +# Baseline case is run by Github Action, in which case GITHUB_ACTOR is defined by +# the environment. +# If running on local dev workstation, substitute in $USER instead. +: ${GITHUB_ACTOR:=$USER} TEST_ARGS= @@ -35,14 +34,13 @@ while getopts hg:iw flag do case $flag in h) usage "";; - g) githubuser=${OPTARG};; # Override guess based on GOMOD w) TEST_ARGS=${TEST_ARGS}" -write";; \?) usage "unrecognized option flag";; esac done tmpl_expand () { - go run ./cmd/tmpl-expand Root="." GithubUser=${githubuser} "$@" + go run ./cmd/tmpl-expand Root="." GithubActor=${GITHUB_ACTOR} "$@" } #tmpl_expand go.mod @@ -82,7 +80,3 @@ cat *.go | -svg-color-dark-scheme ${svg_color_dark_scheme} \ -svg-color-light-scheme ${svg_color_light_scheme} \ >goat.svg - -# Render to HTML, for local inspection. -./markdown_to_html.sh README.md >README.html -./markdown_to_html.sh CHANGELOG.md >CHANGELOG.html diff --git a/trees.mid-blue.svg b/trees.mid-blue.svg deleted file mode 100644 index a98875e..0000000 --- a/trees.mid-blue.svg +++ /dev/null @@ -1,110 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -1 -1 -1 -2 -2 -2 -3 -3 -3 -1 -2 -3 -4 -1 -2 -3 -4 -1 -2 -3 -4 -4 -4 -4 - -