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

[Stefan Kangas]

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
> even run "make" after they install documentation changes, or don't
> look at messages when they do (because when I run it, I see warning
> and error messages), so why should we assume someone will run some
> Lisp in addition to that?

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?

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?

>> 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.  By contrast, Git commit hooks are a pest when they
> fire due to false positives.  So I wouldn't bother.

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.

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.

(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.)

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