Hi Alex, At 2023-05-31T23:39:34+0200, Alejandro Colomar wrote: > Will do; thanks for the link.
...and there it is! Savannah #64267. > mandoc(1) warns about empty paragraphs. I believe it should warn in > this case too. > > $ cat ip.man > .TH A s 2000-02-02 f > .SH Foo > .IP > foo > .IP > .SH Bar > bar > $ mandoc -Tlint ip.man > mandoc: ip.man:5:2: WARNING: skipping paragraph macro: IP empty > > This warning is very useful, and has caught many many mistakes in the > Linux man-pages. That may be, but this is tedious to do in a roff as generally as you're going to want it. I think it _can_ be done, but I fear it's going to look a lot like some code I recently refactored out of groff mm(7).[1] if !((\\n[nl]=\\n[hd*last-pos])&(\\n[hd*last-hsize]=\\n[.k])) Algebraically that's not too complicated, but it doesn't take much *roff expression syntax to terrify people, and that exhibit may be well over the limit for the population of *roff users that aren't also macro package authors. > Here was a difference: the paragraphs did have at least a "bullet". > In the report, there's nothing at all. That would mean I have to track two things: was there a tag (pretty easy) and was there any "body" to the paragraph? But the body of a paragraph is formatted outside of the context of _any_ macro call. This fact will lead to stupid tricks like saving the vertical and horizontal drawing positions on the way out of paragraphing macros and testing them upon hitting the next paragraph or sectioning macro. Ways of breaking such a test are already springing to mind. `\Z`, for one. In the future, if I realize my ambition of forcing all man(7) paragraphing macros to format all paragraphs in diversions first, so as to break them in a way that avoids widows and orphans,[2] then it will be worth reconsidering this resistance, since I'll already have a diversion (or two) for which the formatter helpfully already supplies dimensions in the `dn` and `dl` registers. > > While I have proposed that `TP` be used for tags of indexable or > > semantic import, and `IP` for other sorts like bullets and list > > enumerators, whether it would be better to use `TP` for this > > application has no bearing here in my view. > > Yeah, I'd definitely prefer TP/TQ in this case. In fact, IIRC, I > fixed cases of this exact thing in the Linux man-pages recently. The > arguments to IP are not bullets, or enumerators, but actual tags. Cool. One day this work will pay off in a very nice way, I think. > P.S.: I just read your suggestion of using I instead of IR for > trailing punctuation after variable names. I'm not convinced at all. I used to be opposed to the idea (when I first started contributing to groff documentation), but experience has pushed me into the other camp. > It's more correct/precise to use IR, and the difference in typeset > output is probably minor. The difference in typeset materials is enough that I can notice it. Maybe becoming a groff developer has taught me to be sensitive to such things. Many years ago I was a conference, and the guy next to me complained about the slide that been thrown up; some large proportional text was displayed with no kerning adjustments.[3] I had to confess to him that I hadn't even noticed. These days, I would notice. The other question here is "correctness/precision". I agree that if one is semantically tagging a word or phrase, it properly ends before any trailing punctuation. And in fact I do not apply the practice we're discussing to the names of commands, topical keywords (like the names of tbl(1) region options or eqn(1) primitives), or man page titles. I've never seen anyone prepare an index of metasyntactic variable names on a document corpus as varied as the Unix Programmer's Manual. I don't think it would do any good. Man page authors are jaw-droppingly sloppy about the name conventions they use for such things, and these terms are going to have disparate and conflicting meanings anyway. That is why I decided in favor of typography over semantic precision in this instance. There is a way to have both at the same time. I'll preëmpt Ingo Schwarze by pointing out that mdoc(7) provides for it. The way it does it is by requiring you to input punctuation as independent tokens in macro calls. See subsection "General syntax" of groff_mdoc(7). I'm not sure, but I suspect that this feature is entangled with mdoc's support for macros that parse their own argument lists for the names of other macros to call. (Language in its manual like "This macro is called and parsable." is its mating cry.) That road, I don't want to go down with man(7). Follow-ups on this `I` vs. `IR` punctuation point should perhaps change the Subject: line of the mail. Regards, Branden [1] https://git.savannah.gnu.org/cgit/groff.git/commit/contrib/mm/m.tmac?id=814e204d1675ef9c6da4fb4e2736d5937256f106 [2] tbl(1)'s use of diversions might be the biggest obstacle here. [3] I wish I could remember who it was; I want to say either Joey Hess or Seth David Schoen. Just so I could tell them I've now seen the light,[4] and that I too suffer when bad typography is thrust at me. [4] or known sin
signature.asc
Description: PGP signature
