From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=T_SCC_BODY_TEXT_LINE, UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 5910 invoked from network); 8 Jun 2023 16:05:13 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 8 Jun 2023 16:05:13 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 6295110b for ; Thu, 8 Jun 2023 11:05:11 -0500 (EST) Received: from mx.stare.cz (uvt.stare.cz [185.63.96.79]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 7ba10d23 for ; Thu, 8 Jun 2023 11:05:10 -0500 (EST) Received: from localhost (stare.cz [local]) by stare.cz (OpenSMTPD) with ESMTPA id e29ebcf0 for ; Thu, 8 Jun 2023 18:05:08 +0200 (CEST) Date: Thu, 8 Jun 2023 18:05:08 +0200 From: Jan Stary To: discuss@mandoc.bsd.lv Subject: Re: mandoc on macOS Message-ID: References: <70677-1680635368.039706@Wt5-.bfPI.VmWh> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: 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