Re: emacs-28 b4f47d2: Use @pxref when necessary

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Eli Zaretskii]

> branch: emacs-28
> commit b4f47d2ee2203a9f22bebeb3d09e0fb3fce2f65e
> Author: Robert Pluim <rpluim@gmail.com>
> Commit: Robert Pluim <rpluim@gmail.com>
> 
>     Use @pxref when necessary
>     
>     * doc/lispref/customize.texi (Composite Types):
>     * doc/lispref/edebug.texi (Specification List):
>     * doc/lispref/variables.texi (Local Variables):
>     * doc/misc/efaq.texi (Basic keys):
>     (Informational files for Emacs):
>     * doc/misc/flymake.texi (Locating a master file):
>     * doc/misc/gnus.texi (Don't Panic):
>     (Oort Gnus):
>     * doc/misc/htmlfontify.texi (Non-interactive):
>     * doc/misc/mh-e.texi (More About MH-E):
>     * doc/misc/pcl-cvs.texi (Entering PCL-CVS):
>     * doc/misc/tramp.texi (Remote processes):
>     * doc/misc/vhdl-mode.texi (Indentation Calculation):
>     (Custom Indentation Functions): Use @pxref when inside parens.

Please don't install cleanups on the release branch.  It isn't worth
even the tiniest risk of gratuitously breaking that branch, even if
this is only in the docs.

I reverted the changeset after merging it to master.

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Robert Pluim]

>>>>> On Wed, 24 Nov 2021 21:39:52 +0200, Eli Zaretskii <eliz@gnu.org> said:

    Eli> Please don't install cleanups on the release branch.  It isn't worth
    Eli> even the tiniest risk of gratuitously breaking that branch, even if
    Eli> this is only in the docs.

This contradicts statements you've made in the past about how
documentation-only changes are OK for the release branch. If it's now
in a different state than 'bugfix + doc only', then that should be
announced.

Robert
-- 

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: emacs-devel@gnu.org
> Date: Thu, 25 Nov 2021 09:20:22 +0100
> 
> >>>>> On Wed, 24 Nov 2021 21:39:52 +0200, Eli Zaretskii <eliz@gnu.org> said:
> 
>     Eli> Please don't install cleanups on the release branch.  It isn't worth
>     Eli> even the tiniest risk of gratuitously breaking that branch, even if
>     Eli> this is only in the docs.
> 
> This contradicts statements you've made in the past about how
> documentation-only changes are OK for the release branch. If it's now
> in a different state than 'bugfix + doc only', then that should be
> announced.

Fixes for the documentation are always safe, but that change was not a
fix, as there was no problem that needed to be fixed.

But if it sounds like a contradiction to someone, please consider the
above clarification as the announcement you asked for.

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Robert Pluim]

>>>>> On Thu, 25 Nov 2021 10:44:40 +0200, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Robert Pluim <rpluim@gmail.com>
    >> Cc: emacs-devel@gnu.org
    >> Date: Thu, 25 Nov 2021 09:20:22 +0100
    >> 
    >> >>>>> On Wed, 24 Nov 2021 21:39:52 +0200, Eli Zaretskii <eliz@gnu.org> said:
    >> 
    Eli> Please don't install cleanups on the release branch.  It isn't worth
    Eli> even the tiniest risk of gratuitously breaking that branch, even if
    Eli> this is only in the docs.
    >> 
    >> This contradicts statements you've made in the past about how
    >> documentation-only changes are OK for the release branch. If it's now
    >> in a different state than 'bugfix + doc only', then that should be
    >> announced.

    Eli> Fixes for the documentation are always safe, but that change was not a
    Eli> fix, as there was no problem that needed to be fixed.

The generated info manuals displayed "(see see" when viewed inside
Emacs, because thatʼs what "(see @ref" produces, unlike "(@pxref".

    Eli> But if it sounds like a contradiction to someone, please consider the
    Eli> above clarification as the announcement you asked for.

Robert
-- 

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: emacs-devel@gnu.org
> Date: Thu, 25 Nov 2021 09:47:34 +0100
> 
>     Eli> Fixes for the documentation are always safe, but that change was not a
>     Eli> fix, as there was no problem that needed to be fixed.
> 
> The generated info manuals displayed "(see see" when viewed inside
> Emacs, because thatʼs what "(see @ref" produces, unlike "(@pxref".

This problem should be fixed in info.el, not in the Texinfo sources.
(It should have been mentioned in the log message as well, btw.)
There's nothing wrong with "see @ref" from the Texinfo usage POV.
Moreover, some old enough versions of makeinfo don't produce correct
output from @pxref that is not the first and the only one in
parentheses, or is not in parentheses at all.

