* mandoc on macOS @ 2023-04-04 19:09 Anthony J. Bentley 2023-05-09 8:27 ` Jan Stary 0 siblings, 1 reply; 6+ messages in thread From: Anthony J. Bentley @ 2023-04-04 19:09 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: mandoc on macOS 2023-04-04 19:09 mandoc on macOS Anthony J. Bentley @ 2023-05-09 8:27 ` Jan Stary 2023-05-09 8:36 ` Jan Stary 0 siblings, 1 reply; 6+ messages in thread From: Jan Stary @ 2023-05-09 8:27 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: mandoc on macOS 2023-05-09 8:27 ` Jan Stary @ 2023-05-09 8:36 ` Jan Stary 2023-06-08 13:44 ` Ingo Schwarze 0 siblings, 1 reply; 6+ messages in thread From: Jan Stary @ 2023-05-09 8:36 UTC (permalink / raw) To: discuss [-- 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 --] ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: mandoc on macOS 2023-05-09 8:36 ` Jan Stary @ 2023-06-08 13:44 ` Ingo Schwarze 2023-06-08 16:05 ` Jan Stary 0 siblings, 1 reply; 6+ messages in thread From: Ingo Schwarze @ 2023-06-08 13:44 UTC (permalink / raw) To: Jan Stary; +Cc: discuss 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: mandoc on macOS 2023-06-08 13:44 ` Ingo Schwarze @ 2023-06-08 16:05 ` Jan Stary 2023-06-12 8:37 ` Mingye Wang 0 siblings, 1 reply; 6+ messages in thread From: Jan Stary @ 2023-06-08 16:05 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: mandoc on macOS 2023-06-08 16:05 ` Jan Stary @ 2023-06-12 8:37 ` Mingye Wang 0 siblings, 0 replies; 6+ messages in thread From: Mingye Wang @ 2023-06-12 8:37 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2023-06-12 8:37 UTC | newest] Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2023-04-04 19:09 mandoc on macOS Anthony J. Bentley 2023-05-09 8:27 ` Jan Stary 2023-05-09 8:36 ` Jan Stary 2023-06-08 13:44 ` Ingo Schwarze 2023-06-08 16:05 ` Jan Stary 2023-06-12 8:37 ` Mingye Wang
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).