Re: man pages, defensive programming, and bibliographic formats

[Bjarni Ingi Gislason]

On Sun, Jan 26, 2020 at 12:22:08AM +1100, G. Branden Robinson wrote:
> (was: 01/01: tbl(1): Note origin of tbl.)
> 
[...]
> I threw together a script to count up man(7) macro use in our corpus:
> 
> $ MANS=$(find !(build|EXPERIMENTS) -name "*.man"|sort)
> $ man-macro-frequency-counter $MANS | sort -rn -k2
> B: 7236
> I: 5179
> TP: 2512
> BR: 2316
> IR: 1431
> P: 983
> RE: 841
> BI: 792
> IP: 691
> SH: 484
> RS: 475
> LP: 340
> OP: 284
> TQ: 261
> EX: 231
> EE: 231
> RI: 221
> SS: 209
> SY: 181
> PP: 174
> RB: 130
> YS: 127
> IB: 98
> UR: 65
> UE: 65
> TH: 61
> MT: 52
> ME: 52
> SM: 0
> SB: 0
> 
> The script is attached.
> 
> Note that I have not finished my project of cleansing the pages of
> unnecessary font escapes, so some of the font-style macros are
> under-counted.
> 

  Some of the numbers are wrong;
 compare for example the numbers for RS and RE.
 They should be the same.

  A few man-pages are created to be in the build directory.



> > > It's for similar reasons that I do this:
> > > 
> > >   The mf macros \&.foo and \&.bar should not be called within a
> > >   \&.pp context.
> > > 
> > > The zero-width space escapes on the first line are not necessary;
> > > but it's a good habit to use them anyway, because what happens if
> > > you recast and reflow the sentence in your text editor such that one
> > > of those ends up starting a line?
> > 
> > When semi-automatically transforming code, you need to check the
> > result in any case.
> 
> I agree.  Code defensively and then validate the output.  :)
> 
> > > In my view, this sort of thing is not cargo-culting, but defensive
> > > programming.
> > 
> > In my view, unnecessary escaping just makes text harder to understand
> > by making it look mysterious.  How many people will think the
> > superfluous escaping is actually somehow required?  It's likely to
> > cause fear, uncertainty, and doubt.
> > 
> > How is the (arbitrary) rule "a dot needs escaping at the beginning
> > and end of each word" easier to learn than the (accurate) rule "it
> > needs escaping at the beginning and end of each input line"?  They
> > seem both the same difficulty to me, except that the accurate rule
> > needs to be invoked far more rarely (less work and obfuscation)
> > and also becomes obvious once you understand how request/macro and
> > sentence end detection works, whereas the arbitrary rube is, well,
> > arbitrary and needs yet another argument for understanding it even
> > after understanding the root cause of the problem.
> 
> You and I disagree on this and I'd like to solicit the views of the
> folks on the mailing list.
> 

About the use of '\&':

  The instructions for using '\&' with a period are defective.

  Always use '\&'
 (a non-printing, zero width character)
 to make it clear to the software,
 that the _function_ of the character next to it,
 is neither a sentence-terminating nor
 a control one.

  The _current_ position (in a line) is irrelevant.

-- 
Bjarni I. Gislason