bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual

[Eli Zaretskii]

> From: Eric Abrahamsen <eric@ericabrahamsen.net>
> Cc: larsi@gnus.org,  37078@debbugs.gnu.org
> Date: Fri, 24 Jul 2020 14:08:20 -0700
> 
> > "See @pxref" again.
> >
> >> +per-group (see @pxref{Mail Sources} for more information).
> >
> > Same here.
> 
> Okay there's something funny going on here. When I run "make" with this
> exact diff, the output looks exactly right: "See _Finding the News_ for
> details." Same with your other, later notes. If I "C-x C-f" from the
> info manual (now I'm in "<emacsbuilddir>/info/") and open gnus.info, I
> see there is no "See" in the text, just "*note Finding the News:: for
> details."
> 
> Playing with this further, the info display seems to be inserting a
> "see" if there isn't one, and not if there is.

That's right, you need to look at the file itself, or reset
Info-hide-note-references to nil inside Info.

> In the info manual for the texinfo package on my system, it says all
> three reference commands (@xref, @ref, and @pxref) will insert a see.

I think you are misinterpreting the Texinfo manual, or maybe judging
by the Info mode display, not the real Info file.  In the Info format,
the cross-reference marker is "*note ", not "See".  The latter appears
in the printed manual.  And @ref doesn't generate "see" in the printed
manual, it leaves that to you, so that you could, for example, say
something like "this-and-that, as described in @ref{foo}".

> I'm not seeing any doubled "see"s in the output, though.

You should see "see *note " in the output, which is already a sign of
trouble.  And in printed output, you will see a duplicate "see".

> The texinfo package version on Arch linux is 6.7-3. Could behavior be
> different between versions?

Not this one, no.

> Anyway, I've edited my diff according to your notes, please take a look.

Mostly okay, see below.

> +using interactive commands in the Server buffer.  @ref{Finding
> +the News} for details.                            ^^^^

You want @xref here, and please remember the comma after the closing
brace.

> +messages, see @ref{Summary Mail Commands} for details.
                                            ^
A comma there is missing.