Hello Branden, G. Branden Robinson wrote on Thu, Jun 05, 2025 at 11:00:22PM -0500: > At 2025-06-06T09:49:16+1000, Robert Thorsby wrote:
>> By all means hold the hands of the authors of man pages, as they seem >> surely to need hand holding, > Part of that is due to some software developers' approach toward > documentation, which, like automated testing, is to write it to the > minimal standard their manager will accept, and is then then fled from > at maximum speed. While it is true that this foolish attitude is deplorably widespread, it is not universal. Significant numbers of developers do understand that thoroughly documentating the code they write is both required to make the code useful (in particular for others, but often enough even for themselves) and thoroughly documentating the code is also an excellent way of finding bugs in the code and a prerequisite for any serious code audit - auditing poorly undocumented code is a very hard task with a very poor cost-benefit ratio - been there, done that... Also note that the attitude you describe is not only limited to *automated* testing; many software developers will do as little testing *of any kind whatsoever* and spend as little time on writing good and understandable code as their manager will let them get away with. Basically, i believe that's all one and the same thing: basic human laziness and sloppiness. Again, not universal, but very whitespread. But is this a reason for the desire of "hand holding" of manual page authors? I very much doubt that. For example, OpenBSD has both very high documentation standards *and* insists on very high standards for using standardized idioms in manual pages - by your logic, that would be a contradiction because the former would, in that logic, obsolete the latter. Real reasons for the "hand holding" include: * making writing documentation easy for programmers (after all, it is not a bad thing if programmers focus on writing good code - having them write documentation in excessively complicated ways is *not* a productive thing to do, and when they write documentation, they should be able to foxus on the *content*, not get lost in fancy custom formatting. * making auditing, editing, and maintaining existing documentation easier for *other* developers - imagine climbing through an elaborate work of visual art just to fix a documentation bug? That's not gonna help the software ecosystem as a collective and cooperative endeavour. > Another part arises from a trend, long evident but not clearly codified > until the groff 1.22.4 release, of man pages using only a subset of > *roff formatter features, or least being written with the expectation > that some renderers do not implement the full troff feature set. That is not an arbitrary expectation. Different systems use different tools (including for documentation formatting) and yet you want manual pages (1) to be portable and (2) to use a universal style such that people don't have to get used to tons of different styles just because they are using different systems at work. Those poor sysops you know... There are lots of ways how software engineers can get creative and invent systems serving different purposes in different ways, and even exploring different techniques for solving the same problems. The basic style how the result of this creativity gets documented is *not* one of the areas to be creative. That would not serve any purpose and just make life harder for everyone. > No one's proposed adding machinery to prevent man(7) documents from > invoking `defcolor`, `gcolor`, or `fcolor` requests, though I wouldn't > expect mandoc(1) to ever add support for them. I don't have a citation > handy, but I seem to remember that Ingo has expressed a dim view of > color variation in man pages. Exactly, there are no plans to ever support any other color than black and white in mandoc(1). Colors constitute a disservice to accessibility and are poorly portable. Sure, in art, using colors can be excused, ;-) and groff(1) is intended, among other purposes, to help create electronic art (and even art making dead trees suffer). But that's no excuse for allowing color in manual pages and have people end up with beige text on ivory background when they hit an unlucky device. Not only will mandoc(1) not implement color support for manual pages, except that people are of course free to colour the mandoc(1) HTML output using their very own CSS code at their own peril, but that's a personal choice about representing *semantics* that the author encoded in the page and has nothing to do with the author picking colours. There are no plans either to have mandoc(1) warn if a manual page requests particular colours: $ mandoc -T lint .TH TEST 1 "June 6, 2025" .SH NAME test \- test .SH DESCRIPTION .defcolor .gcolor .fcolor text <Ctrl-D> $ The mandoc(1) program contains explicit code to make sure that it does *not* warn if a manual page contains a colour request, even on the highest diagnostic level (-Tlint), but the colour request is completely ignored because it is simply irrelevant in a manual page. Compare the above to: $ mandoc -T lint .TH TEST 1 "June 6, 2025" .SH NAME test \- test .SH DESCRIPTION .mycolor text <Ctrl-D> mandoc: <stdin>:5:2: ERROR: skipping unknown macro: .mycolor $ Yours, Ingo
