trip logs / gnuvola

Trip Log 2017-05-17 h22

A concentrated followup to yesterday's “blank” lines tripping... 

This tarball has four patch files from four separate projects I maintain: 

$ tar tf add-blank-lines.tar.gz

They all do the same thing, essentially: modify the documentation source such that the rendered Info format is more spacious (i.e., “add blank lines”).  Of course, the particulars differ.  In order of increasing hair: 

These numbers were produced, by the way, using a bit of Emacs Lisp: 

(defun characterize-blank-line-context ()
  (let ((ht (make-hash-table :test 'eq)))
    (while (re-search-forward "^[+];*$" nil t)
      (skip-chars-forward "\n ;()")
      (let ((token (read (current-buffer))))
        (incf (gethash token ht 0))))
    (let (alist)
      (maphash (lambda (token count)
                 (push (cons count token)
      (sort alist (lambda (a b)
                    (> (car a)
                       (car b)))))))

that I invoked via ‘eval-expression’ while visiting the respective patch file, plus a bit of common-sense eyeballing (or, if you are a potential employer, “judiciously applied domain expertise” :-D).  I confess, the “etc” is pure laziness taking hold.  I offer in lieu (and as a form of invitation for you to try to reproduce the findings), the raw ‘unofficial-guile.patch’ results, pretty-printed: 

((255 . @twerpdoc)
 (139 . @item)
 (30 . @example)
 (24 . @twerpmacdoc)
 (19 . @itemize)
 (15 . @twerpcommentary)
 (13 . @twerpcmacdoc)
 (11 . @defvar)
 (5 . @smallexample)
 (3 . where)
 (3 . @c)
 (3 . @lisp)
 (2 . eq\?)
 (2 . symbol->string)
 (2 . @smalllisp)
 (2 . @table)
 (2 . <field)
 (2 . add-hook!)
 (2 . This)
 (2 . The)
 (1 . string=\?)
 (1 . string->symbol)
 (1 . Additionally)
 (1 \` \\)
 (1 \` N)
 (1 . @verbatim)
 (1 . <formals>)
 (1 . <case-lambda-clause>)
 (1 . <\.\.\.)
 (1 . and-let*)
 (1 . <feature-identifier>)
 (1 . <feature-requirement>)
 (1 . <cond-expand-clause>)
 (1 . which)
 (1 . In)
 (1 . We)
 (1 . Now)
 (1 . Given)
 (1 . with))

It's getting late so I won't discuss the algorithmic change now.  Anyway, if you are not a potential employer, thanks for reading — you can stop now and avoid the cheesy self-marketing that follows... 

The point of all this verbiage is to demonstrate what I like to call “aspect-oriented gumption”.  I see a worthy change (spaciousness) and seek to apply it not only deeply — comprehensively within a project — but also broadly, in as many projects as I can.  (These four are a sampling of all the blank lines (and blank-line-producing programs) I've mucked w/ of late — be glad for this reservation!) 

Going forward, I try to methodically incorporate the thinking that underlies the change when I write new stuff (docs, code), so that such a change (especially when its motive is primarily remedial) is not necessary in the future.  The algorithmic change is an example of that mindset in action.  In a testing context, you can ‘s/worthy change/bug and class of bug fix/g’ — same idea. 

That's all for now. 

Copyright (C) 2017 Thien-Thi Nguyen