diff --git a/README.md b/README.md index f12cb3c..4b8f402 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,14 @@ # 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](./cmd/goat) CLI command. + with the [goat](#installation) CLI command. + + - Tie together all three of: 1. Your code's major data structures or abstract data/control flows. @@ -37,10 +42,11 @@ with rows above and below. ## Installation ``` -$ go install github.com/blampe/goat/cmd/goat@latest + $ go install github.com/blampe/goat/cmd/goat@latest ``` + -## Examples +## Example Graphics Here are some snippets of GoAT-formatted UTF-8 @@ -67,6 +73,18 @@ GoAT's [README.md](README.md), then finally rendered to HTML `````` element ``` ![](./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 ``` @@ -141,7 +159,6 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character, ![](./examples/large-nodes.svg) ### Small Grids -![](./examples/small-grids.svg) ``` ___ ___ .---+---+---+---+---. .---+---+---+---. .---. .---. ___/ \___/ \ | | | | | | / \ / \ / \ / \ / | +---+ | @@ -153,6 +170,7 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character, ``` +![](./examples/small-grids.svg) ### Big Grids ``` @@ -210,13 +228,33 @@ 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/). -### library Data Flow +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). -#### Project Tenets +#### 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. diff --git a/README.md.tmpl b/README.md.tmpl index 6597987..8c44774 100644 --- a/README.md.tmpl +++ b/README.md.tmpl @@ -1,9 +1,14 @@ # 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](./cmd/goat) CLI command. + with the [goat](#installation) CLI command. + + - Tie together all three of: 1. Your code's major data structures or abstract data/control flows. @@ -37,10 +42,11 @@ with rows above and below. ## Installation ``` -$ go install github.com/{{.GithubUser}}/goat/cmd/goat@latest + $ go install github.com/{{.GithubUser}}/goat/cmd/goat@latest ``` + -## Examples +## Example Graphics Here are some snippets of GoAT-formatted UTF-8 @@ -58,6 +64,18 @@ GoAT's [README.md](README.md), then finally rendered to HTML `````` element ``` ![]({{.Root}}/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. + + +![]({{.Root}}/trees.mid-blue.svg) + ### Overlaps ``` {{.overlaps_txt}} @@ -90,10 +108,10 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character, ![]({{.Root}}/examples/large-nodes.svg) ### Small Grids -![]({{.Root}}/examples/small-grids.svg) ``` {{.small_grids_txt}} ``` +![]({{.Root}}/examples/small-grids.svg) ### Big Grids ``` @@ -115,13 +133,33 @@ 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/). -### library Data Flow +A nicely formatted reference may be found at [pkg.go.dev](https://pkg.go.dev/github.com/{{.GithubUser}}/goat). + +### Installation + +``` + $ go get -u github.com/{{.GithubUser}}/goat/ +``` +### Library Data Flow ![]({{.Root}}/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 +#### 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. diff --git a/make.sh b/make.sh index c26f84b..3117777 100755 --- a/make.sh +++ b/make.sh @@ -3,8 +3,9 @@ # Run all tests, and all pre-compilation build steps. # Certain output files should be committed to the SCM archive. # -# Recall that 'go get ...' performs compilation-proper for go, within -# the user's local environment. +# Recall that an end-user eventually installing with 'go get ...' +# will trigger a compilation from source within the local environment. +# XX Give this file a more descriptive name. set -e set -x @@ -19,10 +20,14 @@ usage () { # Define colors for SVG ~foreground~ seen on Github front page. 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%%/*} +# 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 TEST_ARGS= @@ -49,9 +54,19 @@ tmpl_expand () { # this script with "TEST_ARGS=-write" first on the command line. # X Results are used as "golden" standard for GitHub-side regression tests -- # so arguments here must not conflict with those in "test.yml". +# XX How to share a single arg list shared between the two i.e. "DRY"? go test -run . -v \ ${TEST_ARGS} +# Illustrate a workaround for lack of support in certain browsers e.g. Safari for +# inheritance of CSS property 'color-scheme' from elements downward to nested +# elements. +# - https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme +go run ./cmd/goat trees.mid-blue.svg + # build README.md tmpl_expand README.md \ $(bash -c 'echo ./examples/{trees,overlaps,line-decorations,line-ends,dot-grids,large-nodes,small-grids,big-grids,complicated}.{txt,svg}') diff --git a/markdown_to_html.sh b/markdown_to_html.sh index 2d93482..94adce2 100755 --- a/markdown_to_html.sh +++ b/markdown_to_html.sh @@ -1,6 +1,16 @@ #! /bin/sh # -# For local test of markdown generation, use a standalone Markdown-to-HTML processer. +# For local test of markdown generation, use a standalone Markdown-to-HTML processor. +# +# XX XX Plan for support of Goat diagrams embedded in Markdown locally +# generated for production e.g. upload to a non-GH server: +# 1. Go filter preprocesses .md file. +# 2. Filter extracts and renders Goat diagrams to out-of-line** SVG files. +# 3. Filter replaces inline ASCII Goat diagram with relative link to SVG. +# +# ** SVG content unlike PNG et al. is of course natively ASCII, but GFM apparently +# nevertheless will not accept it inline, embedded. +# c.f. https://github.github.com/gfm/#images set -e #set -x @@ -8,8 +18,16 @@ set -e svg_color_light_scheme="#320" svg_color_dark_scheme="#FEE" -# XX An alternative to 'marked', for consideration: -# https://github.com/gomarkdown/mdtohtml +# X Alternatives to 'marked': +# - https://github.com/yuin/goldmark +# X X https://github.com/abhinav/goldmark-toc +# => Respin this very script as a Go CLI app, incorporating above libraries. +# - https://github.com/remarkjs/remark +# XX Coded in JS. +# - https://github.com/remarkjs/remark-toc +# - https://github.com/gomarkdown/markdown +# XX No Table-Of-Contents support found. +# - CLI: https://github.com/gomarkdown/mdtohtml # See https://github.github.com/gfm/#introduction # diff --git a/trees.mid-blue.svg b/trees.mid-blue.svg new file mode 100644 index 0000000..a98875e --- /dev/null +++ b/trees.mid-blue.svg @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +1 +1 +1 +2 +2 +2 +3 +3 +3 +1 +2 +3 +4 +1 +2 +3 +4 +1 +2 +3 +4 +4 +4 +4 + +