Re: @pxref documentation

[Karl Berry]

Hi Stepan,

    Perhaps the texinfo manual shouldn't be so strict that @pxref cannot be
    used in sentences?  

Since Alper put in the add_xref_punctuation function for 4.7, I believe
that's right.  These days, I believe it's no longer necessary for
@pxref{} to be followed by a ).  In particular, this is my understanding
of what makeinfo does now (test file below):

1) if it's a one-arg ref, the :: is enough for the Info readers to follow it.

2) if it's a multi-arg ref that is followed by . or , in the input,
   that following punct will again allow the Info readers to follow it.

3) if it's a multi-arg ref that is not followed by . or , in the input
   (including a ) following), then makeinfo inserts a . in the Info
   output, so the readers can follow it.  This rule is why you shouldn't
   just write
     ... @pxref{foo, bar} for info.
   There will be an ugly period in the middle of the sentence:
     ... *note bar: foo. for info.
   (The TeX output will also be wrong.)

BTW, it is definitely preferable to put following punctuation in the
document if it is grammatically needed there.  makeinfo only inserts the
. in Info output.  So something like
   blah blah, @pxref{foo}.
Needs the end-of-sentence period, otherwise the HTML, ..., and TeX,
output will lack it.  makeinfo is smart enough not to insert a period
if one is already there (rule 2).

    take some of the places pointed out by
            grep -E '(^|see )@ref' automake.texi
    and use @pxref there, too.

Yes, I agree; using @pxref at the end of a sentence works better than
"see @ref".  (I agree with Eli that the principal reason @ref exists is
if you want something other than "[sS]ee".)  Feel free to propose a
patch to Alexandre :).

Meanwhile, I'll see about updating the pxref node in the manual, which
still says it must be used inside parens, unless there's some reaction
to the contrary.

Thanks,
karl


\input texinfo
@setfilename refpunct.info

@paragraphindent none

@node Top
@top Ref Punct Test

xref1 @xref{Top} space in sentence.

ref1 @ref{Top} space in address@hidden
ref1 @ref{Top}, comma in address@hidden
ref1 @ref{Top}; semicolon in sentence.

pxref1 (@pxref{Top}) normal in address@hidden
pxref1 (@pxref{Top},) comma in address@hidden
pxref1 (@pxref{Top};) semicolon in address@hidden
pxref1 @pxref{Top} space in sentence.

ref2 @ref{Top,ref-space} in address@hidden
ref2 @ref{Top,ref-comma}, in address@hidden
ref2 @ref{Top,ref-semicolon}; in sentence.

pxref2 (@pxref{Top,pxref-normal}) in address@hidden
pxref2 (@pxref{Top,pxref-comma},) in address@hidden
pxref2 (@pxref{Top,pxref-semicolon};) in address@hidden
pxref2 @pxref{Top,pxref-space} in sentence.

@bye