Hi Ingo, Just some brief comments since you solicited suggestions on wording of mandoc(1)'s own man pages.
At 2026-08-07T18:08:29+0200, Ingo Schwarze wrote: > It seems quite possible to me that some stuff needs toning down further, > though i do not immediately find it, https://mandoc.bsd.lv/index.html > does not seem to imply any such undertones: > > mandoc is a suite of tools compiling mdoc, the roff macro language > of choice for BSD manual pages, and man, the predominant historical > language for UNIX manuals. You might recast this as: ...and man, the predominant language of Linux and historical Unix manuals. That is, if the word "Linux" is utterable in OpenBSD man pages. ;-) And I'll note for any GNU police happening past that GNU _has_ no preferred macro language for man pages, because _respectable_ GNU users stay in Emacs and read _only_ Info documentation. https://www.gnu.org/prep/standards/html_node/Man-Pages.html > Then, the mdoc(7) manual says: > > DESCRIPTION > [...] > However, using roff(7) requests in mdoc documents is discouraged; > mandoc(1) supports some of them merely for backward compatibility. I would recast to avoid passive voice. _Who_ discourages use of roff(7) requests in mdoc documents? Admittedly, groff_man{,_style}(7) uses the phrase "is discouraged" too, and I'll get rid of that. We don't employ it in the "Portability" subsection, but rather here. Deprecated features Use of the following in man pages for public distribution is discouraged. .AT [system [release]] The only other use of the verb "discourage" occurs in groff_man_style(7)'s "Notes" section, a sort of FAQ. Unicode defines an ellipsis code point, and some fonts have an ellipsis glyph, which some man pages have accessed non‐portably with the font‐dependent \N escape sequence. We discourage their use; on terminals, they may crowd the dots into a half‐width character cell, and do not render at all if the output device lacks the glyph. In synopses, missing ellipses can mislead the reader. Dots and space are universally supported. > The man(7) manual is admittedly giving quite explicit advice: > > DESCRIPTION > The man language was the standard formatting language for AT&T > UNIX manual pages from 1979 to 1989. Do not use it to write > new manual pages: it is a purely presentational language and > lacks support for semantic markup. Use the mdoc(7) language, > instead. I'd recast as follows. The man(7) language was used universally for Unix man pages up to 1989; it remains popular in Linux. When composing BSD manual pages, use mdoc(7) instead; it has more extensive semantic markup features. > In roff(7), i fail to see anything that could be considered > "arrogant". I skimmed over mandoc_roff(7) on my system and saw little to remark upon. I look forward to seeing the new requests I've added since groff 1.22.4 show up. ;-) stringup stringdown msoquiet soquiet hydefault pstream pline phw pcomposite pchar pcolor pwh (renamed from `ptr`) > Originally, Kristaps being a playchild, then me neither caring enough > to invest into the work nor being willing to rip it out entirely, > in particular given that on rare occasions, a few people do speeak up > to say that sometimes, it does come up handy for them when they are > in a hurry and have no real typesetting needs. I'm curious? Who needs PostScript or PDF in a hurry but doesn't need it to be all that good? Wouldn't such people be better off using an external converter to transform mandoc(1)'s high-quality HTML output to a PDF? That shouldn't take the _user_ any longer; the effort has already been expended by the people who maintain such converters. > > and even its HTML output could do with some sanding, so to speak. > > You massively helped with that already, thank you very much once more. Maybe I can coax John into helping me improve groff's (X)HTML output. :) Regards, Branden
signature.asc
Description: PGP signature
