bug#44043: Info Files Showing "see" or "*note" when using @ref in source

bug#44043: Info Files Showing "see" or "*note" when using @ref in source

[Christopher Dimech]

Dear Compeers,

I have the following references using @ref to Node Names

> > @* * @ref{Modifier-Keys}
> > @* * @ref{Key-Mnemonics}

But I have noticed that the output is as follows even though @ref
is not supposed to generate the "see" string when loading the info
file.

> > * see Modifier-Keys
> > * see Key-Mnemonics

Have read tne Emacs Documentation and found Info-hide-note-references.

It did not make any difference what value I used (t, nil, other).  One
either gets "see" or "*note".

However for @ref one should not get anything precceding the reference name.

bug#44043: Info Files Showing "see" or "*note" when using @ref in source

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

It may be necessary to report this to bug-texinfo.
However, I don't know how much people are maintaining Texinfo now.
Would you like to help do that?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#44043: Info Files Showing "see" or "*note" when using @ref in source

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sat, 17 Oct 2020 00:19:21 -0400
> Cc: 44043@debbugs.gnu.org
> 
> It may be necessary to report this to bug-texinfo.

No, this is an Emacs feature, implemented in info.el.

bug#44043: Info Files Showing "see" or "*note" when using @ref in source

[Eli Zaretskii]

> Date: Fri, 16 Oct 2020 23:02:02 +0200
> Sensitivity: Normal
> 
> I have the following references using @ref to Node Names
> 
> > > @* * @ref{Modifier-Keys}
> > > @* * @ref{Key-Mnemonics}
> 
> But I have noticed that the output is as follows even though @ref
> is not supposed to generate the "see" string when loading the info
> file.
> 
> > > * see Modifier-Keys
> > > * see Key-Mnemonics
> 
> Have read tne Emacs Documentation and found Info-hide-note-references.
> 
> It did not make any difference what value I used (t, nil, other).  One
> either gets "see" or "*note".
> 
> However for @ref one should not get anything precceding the reference name.

I cannot reproduce the problem: setting Info-hide-note-references to
the value 'hide removes the "*note" part and doesn't replace it with
"see".

Did you try the value 'hide?

bug#44043: Info Files Showing "see" or "*note" when using @ref in source

[Christopher Dimech]

The Emacs Manual does not mention hide so did not try it.  Now
that I have, the problem is resolved.  The Emacs Manual needs
to be updated as the option is not described. It only describes
"t" and "nil". Here are the sections concerned:

1.5 Invisible text in Emacs Info
1.7 Following Cross-References
2.6 Emacs Info-mode Variables

Using M-x describe-variable <Ret> Info-hide-note-references,
although if would help with an improved documentation.  I can
send an update to the documentation myself as I am currently
doing some documentation work in ELisp myself, and can have
a look at the manual.

Regards
Christopher


---------------------
Christopher Dimech


> Sent: Saturday, October 17, 2020 at 9:26 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: 44043@debbugs.gnu.org
> Subject: Re: bug#44043: Info Files Showing "see" or "*note" when using @ref in source
>
> > Date: Fri, 16 Oct 2020 23:02:02 +0200
> > Sensitivity: Normal
> >
> > I have the following references using @ref to Node Names
> >
> > > > @* * @ref{Modifier-Keys}
> > > > @* * @ref{Key-Mnemonics}
> >
> > But I have noticed that the output is as follows even though @ref
> > is not supposed to generate the "see" string when loading the info
> > file.
> >
> > > > * see Modifier-Keys
> > > > * see Key-Mnemonics
> >
> > Have read tne Emacs Documentation and found Info-hide-note-references.
> >
> > It did not make any difference what value I used (t, nil, other).  One
> > either gets "see" or "*note".
> >
> > However for @ref one should not get anything precceding the reference name.
>
> I cannot reproduce the problem: setting Info-hide-note-references to
> the value 'hide removes the "*note" part and doesn't replace it with
> "see".
>
> Did you try the value 'hide?
>

bug#44043: Info Files Showing "see" or "*note" when using @ref in source

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Cc: 44043@debbugs.gnu.org
> Date: Sat, 17 Oct 2020 12:47:17 +0200
> 
> The Emacs Manual does not mention hide so did not try it.  Now
> that I have, the problem is resolved.  The Emacs Manual needs
> to be updated as the option is not described. It only describes
> "t" and "nil". Here are the sections concerned:
> 
> 1.5 Invisible text in Emacs Info
> 1.7 Following Cross-References
> 2.6 Emacs Info-mode Variables

You mean, the Info mode manual, not the Emacs manual.

I fixed the last one of these 3 sections, as only it includes the full
description of the variable, and the other two only discuss limited
effects of the variable.

> Using M-x describe-variable <Ret> Info-hide-note-references,
> although if would help with an improved documentation.

Indeed, the doc string of a variable is the recommended place to look
first for the details of the variable.  The manual could provide some
background and more elaborate info, but it could also completely
ignore the variable (we don't document every variable and every
function in our manuals).

With that, I'm closing this bug report.  Thanks.

bug#44043: Info Files Showing "see" or "*note" when using @ref in source

[Christopher Dimech]

Yes, in the manual it can ignore the variable and not document every single
thing, but when a defaulted variable changes the output of what is expected
from the official texinfo behaviour, some documentation is required, as it
was.  Simply involved a little update, and a bit more clarity in description.

Regards
Christopher


---------------------
Christopher Dimech
Administrator - Naiad Informatics - GNU Project (Geocomputation)
- Geophysical Simulation
- Geological Subsurface Mapping
- Disaster Preparedness and Mitigation
- Natural Resource Exploration and Production
- Free Software Advocacy


> Sent: Saturday, October 17, 2020 at 1:48 PM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: 44043-done@debbugs.gnu.org
> Subject: Re: bug#44043: Info Files Showing "see" or "*note" when using @ref in source
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Cc: 44043@debbugs.gnu.org
> > Date: Sat, 17 Oct 2020 12:47:17 +0200
> >
> > The Emacs Manual does not mention hide so did not try it.  Now
> > that I have, the problem is resolved.  The Emacs Manual needs
> > to be updated as the option is not described. It only describes
> > "t" and "nil". Here are the sections concerned:
> >
> > 1.5 Invisible text in Emacs Info
> > 1.7 Following Cross-References
> > 2.6 Emacs Info-mode Variables
>
> You mean, the Info mode manual, not the Emacs manual.
>
> I fixed the last one of these 3 sections, as only it includes the full
> description of the variable, and the other two only discuss limited
> effects of the variable.
>
> > Using M-x describe-variable <Ret> Info-hide-note-references,
> > although if would help with an improved documentation.
>
> Indeed, the doc string of a variable is the recommended place to look
> first for the details of the variable.  The manual could provide some
> background and more elaborate info, but it could also completely
> ignore the variable (we don't document every variable and every
> function in our manuals).
>
> With that, I'm closing this bug report.  Thanks.
>

bug#44043: Info Files Showing "see" or "*note" when using @ref in source

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Cc: 44043-done@debbugs.gnu.org
> Date: Sat, 17 Oct 2020 14:40:11 +0200
> 
> Yes, in the manual it can ignore the variable and not document every single
> thing, but when a defaulted variable changes the output of what is expected
> from the official texinfo behaviour, some documentation is required, as it
> was.  Simply involved a little update, and a bit more clarity in description.

I did clarify the manual.