G. Branden Robinson wrote on Thu, Aug 11, 2022 at 04:46:12PM -0500: > At 2022-08-11T15:47:38+0200, Ingo Schwarze wrote: >> Alejandro Colomar wrote on Tue, Jul 26, 2022 at 10:09:44PM +0200:
>>> I must say that the source code is really ugly (ugly as in, >>> someone reading it will probably have a hard time modifying it, >>> without reading tbl(1)). >> Completely true, but that's not the worst aspect of it. > I disagree with Ingo's priorities here. The readability of the > source is more important for document maintainability. True, both readability of the source code and rendering quality matter, and discussing which one matters more in the case at hand feels moot. > As we shall see, tbl(1) need not discard as much as Ingo suggests, > and even if it does (at present), I don't perceive quite the semantic > damage he does. I cannot imagine worse damage than reading an alt="" text containing a non-descriptive filename to a blind reader. Even with mandoc, the damage of rendering a structure display as a <table> is very severe for a blind reader. >> In a nutshell, you are making it impossible to decently render >> the manual page to HTML or to convert it to other formats in >> any sensible way. >> >> If esr@ (of doclifter fame) were still around, he would be screaming >> in pain and disgust. > We have an open bug report requesting a feature to have tbl emit HTML. > > https://savannah.gnu.org/bugs/index.php?60052 > > Maybe someone would like to work on this. The "troffcvt" suite already > did this many years ago. An argument that groff -T html could possibly support <table> output from tbl(1) input if somebody did the work is hardly a justification that manual page authors should behave as if it did *right now*. Also, you ignored my observiation that even the mandoc -T html output from a structure display using tbl(1) is very bad for accessibility, and groff could hardly do better. The reason is not that mandoc tbl(7) to HTML conversion is bad but that a structure display *is not tabular data*. I really think this is a point we should try to find a consensus on because using tbl(1) for structure display is such egregiously and unambiguously bad advice that it would be very detrimental if even part of the groff developers would continue promoting it. [...] >>> But at the same time, the result is beautiful, >> Only in PDF and PostScript output. > These output formats are _how typesetting is done_ in the modern era. > > I know mandoc doesn't want to dirty its hands with such matters, but > your militance about the unimportance of typesetting blinkers your > perspective. I don't think that is fair. My argument here is only that a very minor advantage for PDF and Postscript is not worth completely ruining HTML output *for manual pages*. (Besides, there is likely additional fragility with processors without tbl(1) support, or with incomplete tbl(1) support.) I'm not talking about general-purpose typesetting here. > groff cannot share that perspective. > > "As the most widely deployed implementation of troff in use today, groff > holds an important place in the Unix universe. Frequently and > erroneously dismissed as a legacy program for formatting Unix manuals > (manpages), groff is in fact a sophisticated system for producing > high-quality typeset material, from business correspondence to complex > technical reports and plate-ready books." -- groff Mission Statement, > 2014 > > https://www.gnu.org/software/groff/groff-mission-statement.html Yes. It is important that groff provides high-quality typesetting. But that doesn't mean manual pages authors should go out of their way to optimize typesetting quality and disregard considerations for any other output format, or for portability and robustness. [...] > .TS > tab(@); > Lg(type) Lg(identifier) Lg(descriptive-comment). > int@nflag;@/* ??? */ > .TE Please don't abuse hypothetical language extensions to justify using fancy features in manual pages that cause severe trouble with currently existing software. [...] > Yet I would hasten to point out that a synopsis that presents something > that is nowhere discussed later in the man page makes the document > deficient. So if you have semantic markup of all relevant content > _after_ the synopsis, of which a well-written mdoc(7) page will surely > boast, then little or nothing is lost in the domains of searchability > and discoverability. This is a digression. I would argue that the SYNOPSIS should usually not contain structure displays. Then again, this is a page documenting a type, which we both consider a bad idea IIRC. But none of that is related to the question whether using tbl(1) for a structure display is a good idea. If nothing is lost by the structure not rendering at all, that's an argument for deleting it, not for using tbl(1). Let's stick to the point of how to best mark up a structure. >> I don't think you need to worry that the alignment might vary on >> different output devices. If you worry anyway, you can use an >> explicit roff(7) .ta request before the display and reset it with .DT >> after the display. > "If esr@ (of doclifter fame) were still around, he would be screaming in > pain and disgust." > > commit 26e827e36a4d98e9a9403bcc73b4afb116495407 > Author: Eric S. Raymond <e...@thyrsus.com> > AuthorDate: Sat Feb 3 11:54:41 2007 +0000 > > Added portability advice. > > diff --git a/tmac/groff_man.man b/tmac/groff_man.man > index e314cd8f6..057f9f9d4 100644 > --- a/tmac/groff_man.man > +++ b/tmac/groff_man.man > [...] > +.\" ----------------------------------------------------------------- > +. > +.SH "PORTABILITY AND TROFF REQUESTS" > +. > +Since the > +.B man > +macros consist of groups of > +.I groff > +requests, one can, in principle, supplement the functionality of the > +.B man > +macros with individual > +.I groff > +requests where necessary. See the > +.I groff > +info pages for a complete reference of all requests. > +.LP > +Note, however, that using raw troff requests is likely to make your page > +render poorly on the (increasingly common) class of viewers that > +render it to HTML. Troff requests make implicit assumptions about > +things like character and page sizes that may break in an HTML > +environment; also, many of these viewers don't interpret the full > +troff vocabulary, a problem which can lead to portions of your > +text being silently dropped. > +.LP > +For portability to modern viewers, it is best to write your page > +entirely in the requests described on this page. Further, it is best > +to completely avoid those we have described as 'presentation-level' > +.RB ( HP , > +.BR PD , > +and > +.BR DT ). > > The above has undergone some recasting but the basic thrust is intact. > We can dial back its stridency in a considered way, if you like. Shall > we discuss it? The above is just fine. But there is a difference between: (1) Adding a low-level roff(7) request that does little harm when completely ignored, like .ta in this case. That's merely somewhat ugly but not a particularly serious problem. (2) Using non-semantic, fragile markup that causes the complete content to become unsusable in some output modes. That's a major disaster. > It seems like all three of us have some reservations about employing > tbl(1) to this end, but we have not aligned on the best alternative. I think there are many acceptable possibilities. Another one might be using a spaces for indentation in a fixed-with font in non-breaking mode. I don't care that much which of the reasonable ones you pick for recommendation. But tbl(1) is not a serious contender; can't we at least agree on that? >> Formatters that don't support .ta will just ignore it, so it causes >> no harm, and groff and mandoc do support it. > Exactly what I had in mind for `KS` and `KE`, so that we can have > keeps in man pages. :D Practical experience in mdoc(7), which provides the .Bk macro to implement keeps, is that it is almost never needed, so i'd rather deprecate .Bk in mdoc(7) than adding anything similar to man(7). Then again, you are probably right that adding a "keep" macro to man(7) likely causes less disruption than some other macros you added because even the naive way to do it is trivially backward-compatible. But that is unrelated to the question of tbl(1) for structure displays. Yours, Ingo
