Re: [DRAFT] Revised groff ms manual for review

[James K. Lowden]

On Sat, 31 Oct 2020 20:40:44 +1100
"G. Branden Robinson" <g.branden.robinson@gmail.com> wrote:

> Anyway, I'd appreciate feedback, positive or negative

Although a little chatty in places, it's a good starting point.  

One difficulty (as ever) is defining the audience.  To what degree is
the reader expected to know troff itself?  Registers and strings are
carefully described, for example, but auto-incrementing registers (which
I've always found confusing) are first mentioned in passing while
discussing .IP.  

One approach might be to include a kind of troff glossary, with each
use of troff requests hyperlinked to the term in the glossary.  

In the introduction to section 5, you start with "character" and move to
"glyph" via "grapheme" without defining that last term.  It might be
better to start with what everyone knows, "letter", as in of the
alphabet, then character as a generalization of letter, and glyph as a
specialization (or manifestation) of character.  I think it's correct
to say a font maps a character to a glyph.  

IMO the daft zebras example is confusing and a bit specialized.  It
might make more sense after VS is defined, because (I think) it implies
VS is 0. More helpful might be an example contrasting the default
leading with "double spacing" as is used for college term papers.  

I think the math is wrong here:  

    "As a groff ms extension, if \n[PS] or \n[VS] is set greater than or
equal to 1000, ms divides the register by 1000 to get a fractional
point size. For example, .nr PS 1025 sets the point size to 10.25p."

To get 10.25 from 1025, one divides by 100, not 1000.  

I hope to offer more feedback soon. 

--jkl