mandoc on macOS

mandoc on macOS

[Anthony J. Bentley]

Hi,

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. As a fallback, if mandoc gives a
-Wunsupp warning and groff is installed, the script uses groff instead.

https://opensource.apple.com/releases/
https://github.com/apple-oss-distributions/man/blob/man-44/man/man.sh

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

Re: mandoc on macOS

[Jan Stary]

On Apr 04 13:09:28, anthony@anjbe.name wrote:
> >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. As a fallback, if mandoc gives a
> -Wunsupp warning and groff is installed, the script uses groff instead.

Strangely, even calling just 'man' tries to display something, saying
"This manpage is not compatible with mandoc(1) and might display incorrectly"
and displaying what seems to be the content of the script /usr/bin/man
> https://github.com/apple-oss-distributions/man/blob/man-44/man/man.sh
They also install an /etc/man.conf incompatible with mandoc.

Generaly, Apple seems to be replacing the fundamental tools
with *BSD tools (mostly FreeBSD, pf being a notable exception).
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc on macOS

[Jan Stary]

[-- Attachment #1: Type: text/plain, Size: 476 bytes --]

On May 09 10:27:36, hans@stare.cz wrote:
> On Apr 04 13:09:28, anthony@anjbe.name wrote:
> > >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.
Please let me know if there are specific tests to be done.

	Jan


[-- Attachment #2: lint.gz --]
[-- Type: application/x-gunzip, Size: 958475 bytes --]

Re: mandoc on macOS

[Ingo Schwarze]

Hi Jan,

Jan Stary wrote on Tue, May 09, 2023 at 10:36:33AM +0200:
> On Apr 04 13:09:28, anthony@anjbe.name wrote:

>> 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...

 $ 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.  :-)

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.
If something is broken in mandoc, that's more likely to generate
wrong output than to issue an error or warning message.  Then
again, there *might* be rare cases where error or warning messages
are somehow related to mandoc mishandling the input.

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?  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.

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.

Does this anwer help?

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

Re: mandoc on macOS

[Jan Stary]

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

Re: mandoc on macOS

[Mingye Wang]

Jan:
> 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.

The thing about the Feedback Assistant is that you don't get to share
feedbacks using a link and have others comment on it like a Bugzilla
or even Microsoft's Feedback Hub. And usually you don't get any
feedback from Apple about what they are doing with it, so it's overall
designed to... make you not want to do it.

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

Yep, GitHub search (see below) turns up nothing. This leads to a
tangential complaint with mandoc: there's no version output! The
people at GitHub was a little frustrated with that. (PR was stuck for
some unrelated reason.)[2]
  [2]: https://github.com/github/markup/pull/1196#issuecomment-716567772

Ingo:
>If something is broken in mandoc, that's more likely to generate
>wrong output than to issue an error or warning message.

Or it might just get stuck. The test really doesn't make sense: a
timeout would work better than a lint.

> 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.

The BSD manuals seem to match what they are pulling with some edits to
match what they do on their own end. And then there's their own
manuals for what they write. You can often tell which is which from
the quality of the HISTORY section :)

They have in at least one case modified a manual page to fix lint
errors: https://github.com/apple-oss-distributions/awk/blob/f51027cfca6efef532f95b0b5bcbee995c3e6498/awk.plist#L24.
There seems to be a couple more in
https://github.com/search?q=org%253Aapple-oss-distributions+mandoc&type=code.

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