Re: Unsupported nroff macros on MacOS X

[Ralph Corderoy]

Hi Ken,

> This manpage is not compatible with mandoc(1) and might display
> incorrectly.

mandoc is a pain.  It's one of many programs which attempt to interpret
man pages whilst being an incomplete implementation.  I hang out in
places which like to talk about troff/nroff, including for man pages,
and mandoc's flaws crop up a lot.

> After some digging, it turns out man(1) is a shell script and to make
> a long story short is running this command:
>
>       mandoc -Tlint -Wunsupp

I'd suggest disabling that if it's possible.

> And some quick googling suggests that in fact the mandoc macros

I understand it's a program which tries to interpret files intended for
a troff/nroff rather than a set of macros.

> .fc aint one of them.

Ignore mandoc.  :-)

> I will admit that my roff-fu is not very good, but I took a look at
> this.  It seems this is a common idiom for nmh man pages.
> Specifically (this is from packf(1) but it's similar everywhere else):
>
> .SH "PROFILE COMPONENTS"
> .fc ^ ~
> .nf
> .ta 2.4i
> .ta \w'ExtraBigProfileName  'u
> ^Path:~^To determine the user's nmh directory
> ^Current\-Folder:~^To find the default current folder
> ^Msg\-Protect:~^To set mode when creating a new `file'
> .fi
>
> So as I vaguely understand it, the .fc line sets '^ as a field
> delimeter and '~' as the character to pad a field.

Yes, i.e. ‘~’ is where to share out the stretchable space within the
field.

> .nf sets the following lines to no-fill mode.

Yes, so don't join input lines together to form output lines.

> ".ta 2.4i" sets the tab stop to 2.4 inches.

Yes, just a single tab stop.

    $ printf '%s\n' '.ta 2.4i' $'a\tb\tc\td' '.pl \n(nlu' | nroff
    a                       bcd
    $

> The following line sets the tab stop to the width of
> "ExtraBigProfileName" and 'u is the default horizontal span for the
> terminal

Not quite.  The single tab stop is set to the width of the string
‘ExtraBigProfileName  ’ including a couple of spaces.  \w'' gives the
width of the string in ‘basic units’.  The ‘ta’ request assumes numbers
are in ems so the ‘u’ overrides this to show the number is in basic
units.

> (now that I look at it, I'm not sure why there are two .ta lines right
> after another).

Agreed.

> This isn't wonderful and I'd like to fix it, but I'm not sure what
> to do.  Ideas include:
>
> - Tell MacOS X users to install groff(1) (the man(1) script will try
>   to call groff if it encounters a warning like this from mandoc)

This will fix things for macOS users viewing non-nmh too.  +1

> - Switch to some other roff construct; I was under the impression that
>   actual tabs would work?  I'm not sure why tabs aren't used here.

Perhaps a carry over from more complex layouts in other pages which use
the same valid technique.

> - Switch to tbl(1) macros which as far as I can tell are supported by
>   mandoc and seem to work everywhere.

tbl(1) is a preprocessor which reads the man-page source, leaves most
well alone, and turns what's in between lines of .TS to .TE into roff
for processing by troff/nroff.  Other programs which read man pages do
try to emulate it as part of processing the file, typically with the
same gotchas and noise as they trigger with the rest of the file.

man pages are defined as what troff/nroff handle with the man(7) set of
macros.  It's a complex language.  Pretenders start on a sticky wicket.

The .TS and .TE are copied through allowing a macro set, e.g. man, to
define them if it wants.  This allows further processing of tbl's output
which now lies between them.

A man page which uses tbl should indicate this by the first line being

    '\" t

so man knows to use tbl(1) as well as troff/nroff.

> Given my druthers I think I'd rather do the last one, since this kind
> of seems like a table!

It's not the least work.  You may find you have to then muck around with
tbl's commands a bit to get a nice table for ASCII and UTF-8 on the TTY
and PostScript/PDF for the page or graphical viewers.

Others have mentioned the mdoc macros.  These are an alternative to man.
Their big selling point is semantic mark-up rather than presentation.
But they have their own problems, they're YA-standard, and I'd avoid
them.  Stick with simple man macros and troff/nroff with ASCII, UTF-8,
and PostScript/PDF as targets.

-- 
Cheers, Ralph.