trip logs / gnuvola

Trip Log 2017-08-08 h17 -- Indices Style Upgrade Introduction

I've just “released” (internally) version 7.6 of the gnuvola site-maintenance software.  The most notable user-visible change is in the content of the Trip Log indices (for example, month, year, and top for this particular entry).  Firstly, the entry titles (not to be confused w/ page titles) have lost the highly redundant “Trip Log” prefix.  Next, the entries are ordered youngest first.  Lastly, the tags in lower portion of the page are ordered “most impactful” first, where impact is measured primarily by frequency — usage count — and secondarily by currency — most recent trip log that carries the tag.  (If those aspects are identical in two tags, they are ordered lexicographically by default.)  The rest of this trip log describes the motivation for the change (and how I feel about it), points out some overall features of the change, and then delves into the series of individually small changes in the code that altogether produce the user-visible change.  Yes, you heard right: patch-set pondering preceded by persnickety pronouncements!  :-D 

Actually, I've changed my mind.  After a bit of patience-reducing coffee, I've now decided to spread out the individual commit analyses (the “delving”) over a series of trip log entries.  This way offers better flow (lower latency), exercises the software in question (plus its programmer and technical writer) more, and allows for (although does not guarantee) more thorough treatment of the individual changes.  Quantity galore, and if all goes well, Quality, too. 

In any case, to follow along, feel free to download and peruse the accompanying tarball, which contains the patch-set (eight files) and overall diff.  I will refer to these as as “patch 1” through “patch 8” and “the diff”, respectively. 

“Hey ttn!  Back to the plan, man!” 

Right.  The motivation for upgrading the style of the indices was several-fold. 

On the surface, from a user pov, the previous style was tolerable at best (if in a charitable mood).  The redundancy (of “Trip Log” prefix) was an annoyance and a waste of bandwidth.  The oldest and least interesting entries cluttered the top of the page.  The tags were unhelpfully indistinguished.  These last two points are in direct opposition w/ the contemporary (and very prevalant) information presentation style: define what is “interesting” and show it at top of page.  The first point, on the other hand, is not felt quite as universally; many people (probably on fast connections) don't mind multi-megabyte images and malware vying w/ the text for their attention.  But, those people are not me, and I for one felt a twang of disgust and shame on that point, previously. 

BTW, in case you haven't seen the previous style, to help you appreciate its repugnance, here's an excerpt from ‘w3m -dump’:

Trip Logs


  • 2011
  • 2012
  • 2013
  • 2017


(by tags)

  • ELPA
      □ Trip Log 2017-04-04 h22
      □ Trip Log 2017-08-06 h07
  • GIGO
      □ Trip Log 2017-05-16 h15
      □ Trip Log 2017-06-08 h16
  • GNU
      □ Trip Log 2013-01-24 h09
      □ Trip Log 2017-03-31 h15
      □ Trip Log 2017-04-02 h22

Beneath the surface, another motivation for this upgrade was/is the opportunity to discuss (and meta-discuss) the change (and its motivation), i.e., to write this and the followup trip logs.  Basically, unabashed portfolio padding might help me find employment.  These writings (code, documentation, commentary) demonstrate technical and language proficiency, as well as consistency, transparency, and (I hope) engaging style.  Plus, writing builds courage.  Self-marketing is not as bad as I once thought; it's all much less insane if one believes in the product, you see... 

And that brings us to the core motivation: Hacking is fun, even though sometimes quite painful as I learn the truth of my limitations.  But what more can the eternal student ask for? 

Fine.  Now let's look at some features of this change.  [Mental note: IWBN if GTL had a workalike for Texinfo ‘@table’.] 

All changes occur in one file: ‘sub/tl-mkindex’.  You can see this in the diff as well as in every patch, in the section that shows a histogram and a count of the insertions and deletions.  Here's a summary of the latter, with delta (i.e., insertions minus deletions) and some other columns described below:

file    ins  del      𝚫      f     i

0001      6    8     -2     14     *
0002     21    9     12     30     *
0003      4   12     -8     16
0004      6    3      3      9     *
0005      6    4      2     10     *
0006      5    4      1      9
0007     28    3     25     31
0008     14    3     11     17     *
diff     75   31     44    106

Column ‘f’ is the “footprint” (insertions plus deletions) of the change.  A low footprint indicates a very focused change.  That's desirable because the wider the focus, the higher the probability that a bug can creep in. 

Column ‘i’ marks changes that are “internal”, i.e., not resulting in change of user-visible behavior.  Internal changes typically refactor or move abstractions, paving the way for a cleaner, lower footprint, user-visible change.  In this patch-set, the internal changes outnumber the user-visible changes 5 to 3.  Strangely, patch 8 is internal but there is no user-visible patch following — so how can it “pave the way” for anything?  More on that later! 

The last thing to note is that the commit messages are highly stylized.  In fact, they adhere to the GNU Coding Standards for Change Logs, adapted for commit message format (i.e., requiring ‘TITLE’ and discarding the bol ‘TAB’ char). 

Attentive readers will scoff at “last thing to note” hand-waving and also note some glaring omissions: testing and documentation!  My excuse is that this change regards style and not functionality, and since style was never documented in the first place, neither should changes in style be documented.  Still, I will admit that the tags sorting algorithm (for example) is important (and bug-prone) enough to warrant testing and documentation.  Hmmm, where to draw the line?  Maybe a good topic for a followup? 

Copyright (C) 2017 Thien-Thi Nguyen