Re: What is normal these days (display.texi)?

[Eli Zaretskii]

> Date: Sat, 8 Jul 2006 13:10:41 +0000 (UTC)
> From: "Robert J. Chassell" <address@hidden>
> Cc: 
> 
>     >     ! precisely at the right margin, not at a word boundary.
>     >     ! @xref{Filling}, @ref{Longlines,, Long Lines Mode, emacs,
>     >     ! The GNU Emacs Manual}.
>     >
>     > That doesn't seem like proper Texinfo usage; is it?
> 
>     What's wrong with it?
> 
> @ref is for the end of a sentence.

No, it isn't.  It's for _any_ kind of situation where the leading
`see' in the printed manual might be inappropriate.  It's true that
such situations frequently happen at the end of a sentence, but saying
that @ref is _only_ for the end of a sentence (and that there should
be a mandatory `see' before it) is limiting its use for no good
reason.

> The documentation says:
> 
>     (texinfo)ref
> 
>     address@hidden' is nearly the same as address@hidden' except that it does 
> not
>     generate a `See' in the printed output, just the reference itself.
>     This makes it useful as the last part of a sentence.

This text was somewhat misleading.  That's why I suggested (and I
think Karl accepted) to change it as follows:

    Sometimes, `See' or `see' before a reference is not what you want,
    because there's some other similar word that fits the text better.
    That's when you need @code{@@ref}.  @code{@@ref} is nearly the same as
    @code{@@xref} except that it does not generate a `See' in the printed
    output, just the reference itself.  It also produces a lower-case
    @samp{*note} instead of @samp{*Note}.  These two features make
    @code{@@ref} useful as the last part of a sentence or in the middle of
    a sentence, if you want to replace `see' with something else, or
    remove it altogether.

Note that the rest of the section already refrains from another
misleading recommendation--to add a `see' before each @ref:

    In general, it is best to use @code{@@ref} only when you need some
    word other than ``see'' to precede the reference.  When ``see'' (or
    ``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable.