Generate files from Coga Design Guide

[SteveALee]

First pass at generating pages from the Content Usable Design Guide source

• Web pages preview
• TR Note doc preview
• HTLM + respec source code index.html, included files for objectives and patterns
• Jekyll source page generate script
• The Jekyll front-matter is manually added verbatim in a <pre> element
• The generate process reformats the the source include for jeckyll
• Generated files were manually copied from the coga repo to here.

Notes

• the basic inclusion scheme and generation are proven
• source filenames are arbitrary
• generate script transforms the <pre> element to valid Jekyll front-matter. Is currently a fragile hack.
  • Removes the initial header used by respec as the front-matter title is used
  • <pre> was chosen as tooling should not reformat (I hope). Also alows easy transform to front-matter. Possibly could have used <script> element as yaml theoretically supports json but could be fragile (even though removed by respec)
  • yaml format is NOT supported by respec but it's irrelevant and descriptive
  • used a bash script for portability

Open questions

• [x] should we add short descriptive suffix to included files make it easier to browse them?
• [x] should we have better URIs as o1p2 is not friendly - could add permalink to front-matter (manually or generate from filename or title)?

• 14

• 15

• [x] adjust header levels
• [x] handle header
  • [x] if we are not using the header in the include files it could possibly be moved to index file?~~
  • [x] could generate title from header - probably better to have them both as might diverge?~~
• [x] sorting is (probably) by ref so o1p1 suffix is probably good (what if > 9 patterns)?
• [x] can we move the _objectives and _patterns dirs to be under content?
• [x] should we make it clearer that the headings are objectives on the all patterns page? make them links?
  • [x] do the patterns even need to be ordered? They are not numbered. Should they be in same order as the note?~~

Next Steps

• [x] resolve above questions
• [x] improve parsing, replace sed?
  • [x] Could allow heading to be HTML so file can be either MD or HTML
• [x] complete all includes
• [x] add automatic file transfer (GitHub Action?). Decide required trigger / lifecycle

Issues

• The "file an issue" link in footer goes to wai-coga-design-guide not coga

[SteveALee]

A nice discovery for parsing is https://www.w3.org/Tools/HTML-XML-utils/ (current maintainer is Bert). Installable for debian. Man pages provided. Especially interesting are:

• hxextract (1) - extract selected elements
• hxremove (1) - remove selected elements from an XML file
• hxselect (1) - extract elements that match a (CSS) selector

maybe:

• hxcopy (1) - copy an HTML file while preserving relative links
• hxnormalize (1) - pretty-print an HTML file
• hxclean (1) - apply heuristics to correct an HTML file
• hxprune (1) - remove marked elements from an HTML file

eg:

cat about.html | hxselect -c pre[class~="yaml"][class~="remove"] # has leading \n
cat about.html | hxremove h2:first-of-type, pre

[SteveALee]

• Decide to switch to Mark down format - except still using <pre> rather than `` so can use theclass=remove`.
• sed easily does all the transformation we need.

[SteveALee]

@hidde (CC @michael-n-cooper @nitedog) New improved script and more pages added. Source files can be MD or HTML