Re: mandoc(1)'s man pages, groffed, and Project KIC (was: Milestone reached: hyperlinked mdoc(7) documents in PDF)

[Lennart Jablonka]

Quoth G. Branden Robinson:
> > And the page numbers reset at the start of each section.  Which they
> > shouldn’t do—the book is one unit; it should get its own page numbers.
> > And in other books, you don’t usually see page numbers per chapter.
>
> This was a bug in me, not in groff.  I forgot to specify `-rC1` when
> generating the PDF.  Include it, and one gets 160 pages (using U.S.
> letter paper) numbered consecutively.

How come that is not the default?

> > (“Section” being an older term for “man pages,” if memory serves
> > right.)
>
> Not as far as I know.  I use the term "document" when it's important to
> distinguish between a coherent chunk of man(7) or mdoc(7) with one `TH`
> or `Dd` call, respectively, and the face of a (perhaps digitally)
> printed "leaf".

The v7 Introduction indeed calls 1, 2, … 8 “sections” and sh(1) 
and the like “entries.”  But v7 man(1) says:

> NAME
>     man - print sections of this manual
>
> SYNOPSIS
>     man [ option ... ] [ chapter ] title ...
>
> DESCRIPTION
>     Man locates and prints the section of this manual named
>     title in the specified chapter.  (In this context, the word
>     `page' is often used as a synonym for `section'.)  The title
>     is entered in lower case.  The chapter number does not need
>     a letter suffix.  If no chapter is specified, the whole
>     manual is searched for title and all occurrences of it are
>     printed.
>
>     […]

Also, from volume 1 page iii:

> The page numbers of each entry start at 1; it is infeasible to 
> number consecutively the pages of a document like this that is 
> republished in many variant forms.

Huh.  I don’t agree.

> > Though Courier is as ugly as ever.
>
> I'm glad you brought this up.  I vigorously agree.  I think inline (as
> opposed to "displayed" changes of font family are generally a terrible
> idea.  And yes, I know some luminaries do it in their books--Brian
> Kernighan for example.  But he also takes authorial care with the
> clarity and quality of the result.  (I've been enjoying the recent 2nd
> edition of _The AWK Programming Language_ lately.)

Also a good point, though not what I meant.  I think Courier 
itself is an ugly type face.

> mdoc(7) pages typeset by groff have numerous deficiencies, motivated I
> think by some misguided notion that if something was "literal", or maybe
> not "literal" but something that a user was going to _make_ literal when
> they typed it in (through parametric replacement), it should be
> formatted in Courier.
>
> I simply cannot subscribe to that principle.  I reject it violently.

Sure, but it would be a win already to replace Courier by 
a different fixed-width type face.  But that’s site-local 
configuration, I guess.

It would be better still to replace Courier by a non-fixed-width 
type face, because we really don’t need to emulate the nonsense 
typewriters do in print.

> I've been tempted more than once to just nuke these "C"s.  I generally
> haven't done it, and any such meddling is sure to bring strident
> complaint from some quarters.  наб ripped me a new excretory orifice
> when I "demoted" the output of `Nm` from bold to normal weight in the
> "Name" section of the page.[1]

Dew it!

> 2.  Again, I have _no_ objection to Courier in _displays_.  And mdoc(7)
>    has those.  I'd like to see how far we can get with a strategy of
>    assigning these doc-XX-font strings only _style_ changes, and leave
>    it to block-structured macros like `Bd -literal`, `Ed` to change the
>    font family.  There's a problem to be solved with `Bl`/`El`.  I'll
>    need to learn my way around these heavily ornamented macros to grasp
>    the shape of it.  Fortunately, examples of usage are not scarce.

I do object to Courier in displays.  Courier is ugly.  Ugly, ugly, 
ugly.  Even under the fixed-width type faces, there are 
nice-looking ones.  Courier is not one of those.  Courier is ugly.