Hi Branden, i'm answering selectively for now, only so far as is related to my recent commit to the mandoc(1) manual page.
G. Branden Robinson wrote on Sun, Aug 09, 2026 at 03:18:31AM -0500: > A problem I perceive is that mandoc(1) fails to correct distorted views > if the user runs "mandoc -T ps" (or "-T pdf") observes that it goes > fast and exits with status 0. Fanbois conclude from this that the > rendering was correct, sometimes without bothering to inspect the output > at all. > > Where a problem really threatens is that if mandoc(1) fails to correctly > render (in PS or PDF format) a man page maintained by a third party, > those same partisans are apt to conclude that the _document_ was written > incorrectly. > > Thus, in the hands of fanbois, mandoc(1) can become a tool for damaging > the reputation of innocent third parties. > > _That_ is objectionable. That is hard to correct though. As you rightly observe, it is hard to combat prejudice, in particular in people who choose to not read documentation and/or to not listen. Still, improving documentation may help somewhat, because many people do read documentation. Rumour has it that reading manual pages is more common among OpenBSD users than elsewhere (but i'm not aware of any empirical reasearch proving the point, so it's admittedly a bit of a speculation - and possibly even wishful thinking). One thing that mandoc(1) does do is clearly distinguish the "error" and "unsupp" message levels, and document what they mean, so hopefully, *some* people may understand that when ouput looks bad and -T lint or -W error report "UNSUPP", it's at least as much mandoc(1)'s fault as the source document's. Then again, while large amounts of work have been spent on making messages useful, i freely admit theat they are still not perfect, and likely can't ever be. I also admit that by design, all messages are independent of the output format, so if some output mode does not support some input constrution, that usually cannot produce any message. > At 2026-08-07T17:20:17+0200, Ingo Schwarze wrote: >> I always say that if you need real PostScript or PDF output, use >> groff(1), not mandoc(1). > I encourage you to say this even more often, and more loudly. Done in the mandoc(1) manual, see the committed patch below. [...] >> Probably, the mandoc(1) manual should warn that -T ps and -T pdf >> are not indended as serious typesetting and should warn against their >> use for most purposes. > Please, yes! Done in the mandoc(1) manual. [...] > In the meantime I could add an unconditional warning diagnostic to > grohtml(1) such that when it runs, it warns the reader of its beta > status, just as the man page does. I certainly won't add any unconditional warning message to mandoc. I firmly believe that documenting limitations is a job for documention, not for standard error output. I firmly believe that when a program performs as expected and does not experience any *specific* failure, it ought to remain silent. I also strongly detest software being chatty without failure, even when it's not myown software: $ egdb GNU gdb (GDB) 17.1 Copyright (C) 2025 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "x86_64-unknown-openbsd7.9". Type "show configuration" for configuration details. For bug reporting instructions, please see: <https://www.gnu.org/software/gdb/bugs/>. Find the GDB manual and other documentation resources online at: <http://www.gnu.org/software/gdb/documentation/>. For help, type "help". Type "apropos word" to search for commands related to "word". (gdb) Yikes. I dimly remember there may be some way to configure GDB to shut the hell up when it has nothing to say, but i hate having to configure software before it can be used even more, so i don't do that. [...] > Or by withdrawing support for output formats that were no more than an > interesting experiment in the first place. That's the strongest > statement you could make that mandoc(1) is _not_ in the typesetting > business. I agree that merits serious consideration. However, i'm not planning to do that right now, for four reasons. Most importantly, the PostScript and PDF output modes have attracted some - admittedly limited - interest by very smart and capable developers. Most notably, Marc Espie has repeatedly sent patches and suggestions for these modes that made lots of sense, and part of that work even went in, though admittedly much of it didn't because nobody ever managed to sufficiently polish the more complicated parts of his work. The reason for not much coming of it is that (1) Marc is always massively overworked and (2) while i highly respect Marc, on a purely personal level, we simply seem unable to work together very effectively - long ago, i sometimes tried to contribute to his projects as well but never got anything substantial in. But that doesn't mean progress can't be made in the future, be it with Marc or with a different developer who picks up interest. Also, there clearly *is* interest in typesetting in the OpenBSD base system. Most notably, when early on, i clearly stated that a full roff(7) implementation is not a project goal, Mark Kettenis, who is among the most capable and most respected developers, essentially said (i'm paraphasing here, too lazy to look up the exact quote) "What a pity, i'd welcome roff(7), ms(7), and me(7) in base." So, deleting this stuff sends a signal "it's dead" (even though deletion is never final, stuff can be put back when someone wants to finally advance it), whereas keeping it around sends a signal "there is something to do here." The second aspect is that term_ps.c does not really impede development. While i have had to do some maintenance work on it over the years, usually when improving various aspects of the terminal formatter, the burden has always been light. I might even argue that having it around was mildly beneficial in so far as it encouraged keeping some technical aspects of the terminal formatter more general and helped avoiding excessive hardcoding in the terminal formatter, in particular in such respects as would become particularly hurtful if anybody would ever try to move mandoc(1) even sligthly into the direction of typesetting. Compare that to the situation in the OpenBSD kernel where stuff often gets very aggressively deleted as soon as it hinders more general, architecture- and hardware-independent progress. No such problems are caused by term_ps.c. The third aspect is that small numbers of people - but more than a handful IIRC - have occasionally spoken up over the years who thanked us for the output formats or were at least obviously using them. While some of these might have been better off using groff instead and were maybe effectively harmed by low output quality. I don't recall ever talking to any of them in detail why they preferred mandoc over groff for manual page typesetting, so they may or may not have had reasons that made some sense. So i fear many of these people might feel inconvenienced by deletion, which would require somewhat better reasons than i am able to see right now. The fourth, admittedly minor and somewhat sentimental consideration is that deleting term_ps.c would feel slighly disrespectful of Kristaps, who really deserves respect rather than slight. That wouldn't prevent deleting something that causes real harm, but in my personal view, it means that deleting it would require a really strong and unambiguous rationale, certainly more than "some random people unrelated to the project misrepresent what it is." That said, even though i'm not deleting it now, the decision to keep it for now can always been reconsidered. Yours, Ingo Log Message: ----------- Clarify that the -T ps and -T pdf output formats are experimental, produce low-quality output, and that mandoc(1) is not a typesetting system. This should really have been clarified in this manual page many years ago because producing a typesetting system has never been a development goal, not even a long-term goal. Also delete the EXAMPLES entry involving -T ps because that entry puts undue emphasis on it and can be misconstrued as a recommendation to use that mode for any particular purpose. The general idea for this clarification came up talking to G. Branden Robinson on <[email protected]>. Modified Files: -------------- mandoc: mandoc.1 Revision Data ------------- Index: mandoc.1 =================================================================== RCS file: /home/cvs/mandoc/mandoc/mandoc.1,v diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.273 -r1.274 --- mandoc.1 +++ mandoc.1 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.\" Copyright (c) 2012, 2014-2023, 2025 Ingo Schwarze <[email protected]> +.\" Copyright (c) 2012,2014-2023,2025,2026 Ingo Schwarze <[email protected]> .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <[email protected]> .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -143,8 +143,6 @@ the default of .Cm locale , .Cm man , .Cm markdown , -.Cm pdf , -.Cm ps , .Cm tree , and .Cm utf8 . @@ -156,6 +154,13 @@ It implies .Fl W Cm all and redirects parser messages, which usually appear on standard error output, to standard output. +.Pp +Experimental, low-quality +.Cm ps +and +.Cm pdf +.Ar output +formats are also available. .It Fl W Ar level Specify the minimum message .Ar level @@ -527,29 +532,43 @@ input languages are not supported by .Fl T Cm markdown output mode. .Ss PDF Output -PDF-1.1 output may be generated by +Experimental, low-quality PDF-1.1 output may be generated by .Fl T Cm pdf . +Largely, only PDF features that are also available in PostScript are used. See .Sx PostScript Output -for +for limitations of these two output formats and for .Fl O arguments and defaults. .Ss PostScript Output -PostScript +Experimental, low-quality PostScript .Qq Adobe-3.0 Level-2 pages may be generated by .Fl T Cm ps . +The +.Nm +program is not a typesetting system. +Rather than typesetting the document, this mode essentially produces +.Sx ASCII Output +and minimally adjusts it to conform to PostScript syntax. +Formatting defects are particularly severe for, but not limited to, +.Xr tbl 7 +and +.Xr eqn 7 +input. +To typeset manuel pages, use the GNU roff +.Pq Sy groff +software package instead of +.Nm . +.Pp Output pages default to letter sized and are rendered in the Times font family, 11-point. Margins are calculated as 1/9 the page length and width. Line-height is 1.4m. .Pp -Special characters are rendered as in -.Sx ASCII Output . -.Pp The following .Fl O -arguments are accepted: +argument is accepted: .Bl -tag -width Ds .It Cm paper Ns = Ns Ar name The paper size @@ -757,10 +776,6 @@ as the stylesheet: To check over a large set of manuals: .Pp .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga -.Pp -To produce a series of PostScript manuals for A4 paper: -.Pp -.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 > manuals.ps .Pp Convert a modern .Xr mdoc 7
