trip logs / gnuvola


Trip Log 2017-05-16 h15

OK, time to get back to the second week's worth of trip logs.  In the intervening month, I've re-examined the motivation underlying this particular spew campaign (i.e., get a job) and found it lacking soul (of course).  However, because I'm an incorrigible opportunist (always trying to kill N birds w/ one stone), I've decided to look at it as an opportunity to inject some (soul) into the world.  Silence is death, and so far I'm not dead (yet). 

Many years ago, Robert M. Pirsig wrote ZAMM, and since then I've read it quite a few times, initially out of boredom (you know: “of youth”), and later on as a form of meditation.  I can spew forth here about how this book inspired me, bla bla bla (and maybe I will do so someday), but for the moment, all you need to know is that the book's protagonist is a technical writer who comes to conclude that Quality is the moment of perception. 

Huh?  Hold that thought! 

Jumping sideways now, I present Guile-WWW and the recent commit ([doc] Add blank lines.), mentioned in the release 2.40 announcement (search for “spacious”). 

The first thing to note is that the patch indeed shows thirteen new lines, but none of them are actually blank!  “But ttn, how ba{l}dly you lie!”  Well, actually, the explanation is simple: this is an example of the hated class of human artifacts called “generated API documentation”.  The word “blank” describes what the user sees, and for that to happen, the writer must make changes to the documentation source — in this case, adding Scheme comments — that work w/ the generation programs.  Likewise, the ChangeLog file (also mentioned in the patch, above) is for the user primarily, and for the writer secondarily.  Granted, not many people read ChangeLog files these days, but principles are principles... 

The second thing to notice is the location of the blank lines: for the most part (eleven instances) immediately before ‘@item’, once before ‘@table’ and once in between stanzas in an ‘@example’ block.  Here's how the ‘http.scm’-sourced docs looked in Guile-WWW 2.39 (excerpt from ‘receive-response’): 

      HGET is a procedure that takes one arg SEL.
      ‘#f’
           Return the headers (alist).
      ‘#t’
           Return the name normalization procedure (involving S2S,
           described above).
      STRING
           Normalize it; return the associated header value.
      SYMBOL
           Return the associated header value.

and here's how it looks in Guile-WWW 2.40: 

      HGET is a procedure that takes one arg SEL.

      ‘#f’
           Return the headers (alist).

      ‘#t’
           Return the name normalization procedure (involving S2S,
           described above).

      STRING
           Normalize it; return the associated header value.

      SYMBOL
           Return the associated header value.

“But ttn, what are you talking about?  How spacious the docs are depends on your browser, no?  And btw, I snagged the previous version of the docs and they seem to be the same as the current version.  More lies!” 

Well the answer to that lies in the third thing to note.  The improved experience is for users of the documentation in Info format.  HTML format and PDF format have long enjoyed the spaciousness, why not include Info format, as well?  All it takes is a few “blank” lines. 

The nice thing about this change is that it actually improves readability of the source documentation (Scheme comments) as well.  So, win-win.  A case of gumption-in-gumption-out, perhaps?  :-D


Copyright (C) 2017 Thien-Thi Nguyen