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

[Pip Cet]

"Eli Zaretskii" <eliz@gnu.org> writes:

>> From: Stefan Kangas <stefankangas@gmail.com>
>> Date: Sat, 18 Jan 2025 21:08:41 -0600
>>
>> Po Lu <luangruo@yahoo.com> writes:
>>
>> > Stefan Kangas <stefankangas@gmail.com> writes:
>> >
>> >> branch: master
>> >> commit e54b94c28cdf9699009e7691f7c8ffa5b2c7b741
>> >> Author: Stefan Kangas <stefankangas@gmail.com>
>> >> Commit: Stefan Kangas <stefankangas@gmail.com>
>> >>
>> >>     Use @xref more consistently; "See @ref" -> "@xref"
>> >>
>> > This is not appropriate, as "@xref" is supposed only to be used before a
>> > punctuation character, either a period or a comma.  I will revert this
>> > build-breaking change.
>> >
>> >        Caution: A period or comma must follow the closing brace of an
>> >        @xref.  It is required to terminate the cross reference.  This
>> >        period or comma will appear in the output, both in the Info file
>> >        and in the printed manual.
>>
>> If a revert is appropriate, the polite thing to do is to ask the person
>> who made the change to revert it.  Please do that in the future.
>>
>> My Texinfo documentation doesn't have the above warning, and the build
>> didn't break here.  Please tell which version of makeinfo you are using,
>> and what are the errors you see.  Thanks.
>
> This requirement was removed in recent versions of makeinfo, but we

So it was turned from a fatal error to "not even a warning", with no
intermediate stage?  That seems highly unusual to me.  Is there no easy
way to enable the warning?

> need to have punctuation after each cross-reference command (with the
> sole exception of @pxref, which does this automatically) to support
> such old versions.

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?

(defun check-texinfo-style (&optional directory)
  (unless directory (setq directory default-directory))
  (dolist (f (directory-files-recursively
              (expand-file-name directory)
              (rx (* anything) ".texi" string-end)))
    (with-temp-buffer
      (insert-file-contents f)
      (goto-char (point-min))
      (while (re-search-forward (rx (or "@xref" "@ref")) nil t)
        (goto-char (match-end 0))
        (or
         (save-excursion
           (beginning-of-line)
           (looking-at-p "%"))
         (let (arg)
           (while (cond ((looking-at-p (rx white))
                         (forward-char)
                         t)
                        ((looking-at-p (rx "{"))
                         (forward-sexp 1)
                         (setq arg t))))
           (when (and arg
                      (looking-at-p (rx alnum)))
             (while (memq (char-before) (list ?\ ?\n ?))
               (forward-char -1))
             (insert "!")
             (write-file f))))))))

It doesn't seem to find any more cases.  Maybe there are more
"cross-reference commands" I'm unaware of, though.  (Please note this
program modifies files in the Emacs directory).

Certainly not perfect, but "watch out for this problem you cannot
detect" seems suboptimal to me.

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.

Pip