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

[Eric Abrahamsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> 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}".

Yeesh, I had no idea all this happened (nor did I know about
Info-hide-note-references), I was indeed just going by the display.
Sorry if I've come across as obtuse, here.

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

Okay, those final changes are in, and I'm pushing to master this before
I mess anything else up.

Thanks for your help,
Eric