Hi Alejandro, Alejandro Colomar wrote on Mon, Oct 23, 2023 at 04:30:58PM +0200:
> This got me curious about TQ, since mandoc(1) considers it "very rarely > used, even in GNU pages". > > Ingo, you may want to reword that, since TQ was being used in the Linux > man-pages project, Done, thanks for the heads up. I append the resulting commit below. > and yesterday I wrote a patch to use it even more: > <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?id=0962e38105076fffc6dae174a9026917c6a3941d> Strange, i pulled from https://git.kernel.org/pub/scm/docs/man-pages/man-pages and don't see such changes there, so i'm just judging from code inspection right now, without looking at formatted versions. I think that is a really bad patch. 1. It gratuitiously makes the description of almost every option longer by a whole line, which is a significant waste of screen real estate. It's further aggravating that due to long options, most Linux manual pages already have an extra line for the options at the start of each paragraph. Now you are doubling that from one to two wasted lines per option compared to the same functionality on BSD. The situation becomes even more dire because Linux already tends to have many low-utility options compared to BSDs, so you keep driving density of useful information down and verbosity and fluff up. 2. Your argument that this helps searching is a red herring. The weakness of man(7) in searching has nothing to do with the *formatting* of list item heads, it is caused by the lack of *semantic markup*. There would be no problem creating search anchors for multiple .Fl topics on the same output line in mdoc(7). The only reason i did not do it is because it is irrelevant for us since we barely have any of those POSIX-violating long options. 3. Seperating two synonymous .Fl entries onto different .TP/.TQ lines weakens semantic expressiveness further. Even though mandoc already contains special guessing logic in the HTML formatter to treat .TQ and following .TP as part of the same list, other formatters and other output modes may be less smart. I mean, those are not even the same macros, and yet you hope for them to be rcognized as entries in the same list? 4. Even the best HTML markup that is so far feasible results in *two* list entries, one with an empty body and and only the second one with the corresponding content. While that may or may not look superficially right (depending on the CSS), it certainly isn't semantically correct and is likely to cause accessibility grief, for example for blind people. So, you want HTML formatters (and formatters to other output languages that support semantic markup) to combine .TQ and subsequent .TP not only into the same list, but also into the same list element - but only if the body of the .TQ is empty, i guess? So you want different macros to behave identically in some ways (.TQ and .TP part of the same list) but the same macro fundamentally different depending on its content. The same macro sometimes gets its own element and sometimes needs to fuse into a different macro. So much fun for implementers of formatting modules! 5. On top of all that, i have a hard time to think of any macro that has a more wicked failure mode than .TQ in case the formatter does not support it. The output visually looks perfectly fine, and the reader gets no hint that the *most important* information is missing. Actually, part of the reason why i initially added that additional warning about .TQ was that i felt uneasy about it: less portable than for example .EX, less important than for example .UR, no semantic benefit, purely presentational intent, ad hoc house of cards on the foundation of .TP, which is already shaky enough in its own right, and a terrible failure mode. So at that time in the past, i was quite happy to get the impression that it was rarely used and stressed that in the documentation, hoping people would behave reasonably and only use it in exceptionally dire cases where really nothing else could possibly help. Either way, that sentence in our manual page clearly is no longer true even without that particular patch, so it's gone now. > TQ seems to be a sibling of TP. Not sure if this will affect this > -Thtml bug in some way; my experiments seem good, but they weren't > exhaustive. Yes, i believe mandoc -T html is already able to more or less cope with typical use cases of .TQ. It seems likely though that you can construct less typical use cases that render badly to HTML (or any other semantical markup language for that matter). You can be virtually certain that HTML output from any non-mandoc formatter will be atrocious right now, and any future output to any semantical markup language will almost certainly be bad initially unless whoever implements that future output mode in whichever program closely looks at mandoc code first and is aware that man(7) formatting requires intelligent and complicated guessing and cannot be done in any way that is based on any context-independent grammar. Yours, Ingo Log Message: ----------- Remove the statement that .TQ was "rarely used even in GNU manual pages". It appears the Linux Manual Pages project started to quite aggressively use .TQ ever for cases where it not only provides no value, but makes formatting worse even when it formats as intended. It's also a bad idea to use it that aggressively because .TQ has particularly catastrophic formatting behaviour on formatters (other than groff and mandoc) that do not support it: It essentially has the effect of omitting the topic of the discussion from the formatted version of the manual page, but in such a way that it does not become apparent to the reader that anything is missing. But whether this is wise or stupid is their problem and none of our business. Either way, we should not call a thing "rarely used" after that is no longer true. Thanks to Alejandro Colomar <alx at kernel org org> for making me aware that the statement is no longer true. Modified Files: -------------- mandoc: man.7 Revision Data ------------- Index: man.7 =================================================================== RCS file: /home/cvs/mandoc/mandoc/man.7,v retrieving revision 1.149 retrieving revision 1.150 diff -Lman.7 -Lman.7 -u -p -r1.149 -r1.150 --- man.7 +++ man.7 @@ -440,7 +440,7 @@ unspecified, the saved or default width Like .Ic TP , except that no vertical spacing is inserted before the paragraph. -This is a GNU extension and rarely used even in GNU manual pages. +This is a GNU extension. .It Ic UC Sets the volume for the footer for compatibility with man pages from .Bx
