trip logs / gnuovla

Trip Log 2017-03-30 h12 -- TTN: Hacker Cum Technical Writer

This is the first in a series of trip logs intended to impress potential employers.  (In other words, it's time for ttn to Get A Job.)  The method is quite simple: Point to or directly display various pieces of portfolio and talk a bit about why you (potential employer) might consider such work to be aligned w/ your efforts.  At the end of this series (maybe two weeks' worth, if all goes well), I will send a CV to those potential employers that interest me the most, pointing back to these writings.  In the meantime, let's see what kind of foolishness lies in store... 

“But ttn, what do you mean by portfolio?”  Glad you asked.  The answer all comes down to what I do. 

I write, technically. 

Most of what I have written has been for a machine audience (software), but over the last two years or so, I have written more and more for humans (documentation) as well.  I enjoy both kinds of writing (not to mention doggerel, cough cough).  So, w/o further ado (rather, we'll spread the philosophical mumblings out over the series), here is the first portfolio item: the ‘gtl2html --version’ and ‘gtl2html --help’ output. 

$ gtl2html --version
gtl2html 1.2

$ gtl2html --help
Usage: gtl2html [options] ARTICLE.gtl

Read ARTICLE.gtl, and process it to produce ARTICLE.html.
Generate ARTICLE.atom-entry.  "GTL" stands for "GNUVOLA Trip Log".

  -t, --title TITLE   -- set the document title to "Trip Log TITLE"
                         [default: "UNTITLED"]

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).
  In HEAD, each line 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>’ }.

  * preformatted block
    This looks like


    i.e., ",pre" in column 0.  TEXT cannot include two blank
    lines.  It is rendered w/ enclosing { ‘<pre>’, ‘</pre>’ }.

  * cartouche
    This looks like

      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  ┌─────┐
      ┃  2503  ┏━━━━━┓
      ║  2551  ╔═════╗

      ┋  250b  ▗┅┅┅┅┅▖

    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.

  * image reference
    This looks like

      ,(~img 'src FILENAME)

    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>’ }.

* A URL looks like

    ^A URL ^B TEXT ^C

  where ^A, ^B, ^C are control chars U+01, U+02, U+03, respectively.
  Whitespace surrounding URL and TEXT is insignificant (discarded).
  This is rendered w/ enclosing { ‘<a>’, ‘</a>’ }.

Other processing:

* In addition to the "rendered" blurbs above, text is generally escaped:

    &   &amp;
    <   &lt;
    >   &gt;

  and text between ‘ (U+2018) and ’ (U+2019), as well as text between
  double quotes (U+22) are rendered w/ enclosing { ‘<code>’, ‘</code>’ }.

* All of the above is given a ‘h1’ title "Trip Log 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 URL of ARTICLE.html.
* ‘title’ is "Trip Log TITLE".
* Each tag becomes a ‘category’ (zero or more).
* ‘link’ is like URL w/o the scheme and host prefix.
* ‘summary’ is the XHTML subset (first paragraph) of ARTICLE.html.

Let's hope ‘gtl2html’ is actually able to process this file so that you can see it!  How does it compare to the previous, casual documentation

It's more recent.  I wrote it this morning, largely having forgotten about the previous effort (so it goes).  Thus, it benefits from the training as a technical writer I have received in the five years since. 

It's more complete.  It covers all the workings of ‘gtl2html’, not just the input format.  This includes command-line options, general processing steps, top-level layout, and Atom entry generation. 

It's more accessible.  The ‘cartouche’ table shows exactly what you get; no need to imagine how ‘CARTOUCHE-SETS’ would play out.  Moreover, the program itself provides the documentation, on demand. 

It's more maintainable.  The documentation is now much closer to the source code.  Future modifications to the source and the documentation are highly likely to be synchronized (presuming I maintain my personal nitpicking practices). 

To close, a meta-plus-point of this particular portfolio item is that, including it here in this trip log entry exercises ‘gtl2html’.  Use it or lose it! 

Copyright (C) 2017 Thien-Thi Nguyen