Re: @pxref documentation

[Eli Zaretskii]

> Date: Tue, 21 Dec 2004 10:38:17 +0100
> From: Stepan Kasal <address@hidden>
> Cc: address@hidden
> 
> To be frank, @pxref indeed looks nicer here.  The info output looks like:
> 
>    (However the package's maintainers can tune the default, *note The
>    `AC_PROG_LIBTOOL' macro: (libtool)AC_PROG_LIBTOOL.)
> 
> while with ``see @ref{...}'' it would look like
> 
>    (However the package's maintainers can tune the default, see *Note The
>    `AC_PROG_LIBTOOL' macro: (libtool)AC_PROG_LIBTOOL.)
> 
> Please notice the ``note'' with a lowercase `n'.
> 
> Perhaps the texinfo manual shouldn't be so strict that @pxref cannot be
> used in sentences?  Do you want to you adjust the documentation?

I'm not Karl, but I don't see why the Texinfo documentation needs to
be adjusted: I don't think it forbids or otherwise advises against a
usage such as the one you cite above.  Can you quote the part of
texinfo.txi where you think the text tells you such a usage is not
recommended or not allowed?

The simple truth about @pxref is that it's supposed to be used
immediately before a closing parenthesis.  Whether there's something
else before the opening parenthesis and @pxref is not important at
all.  However, note that, since @pxref produces a period after the
cross-reference, a full sentence such as above looks awkward in
Texinfo, as it doesn't (and cannot) end with a period, which is a
disadvantage, albeit a minor one.

> But if we decide that these instances of @pxref are correct, I see no reason
> why we couldn't take some of the places pointed out by
> 
>       grep -E '(^|see )@ref' automake.texi

I think "see @ref..." should be avoided.  @ref is mainly for
situations where you want to say something other than "see" before the
cross-reference, so "see @ref" abuses it to some extent, IMHO.