[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Robert J. Chassell
Subject: Re: What is normal these days (display.texi)?
Date: Sat, 8 Jul 2006 13:10:41 +0000 (UTC)

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

    As far as I can see, it is following the specs to the letter, and
    it works.

No, it is not following the documentation.

    @xref{Filling, , ,emacs, The GNU Emacs Manual}, @ref{Longlines,,
    Long Lines Mode, emacs, The GNU Emacs Manual}.


    *Note Filling: (emacs)Filling, *Note Long Lines Mode:

in Info (and a fairly similar output for DVI).

You need an `and see' before the @ref, since it is without a capital
`S' and in the latter part of a sentence.

Plus, you need to complete the first part of the sentence.
For example:

    @xref{Filling, , ,emacs, The GNU Emacs Manual}, for more
    information; and also see @ref{Longlines,, Long Lines Mode, emacs,
    The GNU Emacs Manual}.

(without the indentation of this example)

The documentation says:


    address@hidden' is nearly the same as address@hidden' except that it does 
    generate a `See' in the printed output, just the reference itself.
    This makes it useful as the last part of a sentence.


(Please bear in mind that the documentation presumes a writer puts an
`and see' or whatever into a reference if needed; my belief is that
most documentation writers do not even notice that, since they learned
the need -- perhaps for a different spoken language -- so early in
their lives.)

    Robert J. Chassell                         
    address@hidden                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

reply via email to

[Prev in Thread] Current Thread [Next in Thread]