For blampe 5.0 -- bug #23 (#24)

Document workaround for #23: Safari-specific limit to CSS property inheritance
    
Fix #20 and #21.

Add a Github-specific status badge.

---------

Co-authored-by: dmullis <dmullis>

README.md

@@ -1,9 +1,14 @@
 # GoAT: Go ASCII Tool
 
+<!-- Github-specific status icons-->
+![](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.
+
+<!-- https://github.com/dmullis/goat/tree/main#installation -->
 
 - 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
 ```
+<!-- https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections#creating-a-collapsed-section -->
 
-## 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 ```<img>``` 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 `<svg>` element
+from within an enclosing `<img>` 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
+
+<!--
+ XX XX  May need a Github Action to do this substitution at "push" time.
+[![resource non-responsive](https://pkg.go.dev/badge/github.com/blampe/goat)](https://pkg.go.dev/github.com/blampe/goat)
+-->
+
+<!--
+ The scraping of GitHub by godocs.io (see https://sr.ht) does NOT include README.md;
+ whereas Google's pkg.go.dev does do so, and apparently runs its own variant of GFM processing :-/ 
+[![resource non-responsive](https://godocs.io/github.com/blampe/goat?status.svg)](https://godocs.io/github.com/blampe/goat)
+-->
+
+### Project Tenets
 
 1. Utility and ease of integration into existing projects are paramount.
 2. Compatibility with MarkDeep desired, but not required.

README.md.tmpl

@@ -1,9 +1,14 @@
 # GoAT: Go ASCII Tool
 
+<!-- Github-specific status icons-->
+![](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.
+
+<!-- https://github.com/dmullis/goat/tree/main#installation -->
 
 - 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
 ```
+<!-- https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections#creating-a-collapsed-section -->
 
-## 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 ```<img>``` 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 `<svg>` element
+from within an enclosing `<img>` 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
+
+<!--
+ XX XX  May need a Github Action to do this substitution at "push" time.
+[![resource non-responsive](https://pkg.go.dev/badge/github.com/{{.GithubUser}}/goat)](https://pkg.go.dev/github.com/{{.GithubUser}}/goat)
+-->
+
+<!--
+ The scraping of GitHub by godocs.io (see https://sr.ht) does NOT include README.md;
+ whereas Google's pkg.go.dev does do so, and apparently runs its own variant of GFM processing :-/ 
+[![resource non-responsive](https://godocs.io/github.com/{{.GithubUser}}/goat?status.svg)](https://godocs.io/github.com/{{.GithubUser}}/goat)
+-->
+
+### Project Tenets
 
 1. Utility and ease of integration into existing projects are paramount.
 2. Compatibility with MarkDeep desired, but not required.

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 <img> elements downward to nested
+# <svg> elements.
+#  - https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
+go run ./cmd/goat <examples/trees.txt \
+   -svg-color-dark-scheme ${github_blue_color} \
+   -svg-color-light-scheme ${github_blue_color} \
+   >trees.mid-blue.svg
+
 # build README.md
 tmpl_expand <README.md.tmpl >README.md \
    $(bash -c 'echo ./examples/{trees,overlaps,line-decorations,line-ends,dot-grids,large-nodes,small-grids,big-grids,complicated}.{txt,svg}')

markdown_to_html.sh

@@ -1,15 +1,33 @@
 #! /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
 
 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
 #