Hi Stephen, At 2026-11-11T10:55:29-0800, Stephen Gildea wrote: > Branden, thank you for your work creating groff 1.25 and especially > for your work on making man pages easier to write.
Thank _you_ for saying so. Some days it feels like I'm bailing out the ocean with a thimble. :) > You offered me a chance to test the beta release, and I failed > to take advantage of this. (I could not get it to build from > source in my environment and eventually gave up.) Hmm, that's both worrisome and surprising. Nelson H. F. Beebe reported broad success with builds of groff 1.25.0 from its source archive in many environments. https://lists.gnu.org/archive/html/groff/2026-11/msg00033.html When you get time, I'm curious to know details of the build failure you're seeing. > I'm particularly sorry because now I see that groff 1.25.0 is blocked > from Debian Testing in part because of a failure in one of the tests > in my package xlbiff. > > My test runs this command: > > groff -man -ww -z -rCHECKSTYLE=3 ./xlbiff.man > > and it fails with a bunch of these: > > warning: end of sentence detected before end of text line [-w style] > > It seems that groff 1.25 adds a new style check that > xlbiff.man does not comply with. Right. That's expected. > I will update the xlbiff package to work with groff 1.25.0. You don't have to edit the man page sources, and I would not advise you to hurriedly do so. You could alter your test. -groff -man -ww -z -rCHECKSTYLE=3 ./xlbiff.man +groff -man -ww -Wstyle -z -rCHECKSTYLE=3 ./xlbiff.man > However, this new groff behavior is arguably a regression. It seems > to me that a new style test should be opt-in, giving users such as > myself a chance to request the new style check only after we have > updated our documents to the new requirement. I gave this quite a bit of thought. Here's the problem I faced. troff(1): Two warning names group other warning categories for convenience. all All warning categories except di, mac, reg, and style. This shorthand is intended to produce all warnings that are useful with macro packages and documents written for AT&T troff and its descendants, which have less fastidious diagnostics than GNU troff. w All warning categories. Authors of documents and macro packages targeting groff are encouraged to use this setting. I wanted a new warning category, because adding the new warnings I was implementing to any existing category would have been flagrantly, obviously wrong and would doubtless have upset people. Also, the stuff I wanted to issue style warnings for, the formatter is unquestionably the best place to perform the syntax checks in question. *roff is not what Ralf Treinen and others might call a "statically decidable" language. To perform syntax checks on *roff, you must interpret *roff. In *roff, you can do crazy things like redefine the control and escape characters. In C, this is like being able to change braces to some other symbols. And to be able to do so dynamically within a brace scope. So, I have to have a new warning category. The name is/was easy. style 16 Input was non‐idiomatic or likely to produce an unexpected result (or none at all), but is not invalid: a brace escape sequence was employed uselessly; an in‐ or decrementing interpolation was applied to a register that lacked an auto‐ in‐ or ‐decrement amount; the end of a sentence was detected prior to the end of a text line; or an attempt was made to combine temporary indentation with centering or right‐alignment. (The foregoing language is from bleeding-edge post-1.25.0 Git.) So which shorthand should group it? "all"? This shorthand is intended to produce all warnings that are useful with macro packages and documents written for AT&T troff and its descendants, which have less fastidious diagnostics than GNU troff. Probably not. That's for fast and loose old AT&T style documents. And it would not have altered your situation had I grouped it there. What about "w"? w All warning categories. Authors of documents and macro packages targeting groff are encouraged to use this setting. But, as you say, this means people who weren't getting warnings before might get them now. We already have an "all" that doesn't mean "all", and a "w" that means "really all". Should we now have a "really all" that isn't "really all"? Should we have a "extra", so that you have to now say "groff -ww -wextra" if you _really_ want _all_ warnings, for real? And what if GNU troff grows yet _another_ new warning category in the future? Does "-ww -wextra" really mean "all the warnings, damn it", or merely "all the warnings as of groff 1.25"? You may begin to perceive my dilemma. One should not have to employ mathematical induction to reason about GNU troff warnings. Having already been saddled with an "all" that doesn't _really_ mean "all", I decided that the "grouping" warning categories needed to have flexible semantics, even though I try to ensure that the semantics of all the "real" categories are fairly rigid. Also, in principle, all the warnings in category "style" that I've implemented are useful in AT&T troff documents. Thus, the configuration "troff -wall -wstyle" is not a crazy thing to do. As you might have noticed, GNU troff's warnings now identify the warning category they belong to, so when someone feels their blood pressure rising due to one of my warnings, they know exactly which button to jab to silence the noise and avoid an ischemic brain injury. > warning: end of sentence detected before end of text line [-w style] > I'm not sure why groff cares that documents start each sentence on a > new source line. Yes, I recognize the advantage for reading, editing, > and smaller diffs. However, there are times where I want the source > text filled. In this particular case, I have the same paragraph in > xlbiff.man and Readme.md. In the markdown file, I want the source > file to be pretty, too, so the paragraph is filled in the source. I raise no objection to your practice. Maintain your man pages in a way that makes sense for your projects. But you might want "-W style". > I'm also unclear about what I'm doing wrong with my sentence > endings. Mid-line, I put one space after a period signifying > an abbreviation, and two spaces after a period at the end of > sentence. Isn't that what groff wants? The warning isn't necessarily trying to tell you that the formatting of your document will not be what you expect; we can't know how good your command of *roff's supplemental inter-sentence application rules is. And in any case, you can change those rules via the `cflags` request and the two-argument form of the `ss` request. Moreover, text editors don't always judge sentence boundaries according to *roff rules themselves, so when reflowing in the editor, "good" inter-sentence spacing might be damaged.[1] What we're telling the user is that their input is non-idiomatic. https://rhodesmill.org/brandon/2012/one-sentence-per-line/ That said, it sometimes makes sense to apply non-roff idioms. Thus, `-W style`. > I'm not sure of the correct forum for this discussion; please forward > and/or cc as you see fit. The groff discussion list is just fine. CCing accordingly. I hope I've illuminated the issue to the point where I'm making sense. Let me know if I can be of further assistance. Regards, Branden [1] In fact, if someone _does_ use the `cflags` and `ss` requests to reconfigure how GNU troff recognizes and handles sentence endings, the text editor has a nigh impossible task.
signature.asc
Description: PGP signature