I don't object to the change in the sources, either (which is why I
did merge the change to master), but the change wasn't trivial and
could have had unintended consequences where I didn't see any real
problem to fix in the first place.

Thanks.

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Robert Pluim]

>>>>> On Thu, 25 Nov 2021 11:03:38 +0200, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Robert Pluim <rpluim@gmail.com>
    >> Cc: emacs-devel@gnu.org
    >> Date: Thu, 25 Nov 2021 09:47:34 +0100
    >> 
    Eli> Fixes for the documentation are always safe, but that change was not a
    Eli> fix, as there was no problem that needed to be fixed.
    >> 
    >> The generated info manuals displayed "(see see" when viewed inside
    >> Emacs, because thatʼs what "(see @ref" produces, unlike "(@pxref".

    Eli> This problem should be fixed in info.el, not in the Texinfo sources.
    Eli> (It should have been mentioned in the log message as well, btw.)
    Eli> There's nothing wrong with "see @ref" from the Texinfo usage
    Eli> POV.

This is "(see @ref", not "see @ref". The latter works correctly. Maybe
this can be fixed in info.el as you say (it would certainly clean up
the display of org.info).

Robert
-- 

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Date: Thu, 25 Nov 2021 10:19:22 +0100
> Cc: emacs-devel@gnu.org
> 
>     Eli> This problem should be fixed in info.el, not in the Texinfo sources.
>     Eli> (It should have been mentioned in the log message as well, btw.)
>     Eli> There's nothing wrong with "see @ref" from the Texinfo usage
>     Eli> POV.
> 
> This is "(see @ref", not "see @ref". The latter works correctly. Maybe
> this can be fixed in info.el as you say (it would certainly clean up
> the display of org.info).

