emacs-26 07ea5ef99a: Fix reference style in org.texi

emacs-26 07ea5ef99a: Fix reference style in org.texi

[Kyle Meyer]

> * doc/misc/org.texi (A Texinfo example): Fix reference style.
[...]
> -Here is a more detailed example Org file.  @xref{GNU Sample
> +Here is a more detailed example Org file.  See @ref{GNU Sample
>  Texts,,,texinfo,GNU Texinfo Manual} for an equivalent example using Texinfo
>  code.

I'm reviewing this commit for backport to the Org repo, and I don't
understand what it's fixing.  Both variants seem to produce the
equivalent output.  Could you please explain to me what the difference
is?

Thanks.

-- 
Kyle

Re: emacs-26 07ea5ef99a: Fix reference style in org.texi

[martin rudalics]

 > I'm reviewing this commit for backport to the Org repo, and I don't
 > understand what it's fixing.  Both variants seem to produce the
 > equivalent output.  Could you please explain to me what the difference
 > is?

The output _should_ be equivalent.  But section 8.4.1 of the texinfo
manual says here:

      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.

And your version got me the following warning (with makeinfo 4.13):

   GEN      ../../../doc/misc/../../info/org.info
../../../doc/misc/org.texi:14038: warning: `.' or `,' must follow @xref, not `f'.

Maybe this has been changed for current versions of texinfo but 4.13 is
still permitted to build Emacs (at least on slower systems).  My commit
message should have explained that but I initially wanted to mark it as
marginal so I did not bother.

Apologies for any inconvenience, martin

Re: emacs-26 07ea5ef99a: Fix reference style in org.texi

[Kyle Meyer]

martin rudalics <rudalics@gmx.at> writes:
> The output _should_ be equivalent.  But section 8.4.1 of the texinfo
> manual says here:
>
>       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.
>
> And your version got me the following warning (with makeinfo 4.13):
>
>    GEN      ../../../doc/misc/../../info/org.info
> ../../../doc/misc/org.texi:14038: warning: `.' or `,' must follow @xref, not `f'.

I see.  Thanks.

> Maybe this has been changed for current versions of texinfo but 4.13 is
> still permitted to build Emacs (at least on slower systems).

Perhaps.  I couldn't find the above note in 6.4's manual and don't see a
warning when generating the info file.

> Apologies for any inconvenience, martin

No inconvenience at all.  Thanks for the explanation.

-- 
Kyle

Re: emacs-26 07ea5ef99a: Fix reference style in org.texi

[Eli Zaretskii]

> Date: Mon, 02 Oct 2017 08:46:19 +0200
> From: martin rudalics <rudalics@gmx.at>
> Cc: emacs-devel@gnu.org
> 
> section 8.4.1 of the texinfo manual says here:
> 
>       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.

That's true, but the same is true about @ref.

>    GEN      ../../../doc/misc/../../info/org.info
> ../../../doc/misc/org.texi:14038: warning: `.' or `,' must follow @xref, not `f'.
> 
> Maybe this has been changed for current versions of texinfo

Yes, latest versions are more lenient in this regard.

Re: emacs-26 07ea5ef99a: Fix reference style in org.texi

[martin rudalics]

 >>        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.
 >
 > That's true, but the same is true about @ref.

While my manual says that

      As a general rule, you should write a period or comma immediately
    after an `@ref' command with two or more arguments.

      If there is no such following punctuation, `makeinfo' will generate a
    (grammatically incorrect) period in the Info output; otherwise, the
    cross-reference would fail completely, due to the current syntax of
    Info format.

so it apparently is less rigid in this case, my texinfo does not insert
a period in the output here.

martin

Re: emacs-26 07ea5ef99a: Fix reference style in org.texi

[Eli Zaretskii]

> Date: Tue, 03 Oct 2017 11:14:58 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: kyle@kyleam.com, emacs-devel@gnu.org
> 
> While my manual says that
> 
>       As a general rule, you should write a period or comma immediately
>     after an `@ref' command with two or more arguments.
> 
>       If there is no such following punctuation, `makeinfo' will generate a
>     (grammatically incorrect) period in the Info output; otherwise, the
>     cross-reference would fail completely, due to the current syntax of
>     Info format.
> 
> so it apparently is less rigid in this case, my texinfo does not insert
> a period in the output here.

For some reason, I don't see the above as "less rigid".

Re: emacs-26 07ea5ef99a: Fix reference style in org.texi

[martin rudalics]

 > For some reason, I don't see the above as "less rigid".

I think "you should write" is less rigid than "*must* follow" but your
knowledge of English is probably better than mine.

martin