Re: master e54b94c28cd: Use @xref more consistently; "See @ref" -> "@xref"

[Pip Cet]

"Stefan Kangas" <stefankangas@gmail.com> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> Date: Thu, 23 Jan 2025 12:28:32 +0000
>>> From: Pip Cet <pipcet@protonmail.com>
>>> Cc: Stefan Kangas <stefankangas@gmail.com>, luangruo@yahoo.com, 
>>> emacs-devel@gnu.org
>>>
>>> So we need to check that @xref and @ref, except in comment lines, are
>>> followed by optional whitespace, a balanced sexp, optional whitespace,
>>> and a punctuation character? If texinfo really cannot do this, can this?
>>
>> Maybe it can, but why bother?  I've seen many times that people don't

Because it's not about fixing every last problem, it's about improving
things for people where we can do so.

>> even run "make" after they install documentation changes, or don't
>> look at messages when they do

I agree that's a difficult social problem, and not one we can solve
technically.

>> (because when I run it, I see warning and error messages),

That's a non sequitur: as this discussion shows, the problem is that
there is no reliable way to get what you might see as an error to even
produce a warning if a different version of texinfo is in use.  Thus my
idea of using a Lisp hack to work around this peculiar limitation.

>> so why should we assume someone will run some Lisp in addition to
>> that?

We can't make that assumption for everyone, but let's be realistic here:
Stefan Kangas pushed the commit.  I'm not sure whether he would have
used an additional make target, but I am sure that if the ordinary make
had included the linter, he would not have ignored the warning.

> FWIW, I think it would be useful to have a linter for texinfo that over
> time could be expanded to catch various errors.  I'm not sure that such
> a linter should be maintained by us, however, since it's probably more
> generally useful.  It might be better to ship it with texi2any.  But at
> that point: why not make texi2any itself warn?

texinfo seems to be a very daunting piece of software.  I spent too much
time trying to simply revert the part of the commit that removed the
warning (it included many other changes, but I didn't see anything about
it about getting the old warning behavior back), and that didn't work.

It seems to involve code in several languages, Perl, C, and some actual
TeX.  I'm not sure which part does what, to be honest.  I thought I was,
but then my change would have worked, so now I'm not.

> So while I applaud the effort of Pip Cet to automate away boring minutia
> such as this one, perhaps we should bring these ideas to the texinfo
> developers?

Now reported as a bug, let's see what happens.

>>> As a general remark, I'm (very slowly) thinking about how we might
>>> add pre-push checks that catch such things but don't slow down
>>> development too much. However, at least until then, we can also fix the
>>> two specific cases that have caused trouble: pdumper hashes and texinfo
>>> files.
>>
>> Errors in making documentation are not fatal, they just leave the Info
>> manuals outdated.

I'm afraid that for me, when "make" fails, that's a major inconvenience.

I'm not sure I've ever seen outdated Info manuals as a result of a build
with documentation errors.  If this isn't a normal make rule which
breaks the build when it fails, something isn't working correctly here.

To be perfectly honest, I find it hard not to be annoyed when setting up
a toolchain because the build breaks due to the non-availability of
texinfo.  While I'd never run a production Emacs without documentation,
for testing it would sometimes be appropriate, and the relevant
utilities simply aren't installed on the Solaris 10 machine I have
access to.

>> By contrast, Git commit hooks are a pest when they fire due to false
>> positives.  So I wouldn't bother.

I did not mean git hooks.  Git *commit* hooks are already over-used by
Emacs, and I'm not sure they're useful enough to be set up
automatically, without my explicit consent, whenever I run autogen.sh.

I'm not saying git hooks are entirely useless, but commit hooks in
particular feel like an unwarranted intrusion into my workflow.  I often
want to mark a temporary commit with DO NOT COMMIT, but that makes the
first line longer than some hook thinks it should be.

> Git hooks are quite useful, but hard to get general agreement on.
> AFAIK, we currently only warn for some uncontroversial things like
> trailing whitespace.  I don't know what else could similarly be
> uncontroversial enough to have on by default.

And even that causes trouble; I merged elisp-benchmarks in a local tree
and I'm pretty sure git sometimes decides to abort merges because of
whitespace errors in unaffected files (elisp-benchmarks has a few
whitespace errors; to be honest, the only reason I'm not ignoring them
is that git keeps complaining).

> We could have something that one could install and use optionally, but
> even then I'd request it to be very fast, so that the whole thing takes
> less than a fraction of a second to run.  Much more than that, and I'd
> probably just turn it off again.

I hope "make check" can be fixed, but right now it is that way for me.
It's still incredibly useful, but running it on an enable-checking build
without optimization requires some patience (it just did find a bug in
one of my patches, though).

And if the idea is to do the best we can in the limited time period
until the user confirms they do want to push (this is my idea of
zero-cost checking), always running the tramp tests first seems
suboptimal.  A good randomization strategy would be important; running a
full test matrix on every commit isn't viable.

(Running gcc's analyzer is useful, for example, but it requires several
hundred gigabytes of temporary storage and takes about an hour with
-flto -O3, which are necessary to find some bugs)

> (In projects at $WORK, we run an incredibly fast linter on every commit
> that finishes within in a couple of milliseconds.  It is very nice.)

I think it would be even better to start a background test which tries
to find problems as efficiently as possible in however much time you
give it, starting with the quickest tests (that's data we have; a better
prediction of the likelihood of failure would be hard) and only runnnig
the analyzer build if the user falls asleep.

> BTW, there was a claim that the missed comma with @xref was "build
> breaking".  Was that claim not correct?

Commit e6591b549f3 did break my build, but this one was fixed so quickly
that I didn't even merge it, so I can't tell.  Thanks again for that!

Pip