GHPages Website Maintenance

[tajmone]

A new thread dedicated to the nitty gritty of the new GHPages website.

Build Scripts

If I've understood correctly how the publish.sh scripts work, they deal exclusively with committing to the orphan branch the converted documents — i.e. they will rely on whatever build script(s) are provided for any document for the conversion work.

This should mean that I'm free to update and improve the build scripts — e.g. adding syntax highlighting to the Alan Design doc, etc.

I'm asking this since I'm about to start getting rid of the various Batch scripts and provide Bash only scripts (where possible, which currently might not be the case with asciidoctor-fopub — see #66), and possible improve them too.

Documents Version Info

Another consideration here concerns the -a reproducible attribute which we've been using so far (either in the conversion script or in the source doc attributes) to prevent meaningless changes when rebuilding unchanged docs — i.e. to prevent Asciidoctor to add info about the date and time of the conversion.

Since we're no longer tracking built documents, we could simply disable the reproducible attribute/option, which will automatically add the conversion date and time in the HTML footer (and possibly somewhere in the PDF too, although I'm not sure).

This would be a useful reference for end users who have downloaded multiple copies of a same document and need to quickly decide which is the latest version.

Some documents might require extra info, e.g. the ALAN Manual might require to set some attributes regarding the Beta vs Alpha SDK, which we can easily handle by conditionally set an attribute in build.sh (based on the branch) and then use that attribute in the ADoc source directly, or create some conditional preprocessor directives that can output different text based on the attribute's value.

But removing the reproducible attribute/option (from scripts and ADoc sources headers) would be a good starting point to move in that direction, with very little effort.