trip logs / gnuvola


Trip Log 2017-05-22 h21

Last week, I wrote (initial, followup) about adding blank lines to documentation in Info format.  No love for PDF or HTML format, however, and in the end, a lot of work for “mere” aesthetics, maybe (or maybe not) in the eye of the beholder...  Today, I veer both towards and away from a more broadly-perceptible change: adding index entries to the documentation of two projects: Guile-BAUX and GNU RCS.

First, why “both towards and away from” (which I blame on the coffee)?  In this day and age, with full-text search a click and a TCP round-trip (or two) away, it's easy for people to forget that documents sometimes have an index, and that there is (could be) some value to using (if not outright perusing) it.  All you need is HTML and a promiscuous — or inept, makes no difference — enough ‘robots.txt’ file, amirite?  LMGTFY is the nod, a hyperlink the currency, and any friction in the diction is already three swipes past prime.  So, tldr: “away from” derives from “Doc index in 2017 — srsly?!” 

On the other hand (and by the same technological token), the instant gratification described above works well only when there is (a) sufficient alignment of interests between the search services and the document author; and (b) shared understanding of the document (organization, underlying assumptions, point of view).  Adding index entries helps with (b) by removing uncertainty, especially for the search services, which use precisely imprecise methods to try to “understand” things.  When the search services achieve (b) more easily, that helps with (a) as well.  So, this explains (partially) the “towards” side of the remark. 

The rest of the “towards” side explanation can be summed up with the word “offline”.  No search services, no problem!  No web browser, no problem!  No network, no problem!  No computer, no problem!  (OK, that last one gets only half a point — it presumes hardcopy.) 

Anyway, indexed documentation is a Good Thing, and adding index entries to documentation is what this tarball evidences.  It contains two Org mode files:

$ tar tf add-index-entries.tar.gz
guile-baux.org
rcs.org

Each file contains one (Guile-BAUX) or more (GNU RCS) patches, each the output of ‘git show <commitid>’, concatenated and following an initial line that reads:

┌────────────────────────────────────────┐
│  eval this: (occur "^[+]\\(;; \\)*@")  │
└────────────────────────────────────────┘

If you open the ‘.org’ file in Emacs, ensure the buffer is in Org mode (via command ‘M-x org-mode RET’, if necessary), move the cursor to the end of the first line, and type ‘C-x C-e’ (or alternatively, ‘M-x eval-last-sexp RET’), you might very well see another buffer appear that counts and lists all the new index entries (171 for Guile-BAUX, 47 for GNU RCS).

If you are Emacs-averse, well, all is not lost (just a small bit of your parenthetical soul — haha, just kidding).  The Guile-BAUX repo is still on a dumb (http) host — I've not yet managed to obtain a GitLab account — sorry, but the GNU RCS repo is at savannah.  You can follow along there, instead: 

$ cd ~/build/GNU/rcs
$ glog --grep 'doc.*ndex' --reverse
b2cf82f 2015-01-14 [doc] Index ‘frob -o’ more.
193be5b 2015-01-14 [doc] Index locking concepts, operations.
9ec90d9 2015-01-14 [doc] Move @cindex before @item.
be2f1ab 2015-01-14 [doc] Index keywords.
c52fe67 2015-01-14 [doc] Index implicit checkout.
bb1111c 2015-01-18 [doc] Index some more branch-related concepts.

There are three kinds of index entries on display here, the first two for API elements: 

The ‘@cindex’ entries are the real “value-add” here, an opportunity to communicate human to human.  A prime example of that is b2cf82f (the first GNU RCS patch), commit log reproduced here: 

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  [doc] Index ‘frob -o’ more.                                    │
│                                                                 │
│  * doc/rcs.texi (rcs): Use "delete" in ‘-o’ explanation,        │
│  reducing "outdate" to aka status; add @cindex for "deleting",  │
│  "removing" and "outdating".                                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

For historical reasons, GNU RCS uses the term “outdate” to mean “remove” or “delete”.  The patch places all three terms on equal footing in the documentation. 

To finish, I'll note that unlike the “add blank lines” followup patches, all of these changes are literal additions — no algorithmic changes.  Probably I'll get to that soon enough.  (I confess, I really prefer writing software, and if I had my druthers...)  I'll close now with these handy links to the Guile-BAUX and GNU RCS online docs.


Copyright (C) 2017 Thien-Thi Nguyen