Re: documentation punctuation fixes

[Steven G. Johnson]

On 17 Apr 2001, Akim Demaille wrote:
> > 2001-04-13  Steven G. Johnson  <address@hidden>
> >         * doc/autoconf.texi: Fixes for punctuation and grammar..  Replace
> >         "..." with "@dots{}" except when "..." is in literal code.
> >  @example
> > -... && my_foos="$my_foos fooo"
> > -... && my_foos="$my_foos foooo"
> > address@hidden && my_foos="$my_foos fooo"
> > address@hidden && my_foos="$my_foos foooo"
> 
> Does it come out properly?

Yes.  (There seems to be no problem with @dots inside @example, if that's
what you're worried about.)

> >  But when things go wrong, you'll thank the Autoconf team for
> > address@hidden
> > address@hidden@dots{}
> 
> Please, change this into ``you'll be happy that autoheader exists'' or
> something like that.  I was a bit too angry when I wrote that.

Okay, although it didn't sound bad to me.  It now reads:

        address@hidden directly is all that is needed.  When things go
        wrong, however, you'll be thankful for the existence of
        @command{autoheader}

> > +since not all shells properly understand @samp{"address@hidden"foo"@dots{} 
> > `"}.
> > +Worse yet, not all shells understand @samp{"address@hidden"foo\"@dots{} 
> > `"} the same
> 
> Why are the quotes escaped?

The quotes are escaped because they are inside other quotes in a shell
string: "...\"foo\"..."

> Do you really mean to move to @dots?  I'm not sure what you mean by
> `except when "..." is in literal code'.

I mean, I switched from "..." to "@dots{}" unless the "..." are meant as a
literal string that is really in the code.  Here, the ellipses aren't so
much a literal string as a representation for an arbitrary string of some
sort.  Actually, they should probably be used instead of "foo", too, and
@samp{} switched to @code{} because the former adds yet another pair of
quotes even in ps/html, which is confusing. i.e.

        ...since not all shells properly understand
        @code{"address@hidden"@dots{}"@dots{}`"}. Worse yet, not all shells
        understand @code{"address@hidden"@dots{}\"@dots{}`"} the same way.

which comes out:

        since not all shells properly understand `"`..."..."...`"'.  
        Worse yet, not all shells understand `"`...\"...\"...`"' the same
        way.

in autoconf.info.  (Is there any way to remove the `...' from @code{} even
in info mode?  Like I said, this example is already confusing enough
without the extra pair of quotes.)

Another problem: in postscript output, even in the code font used for
@code{}, @example, and so on, the ' and ` characters are being rendered
with the wrong glyphs.  They are using the "curly" single-quote glyphs,
rather than the straight foot and backtick glyphs. (The " character is
correctly rendered with the inch glyph.)  I guess this is a bug in
texinfo...

> > -...but beware of the @address@hidden bug from Solaris (see above).  For 
> > safety,
> > address@hidden beware of the @address@hidden bug from Solaris (see above).  
> > For safety,
> 
> Do we need to keep this {}?  Can we write address@hidden but'?  This is really
> ugly :(

The {} is necessary; there should be no space after an ellipsis, unless it
comes at the end of a sentence.

> > address@hidden@dots{}]} (Solaris, Digital Unix, etc.).
> 
> Likewise.

Again, @dots{} comes out fine here, and I prefered it over "..." because
it represents an arbitrary command, not the literal "..." string.

> > -if ...; then
> > if @dots{}; then
> 
> ?

Same reasoning...the "..." is not a literal string here.

> > -./config.status @var{option}... address@hidden@dots{}]
> > +./config.status @address@hidden address@hidden@dots{}]
> >  @end example
> 
> ?

Same again.  (Note that @dots{} were already being used after @var{file},
but not after @var{option}!)

> > -Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}...]}.
> > +Same as @samp{AC_MSG_NOTICE([checking @address@hidden
> 
> ?

Same reasoning again.

Steven