Re: mandoc on macOS

[Jan Stary <hans@stare.cz>]

Hi Ingo,

> >> From Apple's open source releases page, it appears that in macOS 13.0
> >> (released last October), their man(1) implementation was replaced with
> >> a shell script that calls mandoc.
> 
> > $ mandoc -Tlint /usr/share/man/man*/* > /tmp/lint
> > $ wc -l /tmp/lint
> >    98362 /tmp/lint
> > 
> > Attached in case Ingo wants to have a look.
> 
> Not quite sure what i'm supposed to do with that output...

I didn't mean to say that you are supposed to do anyting
- just in case you wanted to have a rough picture
of how mandoc handles macOS's manpages, in the spirit
of your old slides on trying mandoc on other OSes.

>  $ sed 's/^mandoc: [^ ]* //' lint | cut -d: -f1-2 | sort | uniq -c | sort -nr
> 
> 53308 STYLE: input text line longer than 80 bytes
> 9893 STYLE: whitespace at end of input line
> 5629 ERROR: skipping bad character
> 5452 WARNING: skipping paragraph macro
> 4800 WARNING: empty block
> 4675 WARNING: new sentence, new line
> 1847 WARNING: tab in filled text
> 1642 UNSUPP: unsupported control character
> 1419 STYLE: referenced manual not found
> 1305 STYLE: lower case character in document title
> 1111 WARNING: cannot parse date, using it verbatim
>  791 STYLE: useless macro
>  663 STYLE: operating system explicitly specified
>  562 STYLE: no blank before trailing delimiter
>  473 WARNING: invalid escape sequence
>  422 ERROR: skipping excess arguments
>  379 WARNING: missing date, using ""
>  305 STYLE: fill mode already enabled, skipping
>  249 WARNING: .so is fragile, better use ln(1)
>  241 WARNING: missing manual title, using ""
>  227 STYLE: trailing delimiter
>  222 WARNING: unknown font, skipping request
>  179 WARNING: moving content out of list
>  176 WARNING: blank line in fill mode, using .sp
>  173 ERROR: .so request failed
>  172 WARNING: unusual Xr order
>  165 WARNING: skipping no-space macro
>  143 WARNING: line scope broken
>  127 WARNING: skipping empty macro
>  114 STYLE: normalizing date format to
>   99 STYLE: unterminated quoted argument
>   97 WARNING: sections out of conventional order
>   82 WARNING: undefined escape, printing literally
>   76 ERROR: NOT IMPLEMENTED
>   75 ERROR: skipping unknown macro
>   71 WARNING: wrong number of cells
>   65 WARNING: missing -width in -tag list, using 6n
>   61 WARNING: unusual Xr punctuation
>   61 WARNING: missing section argument
>   56 STYLE: verbatim "--", maybe consider using \(em
>   46 WARNING: NAME section without description
>   46 STYLE: function name without markup
>   46 ERROR: skipping end of block that is not open
>   44 WARNING: missing comma before name
>   41 UNSUPP: unsupported escape sequence
>   37 WARNING: prologue macros out of order
>   36 WARNING: cross reference to self
>   35 WARNING: moving paragraph macro out of list
>   30 WARNING: empty argument, using 0n
>   28 WARNING: comma in function argument
>   27 STYLE: bad comment style
>   26 STYLE: fill mode already disabled, skipping
>   25 WARNING: content before first section header
>   24 WARNING: undefined string, using ""
>   21 WARNING: blocks badly nested
>   21 STYLE: possible typo in section name
>   21 ERROR: inserting missing end of block
>   20 WARNING: unexpected section
>   15 STYLE: consider using OS macro
>   15 ERROR: appending missing end of block
>   14 WARNING: missing Os macro, using ""
>   14 WARNING: AUTHORS section without An macro
>   13 WARNING: filename/section mismatch
>   13 STYLE: legacy man(7) date format
>   11 WARNING: nested displays are not portable
>   11 ERROR: escaped character not allowed in a name
>   10 WARNING: macro neither callable nor escaped
>   [...]
> 
> That's certainly more warnings than in OpenBSD, but in an operating
> system that is as poorly maintained as macOS, that's certainly
> expected.  Actually, i might have expected even more errors and
> warnings.
> 
> What can you do about it?
> 
> Well, i would have two completely different ideas.
> 
> First, if you find any ideas on macOS how mandoc can be improved,
> reporting those is certainly welcome.  The easiest way to find such
> ideas is likely using mandoc on macOS for your normal work and then
> noticing that something isn't working quite as it should.  Like
> with any other program on any other system.  :-)

Right. I have been using mandoc on macOS for a couple
of (macOS) releases now - and as the OP said, it is the default now.
It seems Apple is replacing the infrastructure with BSD tools.

I don't see problems using it, except problems on the macOS side:
for example, the ystill install the legacy man.conf which I have
to replace with a mandoc one.

> This list of errors and warnings is not the most likely starting
> point for finding bugs in mandoc because most of these are more
> likely issues with macOS documentation than with mandoc.

Right.

> The second thing you could do is trying to help improve the macOS
> manual pages.  I do not know whether that makes sense.  Does Apple
> even accept patches sent in by users?  What is their policy
> regarding documentation issues?

Apparently one needs to read up on "Using the Feedback Assistant app"
https://developer.apple.com/bug-reporting/#feedback-assistant
and I for one cannot drag myself to anything like that.

> Do they patch their manuals
> when they are broken, or do they merely (every few decades)
> pull in complete software packages from FreeBSD and other third
> parties, without any local modifications?  I have no idea.

As an example, strlen(3) is the FreeBSD manpage from 2009.
So I believe your description is pretty close.

Interestingly, mandoc is not among the repos at
https://opensource.apple.com/releases/

> If you use mandoc -T lint to systematically improve any collection
> of manual pages, then you should generally proceed in this order:
> UNSUPP, ERROR, WARNING, STYLE.  UNSUPP and ERROR are almost
> always worth fixing, WARNING usually, and STYLE often.  On systems
> other than OpenBSD and NetBSD, using -T lint -W style rather
> than plain -T lint is often useful to get rid of the "base"
> level warnings, which are specific convertions for OpenBSD or
> NetBSD, respectively.

Thanks for the insight,

	Jan

--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv