Skip to content

Commit 3880208

Browse files
dmullisdmullis
authored
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>
1 parent 07bb911 commit 3880208

File tree

5 files changed

+239
-20
lines changed

5 files changed

+239
-20
lines changed

‎README.md

Lines changed: 44 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,14 @@
11
# GoAT: Go ASCII Tool
22

3+
<!-- Github-specific status icons-->
4+
![](https://github.com/github/docs/actions/workflows/test.yml/badge.svg)
5+
36
## What **GoAT** Can Do For You
47

58
- From a chunky ASCII-art source drawing, render polished, graphically-rich [SVG](#complicated),
6-
with the [goat](./cmd/goat) CLI command.
9+
with the [goat](#installation) CLI command.
10+
11+
<!-- https://github.com/dmullis/goat/tree/main#installation -->
712

813
- Tie together all three of:
914
1. Your code's major data structures or abstract data/control flows.
@@ -37,10 +42,11 @@ with rows above and below.
3742

3843
## Installation
3944
```
40-
$ go install github.com/blampe/goat/cmd/goat@latest
45+
$ go install github.com/blampe/goat/cmd/goat@latest
4146
```
47+
<!-- https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections#creating-a-collapsed-section -->
4248

43-
## Examples
49+
## Example Graphics
4450

4551
Here are some snippets of
4652
GoAT-formatted UTF-8
@@ -67,6 +73,18 @@ GoAT's [README.md](README.md), then finally rendered to HTML ```<img>``` element
6773
```
6874
![](./examples/trees.svg)
6975

76+
### Trees -- mid-range color value
77+
Setting a foreground color in the middle of the possible range of value or luminance
78+
is one way to work around a limitation of certain browsers e.g. Safari.
79+
Safari does not support inheritance of
80+
the [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
81+
CSS property by
82+
`goat`'s output `<svg>` element
83+
from within an enclosing `<img>` element such as are generated by Markdown.
84+
85+
86+
![](./trees.mid-blue.svg)
87+
7088
### Overlaps
7189
```
7290
@@ -141,7 +159,6 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character,
141159
![](./examples/large-nodes.svg)
142160

143161
### Small Grids
144-
![](./examples/small-grids.svg)
145162
```
146163
___ ___ .---+---+---+---+---. .---+---+---+---. .---. .---.
147164
___/ \___/ \ | | | | | | / \ / \ / \ / \ / | +---+ |
@@ -153,6 +170,7 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character,
153170
154171
155172
```
173+
![](./examples/small-grids.svg)
156174

157175
### Big Grids
158176
```
@@ -210,13 +228,33 @@ The core engine of ```goat``` is accessible as a Go library package, for inclusi
210228
code of your own.
211229
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/).
212230

213-
### library Data Flow
231+
A nicely formatted reference may be found at [pkg.go.dev](https://pkg.go.dev/github.com/blampe/goat).
232+
233+
### Installation
234+
235+
```
236+
$ go get -u github.com/blampe/goat/
237+
```
238+
### Library Data Flow
214239
![](./goat.svg)
215240

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

219-
#### Project Tenets
244+
#### Auto-formatted API docs
245+
246+
<!--
247+
XX XX May need a Github Action to do this substitution at "push" time.
248+
[![resource non-responsive](https://pkg.go.dev/badge/github.com/blampe/goat)](https://pkg.go.dev/github.com/blampe/goat)
249+
-->
250+
251+
<!--
252+
The scraping of GitHub by godocs.io (see https://sr.ht) does NOT include README.md;
253+
whereas Google's pkg.go.dev does do so, and apparently runs its own variant of GFM processing :-/
254+
[![resource non-responsive](https://godocs.io/github.com/blampe/goat?status.svg)](https://godocs.io/github.com/blampe/goat)
255+
-->
256+
257+
### Project Tenets
220258

221259
1. Utility and ease of integration into existing projects are paramount.
222260
2. Compatibility with MarkDeep desired, but not required.

‎README.md.tmpl

Lines changed: 44 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,14 @@
11
# GoAT: Go ASCII Tool
22

3+
<!-- Github-specific status icons-->
4+
![](https://github.com/github/docs/actions/workflows/test.yml/badge.svg)
5+
36
## What **GoAT** Can Do For You
47

58
- From a chunky ASCII-art source drawing, render polished, graphically-rich [SVG](#complicated),
6-
with the [goat](./cmd/goat) CLI command.
9+
with the [goat](#installation) CLI command.
10+
11+
<!-- https://github.com/dmullis/goat/tree/main#installation -->
712

813
- Tie together all three of:
914
1. Your code's major data structures or abstract data/control flows.
@@ -37,10 +42,11 @@ with rows above and below.
3742

3843
## Installation
3944
```
40-
$ go install github.com/{{.GithubUser}}/goat/cmd/goat@latest
45+
$ go install github.com/{{.GithubUser}}/goat/cmd/goat@latest
4146
```
47+
<!-- https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections#creating-a-collapsed-section -->
4248

43-
## Examples
49+
## Example Graphics
4450

4551
Here are some snippets of
4652
GoAT-formatted UTF-8
@@ -58,6 +64,18 @@ GoAT's [README.md](README.md), then finally rendered to HTML ```<img>``` element
5864
```
5965
![]({{.Root}}/examples/trees.svg)
6066

67+
### Trees -- mid-range color value
68+
Setting a foreground color in the middle of the possible range of value or luminance
69+
is one way to work around a limitation of certain browsers e.g. Safari.
70+
Safari does not support inheritance of
71+
the [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
72+
CSS property by
73+
`goat`'s output `<svg>` element
74+
from within an enclosing `<img>` element such as are generated by Markdown.
75+
76+
77+
![]({{.Root}}/trees.mid-blue.svg)
78+
6179
### Overlaps
6280
```
6381
{{.overlaps_txt}}
@@ -90,10 +108,10 @@ Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character,
90108
![]({{.Root}}/examples/large-nodes.svg)
91109

92110
### Small Grids
93-
![]({{.Root}}/examples/small-grids.svg)
94111
```
95112
{{.small_grids_txt}}
96113
```
114+
![]({{.Root}}/examples/small-grids.svg)
97115

98116
### Big Grids
99117
```
@@ -115,13 +133,33 @@ The core engine of ```goat``` is accessible as a Go library package, for inclusi
115133
code of your own.
116134
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/).
117135

118-
### library Data Flow
136+
A nicely formatted reference may be found at [pkg.go.dev](https://pkg.go.dev/github.com/{{.GithubUser}}/goat).
137+
138+
### Installation
139+
140+
```
141+
$ go get -u github.com/{{.GithubUser}}/goat/
142+
```
143+
### Library Data Flow
119144
![]({{.Root}}/goat.svg)
120145

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

124-
#### Project Tenets
149+
#### Auto-formatted API docs
150+
151+
<!--
152+
XX XX May need a Github Action to do this substitution at "push" time.
153+
[![resource non-responsive](https://pkg.go.dev/badge/github.com/{{.GithubUser}}/goat)](https://pkg.go.dev/github.com/{{.GithubUser}}/goat)
154+
-->
155+
156+
<!--
157+
The scraping of GitHub by godocs.io (see https://sr.ht) does NOT include README.md;
158+
whereas Google's pkg.go.dev does do so, and apparently runs its own variant of GFM processing :-/
159+
[![resource non-responsive](https://godocs.io/github.com/{{.GithubUser}}/goat?status.svg)](https://godocs.io/github.com/{{.GithubUser}}/goat)
160+
-->
161+
162+
### Project Tenets
125163

126164
1. Utility and ease of integration into existing projects are paramount.
127165
2. Compatibility with MarkDeep desired, but not required.

‎make.sh

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,9 @@
33
# Run all tests, and all pre-compilation build steps.
44
# Certain output files should be committed to the SCM archive.
55
#
6-
# Recall that 'go get ...' performs compilation-proper for go, within
7-
# the user's local environment.
6+
# Recall that an end-user eventually installing with 'go get ...'
7+
# will trigger a compilation from source within the local environment.
8+
# XX Give this file a more descriptive name.
89

910
set -e
1011
set -x
@@ -19,10 +20,14 @@ usage () {
1920
# Define colors for SVG ~foreground~ seen on Github front page.
2021
svg_color_dark_scheme="#EEF"
2122
svg_color_light_scheme="#011"
23+
github_blue_color="#2F81F7"
2224

23-
GOMOD=$(go env GOMOD)
24-
from_username=${GOMOD##*github.com/}
25-
githubuser=${from_username%%/*}
25+
# GOMOD=$(go env GOMOD)
26+
# from_username=${GOMOD##*github.com/}
27+
# githubuser=${from_username%%/*}
28+
#
29+
# X Is it acceptable to push to a PR branch files that refer to the owner's main branch?
30+
githubuser=blampe
2631

2732
TEST_ARGS=
2833

@@ -49,9 +54,19 @@ tmpl_expand () {
4954
# this script with "TEST_ARGS=-write" first on the command line.
5055
# X Results are used as "golden" standard for GitHub-side regression tests --
5156
# so arguments here must not conflict with those in "test.yml".
57+
# XX How to share a single arg list shared between the two i.e. "DRY"?
5258
go test -run . -v \
5359
${TEST_ARGS}
5460

61+
# Illustrate a workaround for lack of support in certain browsers e.g. Safari for
62+
# inheritance of CSS property 'color-scheme' from <img> elements downward to nested
63+
# <svg> elements.
64+
# - https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
65+
go run ./cmd/goat <examples/trees.txt \
66+
-svg-color-dark-scheme ${github_blue_color} \
67+
-svg-color-light-scheme ${github_blue_color} \
68+
>trees.mid-blue.svg
69+
5570
# build README.md
5671
tmpl_expand <README.md.tmpl >README.md \
5772
$(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

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,33 @@
11
#! /bin/sh
22
#
3-
# For local test of markdown generation, use a standalone Markdown-to-HTML processer.
3+
# For local test of markdown generation, use a standalone Markdown-to-HTML processor.
4+
#
5+
# XX XX Plan for support of Goat diagrams embedded in Markdown locally
6+
# generated for production e.g. upload to a non-GH server:
7+
# 1. Go filter preprocesses .md file.
8+
# 2. Filter extracts and renders Goat diagrams to out-of-line** SVG files.
9+
# 3. Filter replaces inline ASCII Goat diagram with relative link to SVG.
10+
#
11+
# ** SVG content unlike PNG et al. is of course natively ASCII, but GFM apparently
12+
# nevertheless will not accept it inline, embedded.
13+
# c.f. https://github.github.com/gfm/#images
414

515
set -e
616
#set -x
717

818
svg_color_light_scheme="#320"
919
svg_color_dark_scheme="#FEE"
1020

11-
# XX An alternative to 'marked', for consideration:
12-
# https://github.com/gomarkdown/mdtohtml
21+
# X Alternatives to 'marked':
22+
# - https://github.com/yuin/goldmark
23+
# X X https://github.com/abhinav/goldmark-toc
24+
# => Respin this very script as a Go CLI app, incorporating above libraries.
25+
# - https://github.com/remarkjs/remark
26+
# XX Coded in JS.
27+
# - https://github.com/remarkjs/remark-toc
28+
# - https://github.com/gomarkdown/markdown
29+
# XX No Table-Of-Contents support found.
30+
# - CLI: https://github.com/gomarkdown/mdtohtml
1331

1432
# See https://github.github.com/gfm/#introduction
1533
#

‎trees.mid-blue.svg

Lines changed: 110 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)