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 autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 322 invoked from network); 8 Jun 2023 13:44:51 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 8 Jun 2023 13:44:51 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 8da0b825 for ; Thu, 8 Jun 2023 08:44:46 -0500 (EST) Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 164961b2 for ; Thu, 8 Jun 2023 08:44:44 -0500 (EST) Received: from hekate.asta.kit.edu ([2a00:1398:5:f401::77]) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.3:ECDHE_SECP256R1__RSA_PSS_RSAE_SHA256__AES_256_GCM:256) (envelope-from ) id 1q7FwR-006OSz-B8; Thu, 08 Jun 2023 15:44:43 +0200 Received: from login-1.asta.kit.edu ([2a00:1398:5:f400::72]) by hekate.asta.kit.edu with esmtp (Exim 4.94.2) (envelope-from ) id 1q7FwQ-0016FA-8J; Thu, 08 Jun 2023 15:44:41 +0200 Received: from schwarze by login-1.asta.kit.edu with local (Exim 4.94.2) (envelope-from ) id 1q7FwP-000o8M-MM; Thu, 08 Jun 2023 15:44:41 +0200 Date: Thu, 8 Jun 2023 15:44:41 +0200 From: Ingo Schwarze To: Jan Stary Cc: 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 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