Re: Unsupported nroff macros on MacOS X

[Ralph Corderoy]

Hi Ken,

> > The status quo is fine.  It doesn't require understanding all of
> > troff.  Just man(7) plus the odd bit here and there.
>
> Sigh.  The "odd bit" unfortunately, for me, requires a lot of
> knowledge that seems to take some serious roff-fu.

Which is why I said refer to the mailing list for help.  Which you cut.

> Let's take the example you gave where the first line for a man page
> that uses tbl should contain:
>
>     '\" t
>
> So, my question is ... what does this mean?

It's a magic string recognised by man-page processors, like man(1).
They hand off the man page to troff for formatting but need to know what
preprocessors to run in advance.  These are programs which expand some
of the man page into troff language.  tbl is one.  pic(1) is another
common one for diagrams.  The agreement is the man page author specifies
this by convention: the first line being the three characters quote,
backslash, double-quote and a list of characters.  man(7) here lists:

       e  eqn(1)
       g  grap(1)
       p  pic(1)
       r  refer(1)
       t  tbl(1)
       v  vgrind(1)

> I understand that \" is a comment, but I'm confused about the leading
> single quote.

Ignore all troff documentation until you have seen Ossanna's and
Kernighan's CSTR 54, the ‘Troff User's Manual’.
https://troff.org/54.pdf

Just skim the first few pages and you'll see it starts with lots of
handy tables referring to the following pages.  The paper is the high
quality succinctness one expects from Bell Labs and Kernighan.
It's a delight to read.  I still refer to it often.

The very first paragraph of the main text answers your question.

    1. General Explanation

    1.1.  Form of input.

    Input consists of text lines, which are destined to be printed,
    interspersed with control lines, which set parameters or otherwise
    control subsequent processing.

    Control lines begin with a control character — normally . (period)
    or ’ (single quote) — followed by a one or two character name that
    specifies a basic request or the substitution of a user-defined
    macro in place of the control line.

    The control character ’ suppresses the break function — the forced
    output of a partially filled line — caused by certain requests.

    The control character may be separated from the request/macro name
    by white space (spaces and/or tabs) for aesthetic reasons.

    Names should be followed by either space or newline.
    Control lines with unrecognized names are ignored.

So «'» and ‘.’ are equivalent in many cases.  The ‘\"’ comment above
should be on a request line rather than a text line as a text line is
‘destined to be printed’, even if empty.

    $ printf '%s\n' '\" t' foo '.pl \n(plu'
    \" t
    foo
    .pl \n(plu
    $
    $ printf '%s\n' '\" t' foo '.pl \n(plu' | nroff | cat -n
         1      
         2      foo
    $ printf '%s\n' '.\" t' foo '.pl \n(plu' | nroff | cat -n
         1      foo
    $ printf '%s\n' \''\" t' foo '.pl \n(plu' | nroff | cat -n
         1      foo
    $ 

> As a random note, this string is rather hard to search for.

CSTR 54 mentions it at the start of the second page of documentation.

    Request Summary

        B   Request normally causes a break.  The use of ’ as control
            character (instead of .) suppresses the break function.

And then 1.1, above, covers it again.  What's ‘filling’?  Well, the
index of chapters and the requests each covers has

    4. Text Filling, Adjusting, and Centering

> there's a huge pile of knowledge that is assumed you know.

Given you don't know what you don't know, I can say you're wrong.
It's not a huge pile.

> And I do it so infrequently that I have to re-learn it all every time
> I want to edit a man page.

Just copy what's already there.

> (I did play around with tbl, and it seems like that is actually very
> easy so I am thinking that Anthony is is right and we should just
> switch to that).

You're just prolonging the agony.  Make nmh on macOS depend on
macOS's troff.  Whether that's a virtual package satisfied by others
or an actual package if there's only one.  You've identified one thing
mandoc is formatting wrongly.  It may be formatting other things wrongly.
And if not now, then it may do in the future, especially if knowedgable
man-page authors continue to write nmh's *man pages*, not mandoc-input.

-- 
Cheers, Ralph.