Hi Branden,
G. Branden Robinson wrote on Mon, Jan 19, 2026 at 11:29:49AM -0600:
> At 2026-01-19T11:55:49+0100, Ingo Schwarze wrote:
>> I had to look up what \n[.y] even is, and now i find it weird that
>> this register exists at all.
> I think you mean `\n[.Y]`--uppercase.
True - .Y is what you brought up as causing issues in the past on an
occasion where version strings were handled in a less than perfect way,
if i understood your point correctly.
That said, my unease quoted above applies to both .y and .Y, actually.
> To refresh readers:
> $ nroff -t -man -P -cbou $(man -w 'groff(7)') | grep '\n\[\.[XxYy]]'
> \n[.x] Major version number of the running troff formatter.
> \n[.y] Minor version number of the running troff formatter.
> \n[.Y] Revision number of the running troff formatter.
>
> (Why not `.z`? Ossanna troff already used that for another purpose.
> But this may be fortunate, since as you note, people should likely not
> employ `.Y` for the same sorts of purposes as `.x` and `.y` anyway.)
>> That's not something documents should access or depend on.
> I think you're taking a sound principle and carrying it a little too
> far. I'll explain.
>
> I don't think a _visible interface change_, meaning something one can
> write *roff document (or macro file) logic depending on, should be
> accompanied by anything less than a minor version bump.
I agree with that sentence. If a feature is added to the user interface,
bump at least the minor.
> (I'll qualify this claim below.)
>
> However, I have actually used the feature myself not to manage flow of
> control, but simply to annotate a reconstructed document with the
> identity of its formatter.[2] After all, the date isn't part of the
> formatter interface either, so why do we have the crap below?
>
> $ nroff -t -man -P -cbou $(man -w 'groff(7)') \
> | grep -E '\n\[(year|yr|mo|dy|dw|hours|minutes|seconds)]'
> \n[dw] Day of the week (1–7; 1 is Sunday).
> \n[dy] Day of the month (1–31).
> \n[hours] Count of hours elapsed since midnight (0–23).
> \n[minutes] Count of minutes elapsed in the hour (0–59).
> \n[mo] Month of the year (1–12).
> \n[seconds] Count of seconds elapsed in the minute (0–60).
> \n[year] Gregorian year.
> \n[yr] Gregorian year minus 1900.
I agree, none of that is valuable.
$ cat | mandoc
.nf
\n[dw] Day of the week (1-7; 1 is Sunday).
\n[dy] Day of the month (1-31).
\n[hours] Count of hours elapsed since midnight (0-23).
\n[minutes] Count of minutes elapsed in the hour (0-59).
\n[mo] Month of the year (1-12).
\n[seconds] Count of seconds elapsed in the minute (0-60)
\n[year] Gregorian year.
\n[yr] Gregorian year minus 1900.
^D
() ()
0 Day of the week (1-7; 1 is Sunday).
0 Day of the month (1-31).
0 Count of hours elapsed since midnight (0-23).
0 Count of minutes elapsed in the hour (0-59).
0 Month of the year (1-12).
0 Count of seconds elapsed in the minute (0-60)
0 Gregorian year.
0 Gregorian year minus 1900.
In manual pages, using these is clearly detrimental. The content of
documentation should not depend on the date or time of formatting.
If anything, only the date and time of the software being documented
or the last update of the documentation should be mentioned.
For documents that are not manual pages, making a case for such
registers is slightly easier - but even there, i claim that using
them is detrimental more often than useful. For example, how often
have i looked at business letter documents written by others and
went "wait, what? this clearly wasn't written *today*. So, when
was this written and sent out? Let's look at the file modification
date. Oh, that can't be right either - apparently someone modified it
after the fact or copied it around." Wouln't it be great if you
could find the real date of a real letter by the author actually
putting that date into the file, rather then putting a macro there
that will start lying the very next day?
> For the limited purpose of disclosing information about the formatter
> itself or its operating environment[3], it seems fine to me,
Maybe, except that you almost never need or want such information
as part of the rendered document. Instead, use the system package
manager to find out which versions of software you are running,
and use date(1) to find out what time it is.
[...]
> So, unlike you, I don't need smelling salts to cope with `\n[.Y]`.
> But it should be used only advisedly.
Yeah, kind of. Anyway, trying to kill it now would likely cause minor
trouble for almost no benefit.
I think what we should have right nor is:
\n[.x] 1
\n[.y] 24
\n[.Y] 0
extraction directory name groff-1.24.0 or groff-1.24.0rc1,
whichever you like better
tarball name groff-1.24.0rc1.tar.gz
[...]
> I think it was Bertrand who put in some machinery tying Git, Autoconf,
> and Automake together to construct the name of the directory (and
> therefore the tar archive).
Yes, some kind of automation is likely helpful in this respect.
For example, mandoc/Makefile contains:
VERSION = 1.14.6
dist: mandoc-$(VERSION).sha256
mandoc-$(VERSION).sha256: mandoc-$(VERSION).tar.gz
sha256 mandoc-$(VERSION).tar.gz > $@
mandoc-$(VERSION).tar.gz: $(DISTFILES)
ls regress/*/*/*.mandoc_* && exit 1 || true
mkdir -p .dist/mandoc-$(VERSION)/
$(INSTALL) -m 0644 $(DISTFILES) .dist/mandoc-$(VERSION)
cp -pR regress .dist/mandoc-$(VERSION)
find .dist/mandoc-$(VERSION)/regress \
-type d -name CVS -print0 | xargs -0 rm -rf
chmod 755 .dist/mandoc-$(VERSION)/configure
( cd .dist/ && tar zcf ../$@ mandoc-$(VERSION) )
rm -rf .dist/
That kind of thing...
Of course, such automation can be overengineered, but i'm neither claiming
what Bertrand did is overengineered nor that it is simple.
> I failed to exercise that machinery for
> rc1, and simply renamed the archive (which "make dist" had made for me)
> for upload to alpha.gnu.org. That was a mistake, which you and Colin
> pointed out.
>
> https://savannah.gnu.org/bugs/?67933
>
> I have a change in my working copy that intends to resolve that
> ticket.[5]
Thank you!
> Also, `.Y` _does_ report `0`, even with a build from the weirdly-named-
> when-unpacked rc1 archive. If you're seeing something else, I want to
> hear about it.
I'm still quite far away from getting groff-1.24.0rc1 to build,
let alone run, so i can't answer that just yet.
[...]
> But if you mean "a number is a decimal integer", then yes.
Nonono, i consider calling 1.24.0 a "version number" reasonable enough.
Nobody, not even a die-hard algebraist, is calling that a "version module
element" because of https://en.wikipedia.org/wiki/Module_(mathematics) :-D
You are right that i merely had my letter case scrambled.
Yours,
Ingo
