Follow-up Comment #2, bug #67363 (group groff): [comment #1 comment #1:] > Utter madness.
I disagree, and don't find that characterization helpful. > In manual pages, just switch adjustment and hyphenation off globally for > everyone without supporting any way to switch it back on, Why? I already know the answer: "because that's what _mandoc_(1) does". I get that _mandoc_ doesn't ever want to mess with adjustment and hyphenation. I understand; they're hard problems--I repeatedly run into bizarre subtleties involving them even in contexts that have nothing to do with typesetting man pages. _mandoc_ exists only to typewrite (not really typeset) man pages (but with hyperlink support). And that's fine. But _groff_'s mission is more general. > and be done with it, then delete all the fragile, Fragility is a property that can only be objectively measured by reproducible defects. The primary defense against fragility is an automated test suite. > overengineered, I'm open to improving the code quality of _groff_'s _man_ and _mdoc_ implementations, but I must ask that you be specific and concrete when making recommendations. > and likely bug ridden code in the macro sets related to it. Now that's *definitely* a rebuttable presumption. If you want to assert the presence of bugs in _groff_'s _man_ and _mdoc_ implementations, I ask that you *file bug reports*. > I believe that's the only sustainable option. I disagree. I think what I've devised, and which took me a long time to think up, is sustainable, in large part because it requires nobody but me to change anything that they're doing. If you didn't grasp that from comment #0, then you did not understand the proposal. > You are obviously in way over your head I'm happy to yield my status as _groff_ maintainer to a smarter person if they can also convincingly demonstrate that they have the time and energy to perform the functions of that role on an ongoing basis. Until such a person arrives, I reckon I'll continue bumping my stupid head into things. If you would like to convene a colloquy for consideration of my (in)competence as a software engineer and (in)ability as a _groff_ developer, please start a thread on the _groff_ mailing list so that we can survey the community. > and have produced such a massive amount of regressions with the groff-1.23 > release that it has taken me two years to sort it all out. "[A] massive amount of regressions?" I've received few bug reports from you against _groff_ in the past 2 years. Where did they go? And in contrast, you seem to have recognized some changes to _groff_'s _man_ and _tbl_ implementations as improvements. When italic font is requested in a section or subsection header, render it as bold italic, both for compatibility with groff-1.23 and because doing so makes sense logically - even though manual page authors are neither encouraged to manually manipulate fonts nor to use macros inside section headers. ... If the second argument to .Dt (the section number) is invalid, print "LOCAL" for the volume title, just like when the section number is missing. This improves compatibility with groff-1.23.0, and it's not a big deal because we don't use invalid section numbers in our manuals. ... Fix the logic for printing or skipping vertical spacing before a paragraph if the paragraph is at the beginning of an .RS block. In this case, rather than always printing the spacing as we did in the past, do the spacing as if the .RS block wouldn't be there. The new behaviour is compatible with groff-1.23. ... Change the footer line to always show NAME(SECTION) on the right hand side. The main reason for this change is to restore compatibility with groff-1.23, which changed from showing the operating system in this place to showing the page name in groff commit 5e9c49e1 (gbranden@ Sep 6, 2022). It also agrees better with what man(7) has done in groff since groff commit f1eb5d22 (wl@ Mar 20, 2001). The change also makes sense from a user perspective. At the end of a page, seeing the page name matters more than at the beginning, where the NAME section is always visible anyway. The user is not losing information because the operating system remains visible on the left hand side of the footer. ... Reduce the man(7) default global indentation from 7n, which was an oddity in groff-1.01 to groff-1.22.4, to 5n for compatibility with Version 7 AT&T UNIX, 4.3BSD-Reno, groff-1.23.0, and all versions of mdoc(7). ... Implement the man(7) .MR macro, a 2023 GNU extension. The syntax and semantics is almost identical to mdoc(7) .Xr. This will be needed for reading the groff manual pages once our port will be updated to 1.23, and the Linux Manual Pages Project is also determined to start using it sooner or later. I did not advocate for this new macro, but since we want to remain able to read all manual pages found in the wild, there is little choice but to support it. At least it is easy to do, they basically copied .Xr. ... Stop unconditionally emitting vertical space before .TS (table start). Same change as in groff commit 7ec36dc9 Jul 30 2022 gbranden@ For more details, see https://savannah.gnu.org/bugs/index.php?62841 This change makes sense because: * It improves the formatting of more pages than it degrades. * Existing manual pages are wildly inconsistent in which behaviour they expect: apparently few manual page authors understood the old rules. * It simplifies the rules of how .TS behaves in man(7) and makes them more similar to how it behaves in mdoc(7). * It improves flexibility, making it possible for a table to immediately follow preceding text without a blank line, which some existing pages want to use, for example XCreateWindow(3). ... Separate a vertical line on the left side of a table by horizontal whitespace of 1n from the content of the leftmost column, both when the line results from a table option (e.g. "box") and when it results from a '|' layout option. This is the same change as in groff commit 8f06678 Feb 3 02:22:02 2023 -0600 by gbranden@, which was released with groff-1.23.0. This does change the appearance of existing documents that use tbl(7), so technically, it's a backward-incompatible change, but it is highly unlikely to degrade formatting in any situation, it almost always looks better, and anyway, compatibility with modern groff matters more than compatibility with historical formatters and documents. ... Stop skipping vertical space after boxed tables. Skipping such space used to be a bug in GNU tbl(1), and a kludge was added to mandoc to produce identical output. The bug was fixed in groff commit 8818c07c Jul 30 2022 gbranden@ https://savannah.gnu.org/bugs/index.php?49390 Consequently, now is the time to get rid of the kludge. ... > I'm now almost done; only three regressions remain to be dealt with, and one > (simple) feature improvement where mandoc needs to catch up. I see. Perhaps you are using "regression" in the specialized sense of "causes failures in an automated test harness which validates consistent output down to the byte". That's a good property for a regression test suite to have; unfortunately, neither the _troff_ formatter nor the _man_ and _mdoc_ macro packages are sufficiently rigidly specified for byte-precise output to be predicted even in "_nroff_ mode", let alone when producing output for a typesetter. It appears to me that most of the _groff_-citing revisions you've made to _mandoc_(1) over the past years have been to (1) adopt changes from _groff_ you evaluated as good ideas that were within the parameters of the system's informal specifications, (2) recognize _groff_'s adoption of _mandoc_(1) changes, or (3) adopt new features of _groff_ _man_ (which I have, incidentally, tried to keep to a minimum). As an example of (1), I point to the _tbl_ left-hand vertical rule (line) separation issue. Further, I would also point out that one change you identified as a _groff_-1.23.0-ism doesn't actually seem to be. The description is not precise enough for me to be sure... Fix the logic for printing or skipping vertical spacing before a paragraph if the paragraph is at the beginning of an .RS block. In this case, rather than always printing the spacing as we did in the past, do the spacing as if the .RS block wouldn't be there. The new behaviour is compatible with groff-1.23. ...but when I render all of _mandoc_'s tests, as of CVS today, that seem relevant with _groff_ 1.22.4 and _groff_ 1.23.0, I see no changes fitting this description. Observe. $ ~/groff-1.22.4/bin/groff -man -Tascii -Z ~/src/CVS/mandoc/regress/man/RS/*.in | grotty -cbou >| /tmp/1224 $ ~/groff-1.23.0/bin/groff -man -Tascii -Z ~/src/CVS/mandoc/regress/man/RS/*.in | grotty -cbou >| /tmp/1230 $ diff -u /tmp/1224 /tmp/1230 --- /tmp/1224 2025-07-27 17:19:05.136032130 -0500 +++ /tmp/1230 2025-07-27 17:19:14.712016290 -0500 @@ -1,7 +1,5 @@ RS-REARG(1) General Commands Manual RS-REARG(1) - - NAME RS-REarg - arguments to the RE macro @@ -18,12 +16,10 @@ level 3 back to 1 - - + December 21, 2018 RS-REARG(1) +------------------------------------------------------------------------------- RS-AN-MARGIN(1) General Commands Manual RS-AN-MARGIN(1) - - NAME RS-an-margin - reStructuredText peeks at an internal register @@ -34,12 +30,10 @@ back to zero indent 168 back to regular text 168 - - + June 13, 2017 RS-AN-MARGIN(1) +------------------------------------------------------------------------------- RS-BREAKING(1) General Commands Manual RS-BREAKING(1) - - NAME RS-breaking - some block gets broken by an RS block @@ -54,12 +48,10 @@ indented text trailing text - - + 7 July 2012 RS-BREAKING(1) +------------------------------------------------------------------------------- RS-BROKEN(1) General Commands Manual RS-BROKEN(1) - - NAME RS-broken - indented blocks broken by other blocks @@ -94,12 +86,10 @@ final text - - + November 13, 2023 RS-BROKEN(1) +------------------------------------------------------------------------------- RS-EMPTY(1) General Commands Manual RS-EMPTY(1) - - NAME RS-empty - empty margin reset blocks @@ -109,12 +99,10 @@ indented text regular text - - + July 17, 2012 RS-EMPTY(1) +------------------------------------------------------------------------------- RS-FRACTION(1) General Commands Manual RS-FRACTION(1) - - NAME RS-fraction - indentation by non-integer multiples of EN @@ -133,11 +121,10 @@ back to 2.5n regular text - + July 23, 2025 RS-FRACTION(1) +------------------------------------------------------------------------------- RS-LITERAL(1) General Commands Manual RS-LITERAL(1) - - NAME RS-literal - indented literal text @@ -154,12 +141,10 @@ ENDTEST end of file - - + January 5, 2019 RS-LITERAL(1) +------------------------------------------------------------------------------- RS-LONELYRE(1) General Commands Manual RS-LONELYRE(1) - - NAME RS-lonelyRE - closing RS that is not open @@ -176,12 +161,10 @@ line, such that we can see the hanging indentation. out of body - - + November 10, 2013 RS-LONELYRE(1) +------------------------------------------------------------------------------- RS-NESTED(1) General Commands Manual RS-NESTED(1) - - NAME RS-nested - various blocks nested inside reset blocks @@ -205,8 +188,8 @@ tag text (6n) - hanged This is very long text. Let's see where it will break the - line, and which indent the next line will have - hope- + hanged This is very long text. Let's see where it will break the + line, and which indent the next line will have - hope- fully 12n. outer text @@ -216,12 +199,10 @@ inner text - - + April 4, 2015 RS-NESTED(1) +------------------------------------------------------------------------------- RS-NORE(1) General Commands Manual RS-NORE(1) - - NAME RS-noRE - unclosed indented block @@ -229,12 +210,10 @@ regular text indented text - - + June 20, 2014 RS-NORE(1) +------------------------------------------------------------------------------- RS-NESTED(1) General Commands Manual RS-NESTED(1) - - NAME RS-nowidth - indentation blocks not specifying a width @@ -249,12 +228,10 @@ top-level indented list regular text - - + April 6, 2015 RS-NESTED(1) +------------------------------------------------------------------------------- RS-PARAGRAPH(1) General Commands Manual RS-PARAGRAPH(1) - - NAME RS-paragraph - interaction between regular and indented paragraphs @@ -274,12 +251,10 @@ ENDTEST end of file - - + July 2, 2025 RS-PARAGRAPH(1) +------------------------------------------------------------------------------- RS-WIDTH(1) General Commands Manual RS-WIDTH(1) - - NAME RS-width - negative and excessive indentation @@ -296,6 +271,4 @@ text regular text - - December 23, 2014 RS-WIDTH(1) So before you hastily accuse me of making gratuitous changes and not knowing what I'm doing, I suggest you be able to demonstrate that fact. (It's not difficult; I discover my own errors all the time, as even a brief perusal of _groff_'s Git history reveals.) I sort the foregoing differences into a few buckets: 1. _groff_ 1.23.0 puts less vertical space between the headers/footers and the body text (in "continuous rendering mode", the default for _nroff_-mode output). 2. _groff_ 1.23.0 renders a footer for every document, not just the last one. That's a bug fix. 3. _groff_ 1.23.0 formats a horizontal rule between every document when rendering more than one. The only other change I see looks like a difference in "adjustment parity" in the "RS-nested" exhibit, which happens to be tangentially relevant to broader discussion of this ticket because _mandoc_ always disables adjustment. I could have added '-dAD=l' to my command lines, but that wouldn't have done any good--it wouldn't have affected _groff_ 1.22.4 output **because allowing the user to disable adjustment at the command line was a new feature of _groff_ 1.23**. > And i got these massive amounts of dysfunctionality Where? Show me! If _groff_ is defective, send me bug reports. If what you object to is the simple fact of _groff_'s resumed _development_ of its _man_ macro package, after a long period of it being nearly moribund, we may be at an impasse. > even though i switch off whatever overengineering i can. I assume that you're talking about disabling adjustment and hyphenation. As of _groff_ 1.23.0, both are easily done ("-dAD=l -rHY=0"). That provision, however, is not going to protect us from diverging with respect to other aspects of *roff and its macro packages, which are often, as I said, under-specified. > I have no idea what users may be suffering who actually try to _use_ any of > that overengineered stuff. I don't have any idea, either, when they fail to raise complaints in any forum where I can see them. And I do go looking. > I believe the only chance to get all this into a better shape and make it > less painful and more stable is massively cutting back on the complexity and > the overengineering such that you get a better chance of actually > understanding what you are doing. If you have a _concrete_ proposal with _specifics_, make it. > Piling more and more and more useless complication on top is not buying you > anything but lots of bugs, and dealing with that is very painful for any > downstream system that cares about software quality and reliability. I strongly desire enhancement of _groff_'s automated test suite, which is a _demonstrable_ means of ensuring software quality and reliability--contrast with hand-wavy assertions like "layering violations" or, more typical of BSD partisans, "not being written in C++" or "not being copylefted". > I don't think it's fair to build more and more elaborate castles in the sky > and let downstreams sort out the consequences and suffer the resulting > havoc. Give me a way to quantify "castles in the sky". Show me reproducible test cases of "havoc". Now, finally, to get back to the point of this ticket: I don't expect my proposed (and in progress) changes to _groff_ to inconvenience _mandoc_ in any way, and that accommodation was in fact a design criterion for me. Because _mandoc_ always aligns left (i.e., disables adjustment) and always disables automatic hyphenation, it does not need to pay any attention to these mechanisms. You don't need to recognize or interpret an assignment to the `AD` string. You don't need to recognize or interpret an assignment to the `HY` register. You don't need to interpret `nh` or `hy` requests (let alone _groff_'s many extensions for fine-tuning hyphenation determinations, added by James Clark). You don't need to interpret the `\%` escape sequence, except to silently discard it. You don't need to interpret `na` or `ad` requests. You don't need to interpret the `\p` escape sequence, except to silently discard it. You **definitely** don't need to worry about the package-internal objects I'm adding to "tmac/an.tmac" to track the user's configured preferences for adjustment and automatic hyphenation. I hope no one ever does; if I catch anyone accessing them in the wild, I'll be strongly tempted to rename them. They are **internal**, and people should keep their hands off of them. To conclude, concrete and specific defect reports will motivate and persuade me better than insults of my intelligence or work product. _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?67363> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/
signature.asc
Description: PGP signature