So I guess it's this part of info.el that needs to become smarter:

              (when Info-hide-note-references
                (when (and (not (eq Info-hide-note-references 'hide))
                           (> (line-number-at-pos) 4)) ; Skip breadcrumbs
                  ;; *Note is often used where *note should have been
                  (goto-char start)
                  (skip-syntax-backward " ")
		  (when (memq (char-before) '(?\( ?\[ ?\{))
		    ;; Check whether the paren is preceded by
		    ;; an end of sentence
		    (skip-syntax-backward " ("))
                  (setq other-tag
			(cond ((save-match-data (looking-back "\\(^\\| \\)see"
                                                              (- (point) 4)))
			       "")
			      ((save-match-data (looking-back "\\(^\\| \\)in"
                                                              (- (point) 3)))
			       "")
			      ((memq (char-before) '(nil ?\. ?! ??))
                               "See ")
			      ((save-match-data
				 (save-excursion
				   (search-forward "\n\n" start t)))
			       "See ")
			      (t "see "))))

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Robert Pluim]

>>>>> On Thu, 25 Nov 2021 10:19:22 +0100, Robert Pluim <rpluim@gmail.com> said:
    Robert> This is "(see @ref", not "see @ref". The latter works correctly. Maybe
    Robert> this can be fixed in info.el as you say (it would certainly clean up
    Robert> the display of org.info).

Something like this, with 'Also *note'/'See also *note' as a bonus,
although that might be going a bit far.

diff --git a/lisp/info.el b/lisp/info.el
index 8c08eaec3c..40995d0ba1 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -4858,9 +4858,17 @@ Info-fontify-node
 		    ;; an end of sentence
 		    (skip-syntax-backward " ("))
                   (setq other-tag
-			(cond ((save-match-data (looking-back "\\(^\\| \\)see"
+			(cond ((save-match-data (looking-back "\\(^\\|[ (]\\)see"
                                                               (- (point) 4)))
 			       "")
+                              ((save-match-data (let ((case-fold-search nil))
+                                                  (looking-back "\\(^\\| \\)also"
+                                                              (- (point) 5))))
+			       "")
+                              ((save-match-data (let ((case-fold-search nil))
+                                                  (looking-back "\\(^\\| \\)Also"
+                                                              (- (point) 5))))
+			       "see ")
 			      ((save-match-data (looking-back "\\(^\\| \\)in"
                                                               (- (point) 3)))
 			       "")

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: emacs-devel@gnu.org
> Date: Thu, 25 Nov 2021 11:18:03 +0100
> 
> >>>>> On Thu, 25 Nov 2021 10:19:22 +0100, Robert Pluim <rpluim@gmail.com> said:
>     Robert> This is "(see @ref", not "see @ref". The latter works correctly. Maybe
>     Robert> this can be fixed in info.el as you say (it would certainly clean up
>     Robert> the display of org.info).
> 
> Something like this, with 'Also *note'/'See also *note' as a bonus,
> although that might be going a bit far.

"Also *note" that comes from "Also @ref" should be fine.  If you mean
"Also see @ref", which currently produces "Also see see", then yes, it
should be fixed as well.

Anyway, if this fixes the Org manual, feel free to install on master,
and thanks.

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Robert Pluim]

>>>>> On Thu, 25 Nov 2021 12:53:33 +0200, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Robert Pluim <rpluim@gmail.com>
    >> Cc: emacs-devel@gnu.org
    >> Date: Thu, 25 Nov 2021 11:18:03 +0100
    >> 
    >> >>>>> On Thu, 25 Nov 2021 10:19:22 +0100, Robert Pluim <rpluim@gmail.com> said:
    Robert> This is "(see @ref", not "see @ref". The latter works correctly. Maybe
    Robert> this can be fixed in info.el as you say (it would certainly clean up
    Robert> the display of org.info).
    >> 
    >> Something like this, with 'Also *note'/'See also *note' as a bonus,
    >> although that might be going a bit far.

    Eli> "Also *note" that comes from "Also @ref" should be fine.  If you mean
    Eli> "Also see @ref", which currently produces "Also see see", then yes, it
    Eli> should be fixed as well.

Not quite:

Before:

Texi                  Info display

"Also @ref"        => "Also see <link>"
"See @ref"         => "See <link>"
"Also see @ref"    => "Also see <link>"
"See also @ref"    => "See also see <link>"
"(Also @ref)"      => "(Also see <link>)"
"(See @ref)"       => "(See see <link>)"
"(Also see @ref)"  => "(Also see <link>)"
"(See also @ref)"  => "(See also see <link>)"

After:

"Also @ref"        => "Also see <link>"
"See @ref"         => "See <link>"
"Also see @ref"    => "Also see <link>"
"See also @ref"    => "See also <link>"
"(Also @ref)"      => "(Also see <link>)"
"(See @ref)"       => "(See <link>)"
"(Also see @ref)"  => "(Also see <link>)"
"(See also @ref)"  => "(See also <link>)"

    Eli> Anyway, if this fixes the Org manual, feel free to install on master,
    Eli> and thanks.

The org texi generation always produces @ref, even inside parens, so I
think itʼs the best we can do.

Robert
-- 

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: emacs-devel@gnu.org
> Date: Thu, 25 Nov 2021 15:38:02 +0100
> 
> Before:
> 
> Texi                  Info display
> 
> "Also @ref"        => "Also see <link>"
> "See @ref"         => "See <link>"
> "Also see @ref"    => "Also see <link>"
> "See also @ref"    => "See also see <link>"
> "(Also @ref)"      => "(Also see <link>)"
> "(See @ref)"       => "(See see <link>)"
> "(Also see @ref)"  => "(Also see <link>)"
> "(See also @ref)"  => "(See also see <link>)"
> 
> After:
> 
> "Also @ref"        => "Also see <link>"
> "See @ref"         => "See <link>"
> "Also see @ref"    => "Also see <link>"
> "See also @ref"    => "See also <link>"
> "(Also @ref)"      => "(Also see <link>)"
> "(See @ref)"       => "(See <link>)"
> "(Also see @ref)"  => "(Also see <link>)"
> "(See also @ref)"  => "(See also <link>)"

LGTM, thanks.

Re: emacs-28 b4f47d2: Use @pxref when necessary

[Robert Pluim]

>>>>> On Thu, 25 Nov 2021 18:54:02 +0200, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Robert Pluim <rpluim@gmail.com>
    >> Cc: emacs-devel@gnu.org
    >> Date: Thu, 25 Nov 2021 15:38:02 +0100
    >> 
    >> Before:
    >> 
    >> Texi                  Info display
    >> 
    >> "Also @ref"        => "Also see <link>"
    >> "See @ref"         => "See <link>"
    >> "Also see @ref"    => "Also see <link>"
    >> "See also @ref"    => "See also see <link>"
    >> "(Also @ref)"      => "(Also see <link>)"
    >> "(See @ref)"       => "(See see <link>)"
    >> "(Also see @ref)"  => "(Also see <link>)"
    >> "(See also @ref)"  => "(See also see <link>)"
    >> 
    >> After:
    >> 
    >> "Also @ref"        => "Also see <link>"
    >> "See @ref"         => "See <link>"
    >> "Also see @ref"    => "Also see <link>"
    >> "See also @ref"    => "See also <link>"
    >> "(Also @ref)"      => "(Also see <link>)"
    >> "(See @ref)"       => "(See <link>)"
    >> "(Also see @ref)"  => "(Also see <link>)"
    >> "(See also @ref)"  => "(See also <link>)"

    Eli> LGTM, thanks.

Pushed, thanks.

Robert
--