Hi Branden, G. Branden Robinson wrote on Sun, Aug 09, 2026 at 03:35:57AM -0500: > 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. Patch taken. Sure, that explanation isn't complete either, but i agree it's the best that can be done in ten words, and the first paragraph of the homepage would be the wrong place to go into any more nuance. https://mandoc.bsd.lv/ While there, i did this: revision 1.59 Mention that man(7) is still dominant in Linux and not purely historic. Stop advertising the experimental PostScript and PDF output formats in the first paragraph because that constitutes undue and misleading emphasis. s/UNIX/Unix/ in some places where it is merely used as a generic term. > That is, if the word "Linux" is utterable in OpenBSD man pages. ;-) Of course it is, even though it's not needed very often: $ mandoc -M /usr/share/man -k any=linux getent(1) - get entries from administrative database elf(5) - format of ELF executable binary files mdoc(7) - semantic markup language for formatting manual pages [...] >> 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? Obviously, the authors and maintainers of the document. Who else? If the Pope would be the one discouraging it, being more specific would admittedly be warranted. ;-) In OpenBSD, we carefully avoid using "we", "you", and "I" in manual pages. Admittedly, that's a preference established by Jason McIntyre, our documentation maintainer for almost two decades, but i agree it helps a bit to keep the tone formal and objective. [...] >> 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; THat is incorrect. It was not used and did not even exist for almost half that period, from 1971 to 1978, and that is an important period of Unix history. I admit though that the sentence as it stands is also slightly misleading because from 1979 to 1989, man(7) was not only used in AT&T UNIX, but also in BSD, SunOS, HP-UX, Ultrix, AIX, and others, so your wording "universally for Unix man pages" *is* an improvement. > it remains popular in Linux. That is undoubtedly true and probably worth saying. > When composing BSD manual pages, use mdoc(7) instead; I disagree with that. Not only do i want to recommend mdoc(7) for BSD manual pages, but also for portable software projects in general. Unless i misremember, even the Linux man pages project now accepts mdoc(7) pages if contributors want to submit any. > it has more extensive semantic markup features. You have a point here. While "purely presentational" was close to (but even then, not entirely) correct when it was written, more semantic features have been added since then, which is mostly your fault. =:c) To summarize, i polished the introductory paragraph of man(7) somewhat, see the committed patch appended at the end. >> 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 I should probably implement that. Unless it is able to handle wide characters in the manner of towupper(3), which i sure hope it does not, that should be easy enough. > msoquiet All that needs to be done is mark it as "Ignored because insecure." > soquiet That should be trivial to implement. However, i would probably be best to make it a strict synonym of .so and *not* suppress any warnings because in a manual page, any missing include file seems very likely to be a serious problem, no matter whether .so or .soquiet is used, and silent loss of information must be considered a very serious defect in manual pages in particular. > hydefault Can simply be ignored just like all the other .hy* macros. > pstream Can simply be ignored, doesn't seem to make sense for mandoc(1). > pline Should be ignored: in mandoc(1), the facility to use for that purpose is -T tree. > phw Ignore because it's related to .hy. > pcomposite Ignore because composite characters are not a thing in mandoc(1). > pchar While mandoc(1) has partial support for .char (but not for .fchar or .schar), i still tend to ignore this and if needed, improve -T tree. > pcolor Ignore, mandoc(1) has no concept of colors in the first place. > pwh (renamed from `ptr`) Ignore, mandoc(1) has no concept of traps. Note that these are *not* purely documentation issues. They also need to be reflected in the code of the roff.c parser module, to make sure that the requests are treated as desired when they are encountered, including providing messages that are actually helpful and come at an adequate message level, or *not* spewing messages when none are needed. For example, this current situation is not good: $ echo '.pchar' | mandoc -T lint -W error mandoc: <stdin>:1:2: ERROR: skipping unknown macro: .pchar The meaning of ERROR is documented as follows see the DIAGNOSTICS section in the mandoc(1) manual): error Indicates a risk of information loss or severe misformatting, in most cases caused by serious syntax errors. Throwing an ERROR at the user when finding a .pchar request is obviously a massive overreaction and likely to inspire some FUD in the poor user. =8-| >> 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? I just did a quick check of my mail archives (without going to the full length of performing an exhaustive full-text search) and immediately found people talking and asking about it at various times. Most seemed more or less happy with what they got from mandoc except for some specific bug report, but none explained why they chose mandoc -T pdf or -T ps over the more obvious option to use groff, nor why it was good enough for them. About half the people were operating system developers (mostly from OpenBSD and NetBSD), the other half were users, some of them mailing list regulars whom i knew before, some of whom i didn't. * 29 Jun 2010 * 04 Jun 2014 mentioned wanting to share PDF files with users on other operating systems, but didn't say why * 06 Oct 2017 * 19 Nov 2018 wanted to use -T pdf for significant numbers of Polish manuals they had written themselves for internal company purposes In response, i recommended Groff and together with another OpenBSD developer, we helped them to configure character sets and fonts for groff, which was harder to do back then than it is now * 14 Jan 2019 two different people spoke up independently of each other * 09 Jan 2022 mentioned using Alpine Linux That list is almost certainly incomplete, but it reflects the general trend: people don't talk about it often (significantly less than one percent of discussions about mandoc, likely roughly on the order of one or two permille), but when people do speak up, they don't usually say "this is just utter crap" (even though i would have a hard time disputing that) but seem to mostly get along with it. Why? About as mysteriuos to me as it is to you, i guess. > Wouldn't such people be better off using an external converter to > transform mandoc(1)'s high-quality HTML output to a PDF? I don't think so. HTML is absolutely not a typesetting language, it is a semantical markup language, and whatever the source document may have done to achieve good typesetting is almost certainly lost in the conversion to HTML, even if that conversion produces HTML code of exemplary quality. > That shouldn't take the _user_ any longer; the effort has already > been expended by the people who maintain such converters. Well, the natural way to create PDF from mdoc(7) or man(7) is using groff(1). While using that is arguably slightly more difficult than using mandoc(1), it's not going to cause *that* much additional effort, and if you are serious that you want typesetting, the time spent is definitely worth it to get good results. There may be ususual cases where using groff requires significant resources - for example, suppose you want to maintain all manual pages in Debian in PDF format and update the whole set multiple times a day, then you have to expect that you will be burning some CPU on the job. All the same, even though cheaper, using mandoc(1) instead, or going via HTML, would not really make sense to me, especially not in such in a high-profile high-cost use case like that. > Maybe I can coax John into helping me improve groff's (X)HTML output. :) THat would certainly be great. :) Yours, Ingo Log Message: ----------- Some corrections and updates in the introductory paragraph: * From 1979 to 1989, not only AT&T UNIX used man(7), but so did all other Unix-like systems including BSD, SunOS, and all the others. * While the statement that man(7) was "purely presentational" was mostly (though not entirely) true when written, it is no longer accurate. A number of semantic macros have since been added, even though far less systematically than in mdoc(7). * Mention the situation in Linux and GNU roff. Knowing about that is relevant for all, including our users, because it means people will continue to find many man(7) pages in the wild, including some that will fail badly with old versions of groff(1). * Point to GNU roff documentation for the unlikely case that someone sees themselves forced to write new man(7) code. About half of the the ideas and a few wordings were suggested to me by G. Branden Robinson. Modified Files: -------------- mandoc: man.7 Revision Data ------------- Index: man.7 =================================================================== RCS file: /home/cvs/mandoc/mandoc/man.7,v diff -Lman.7 -Lman.7 -u -p -r1.155 -r1.156 --- man.7 +++ man.7 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.\" Copyright (c) 2011-2015, 2017-2020, 2023, 2025 +.\" Copyright (c) 2011-2015, 2017-2020, 2023, 2025, 2026 .\" Ingo Schwarze <[email protected]> .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <[email protected]> .\" Copyright (c) 2017 Anthony J. Bentley <[email protected]> @@ -27,14 +27,17 @@ .Sh DESCRIPTION The .Nm man -language was the standard formatting language for -.At -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 +language was used universally for Unix manual pages from 1979 to 1989. +It remains popular in Linux and keeps being actively maintained and +extended by the GNU roff project. +All the same, do not use it to write new manual pages. +Instead, use the .Xr mdoc 7 -language, instead. +language, which provides both significantly better semantic markup +facilities and is easier to use correctly. +Consequently, this document does not provide advice on how to use the +.Nm +language; for such advice, refer to the GNU roff project instead. .Pp In a .Nm
