trip logs / gnuvola


Trip Log 2017-07-07 h09

New ‘gtl2html’ is out and about.  Major version bump due to dropped cruft and change in GTL file format, as well.  Previously, we conflated several disparate concepts: upath, filename, various titles, and the nominal time of the trip log.  Now, this is all rationalized design-wise, and implementation-wise, the code rethwacked for further hacking happiness (more table-driven, cleaner internal interfaces, etc).  It's true what they say, three's the charm! 

Here are the user visible changes: 

And here is the output from ‘--version’ and ‘--help’ invocations: 

┌────────────────────────────────────────────────────────────────────────┐
│$ gtl2html --version                                                    │
│gtl2html 3.0                                                            │
│                                                                        │
│$ gtl2html --help                                                       │
│Usage: gtl2html --pp-cartouche-sets                                     │
│                                                                        │
│Display a Lisp/Scheme ‘read’able form (SET ...), where each SET         │
│has the form (X TL TM TR BL BM BR), w/ all elements a string of a       │
│single Unicode characater.  These are arranged like so:                 │
│                                                                        │
│  TL TM[...] TR                                                         │
│  X  (text)  X                                                          │
│  BL BM[...] BR                                                         │
│                                                                        │
│See "cartouche" top-level block, below.                                 │
│                                                                        │
│Usage: gtl2html [options] ARTICLE.gtl                                   │
│                                                                        │
│Read ARTICLE.gtl, and process it to produce ARTICLE.html.               │
│"GTL" stands for "GNUVOLA Trip Log".                                    │
│                                                                        │
│Options:                                                                │
│  -a, --atom          -- also generate ARTICLE.atom-entry               │
│  -v, --verbose       -- display some progress details to stderr        │
│                                                                        │
│Notes on the input (.gtl) format:                                       │
│                                                                        │
│* File has two parts, HEAD and BODY, separated by a form-feed           │
│  on a line of its own (i.e., "\f\n" in C language notation).           │
│  The first line of HEAD must start with the CONFIG-PLIST, a            │
│  Scheme/Lisp list of alternating keys (symbols) and values.            │
│  CONFIG-PLIST may occupy multiple lines.                               │
│                                                                        │
│  The unique required key at this time is ‘moment’.  Its value          │
│  must be a list of two strings (N-TIME PRETTY), where N-TIME is        │
│  the canonical name of the article, expressed as seconds since         │
│  epoch.  Here is an example of a complete CONFIG-PLIST:                │
│                                                                        │
│    (moment ("1501841920" "2017-08-04 10:18:40"))                       │
│                                                                        │
│  PRETTY is unused at the moment.  N-TIME is used to form               │
│  various titles (strings) in different contexts:                       │
│                                                                        │
│    (context)      (format string for ‘strftime’)                       │
│    xhtml-head     "%F h%H"                                             │
│    xhtml-body-h1  "Trip Log %F h%H"                                    │
│    upath          "/u/%Y/%m/%dh%H.html"                                │
│    atom           xhtml-body-h1                                        │
│                                                                        │
│  The last entry is an alias; it means to use ‘xhtml-body-h1’           │
│  format string in the ‘atom’ context.                                  │
│                                                                        │
│  Each line, starting from the one following the one where              │
│  CONFIG-PLIST ends, holds a "tag", which may contain spaces.           │
│  Case is significant in tags.                                          │
│                                                                        │
│* Top-level blocks (in BODY) are separated by two blank lines.          │
│  Each block can be one of:                                             │
│                                                                        │
│  * paragraph                                                           │
│    This is (possibly multi-line) plain text.  Conventionally,          │
│    each sentence ends w/ punctuation followed by non-breaking          │
│    space (U+A0) followed by whitespace (either SPC or LF).             │
│    It is rendered w/ enclosing { ‘<p>’, ‘</p>’ }.  Portions of         │
│    text that look like "<URI>" for ‘http’ and ‘https’ schemes          │
│    are converted to anchors of the form ‘<a href="URI">EURI</a>’,      │
│    where EURI is the "escaped URI" (see Other processing, below).      │
│    This is called "auto-anchor processing".                            │
│                                                                        │
│  * preformatted block                                                  │
│    This looks like                                                     │
│                                                                        │
│      ,pre                                                              │
│      TEXT                                                              │
│                                                                        │
│    i.e., ",pre" in column 0.  TEXT cannot include two blank            │
│    lines.  It is rendered w/ enclosing { ‘<pre>’, ‘</pre>’ }.          │
│    TEXT also undergoes auto-anchor processing.                         │
│                                                                        │
│  * cartouche                                                           │
│    This looks like                                                     │
│                                                                        │
│      ,cartouche                                                        │
│      X TEXT                                                            │
│                                                                        │
│    and there can be multiple lines of "X TEXT".  X determines          │
│    which "cartouche set" to use.  Here are the possibilities:          │
│                                                                        │
│      X  U+    Example                                                  │
│                                                                        │
│      │  2502  ┌─────┐                                                  │
│               │hello│                                                  │
│               └─────┘                                                  │
│      ┃  2503  ┏━━━━━┓                                                  │
│               ┃hello┃                                                  │
│               ┗━━━━━┛                                                  │
│      ║  2551  ╔═════╗                                                  │
│               ║hello║                                                  │
│               ╚═════╝                                                  │
│                                                                        │
│      ┋  250b  ▗┅┅┅┅┅▖                                                  │
│               ┋hello┋                                                  │
│               ▝┅┅┅┅┅▘                                                  │
│                                                                        │
│    The spaces between and X and TEXT (left padding) is mirrored        │
│    on the right.  Leading and trailing lines w/ only X (no TEXT)       │
│    determine the top and bottom padding, respectively.                 │
│    TEXT also undergoes auto-anchor processing.                         │
│                                                                        │
│  * image reference                                                     │
│    This looks like                                                     │
│                                                                        │
│      ,(~img 'src FILENAME)                                             │
│      TITLE                                                             │
│                                                                        │
│    where FILENAME is a string (enclosed in "") that names the image.   │
│    This is rendered w/ enclosing { ‘<img>’, ‘</img>’ }, and TITLE      │
│    is used for ‘alt’ and ‘title’ attributes.                           │
│                                                                        │
│  * outline                                                             │
│    This looks something like                                           │
│                                                                        │
│      - point 1                                                         │
│      - point 2                                                         │
│        - point 2.1                                                     │
│        - point 2.2                                                     │
│      - point 3                                                         │
│                                                                        │
│    i.e., zero or more pairs of SPC followed by ‘-’ (hyphen, U+2D)      │
│    followed by SPC followed by the rest of the line.  This is          │
│    rendered w/ enclosed (and nested) { ‘<ul>’, ‘</ul>’ }.              │
│    Each line also undergoes auto-anchor processing.                    │
│                                                                        │
│* A URI looks like                                                      │
│                                                                        │
│    ^A TEXT ^B URI ^C                                                   │
│                                                                        │
│  where ^A, ^B, ^C are control chars U+01, U+02, U+03, respectively.    │
│  Whitespace surrounding URI and TEXT is insignificant (discarded).     │
│  This is rendered w/ enclosing { ‘<a>’, ‘</a>’ }.                      │
│                                                                        │
│  Limitation: This construct is not recognized in cartouche blocks.     │
│                                                                        │
│Other processing:                                                       │
│                                                                        │
│* In addition to the "rendered" blurbs above, text is generally escaped:│
│                                                                        │
│    &   &amp;                                                           │
│    <   &lt;                                                            │
│    >   &gt;                                                            │
│                                                                        │
│  and text between ‘ (U+2018) and ’ (U+2019)                            │
│  is rendered w/ enclosing { ‘<code>’, ‘</code>’ }.                     │
│                                                                        │
│* All of the above is given a ‘xhtml-body-h1’ (context) title,          │
│  surrounded by a simple site-navigation paragraph and ‘hr’ (top);      │
│  and ‘hr’ and copyright paragraph (bottom) to form the HTML ‘body’.    │
│                                                                        │
│* In the HTML ‘head’, arrange to include:                               │
│                                                                        │
│   <link rel="stylesheet" href="/s/u.css" type="text/css" />            │
│                                                                        │
│  and prefix everything w/ proper XHTML 1.0 Strict boilerplate.         │
│                                                                        │
│ARTICLE.atom-entry is a sexp Atom ‘entry’ with several children:        │
│* ‘id’ is the full URI of ARTICLE.html.                                 │
│* ‘title’ is ‘atom’ (context) title                                     │
│* Each tag becomes a ‘category’ (zero or more).                         │
│* ‘link’ is like URI w/o the scheme and host prefix.                    │
│* ‘content’ is the XHTML subset (first paragraph).                      │
│  All URIs in this excerpt are canonicalized:                           │
│  - relative to absolute                                                │
│  - explicit site prefix                                                │
└────────────────────────────────────────────────────────────────────────┘

Copyright (C) 2017 Thien-Thi Nguyen