autoconf-patches
[Top][All Lists]
Advanced

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

Re: more documentation proofreading


From: Steven G. Johnson
Subject: Re: more documentation proofreading
Date: Tue, 10 Apr 2001 11:01:26 -0400 (EDT)

On 10 Apr 2001, Akim Demaille wrote:
> |  You are now able to understand one of the constructs of Autoconf that
> | -has continuously been misunderstood...  The rule of thumb is that
> | +has been continually misunderstood...  The rule of thumb is that
> 
> What is the difference between the two?  Continuously is mathematical?
> Or continuously is `spatial' and continually related to time?

"Continuously" means at *all* times, "always," with no breaks; think of a
continuous function.  "Continually" means more like "repeatedly," "over
and over again;" it implies a discrete sequence of events.

> | address@hidden b10;}.  There was a idiom developed in the Autoconf world to
> | address@hidden b10;}.  (There was a idiom common in Autoconf's past to
> 
> s/a idiom/an idiom/ I guess.

Right, I didn't see that.  I'll prepare a patch.

> | address@hidden (not to be confounded with the quote characters).  You may
> | +as @ovar{arg} (not to be confused with the quote characters).  You may
> 
> What is the difference?
> 
>   confound
>        2: mistake one thing for another; "you are confusing me with
>           the other candidate"; "I mistook her for the secretary"
>           [syn: {mistake}, {confuse}]

The usage is not incorrect, as you point out.  (In fact, "confuse" has its
roots as the passive participle of "confound.")  I changed it because, for
me, I feel that "confound" has stronger and more negative connotations,
because it can also mean "defeat" or "overthrow."  It seemed to give too
heavy an emphasis to a parenthetical remark to clarify a point for the
reader.

> | @@ -800,6 +802,8 @@
> |  # Process this file with autoconf to produce a configure script.
> |  @end example
> |  
> | +Such comments will be included in the generated @file{configure} script.
> | +
> 
> I would not include this.  For instance, it does not apply to any
> comment before AC_INIT, which is precisely what the example above is
> about.  Rule for # comments are not straight to describe.

Ah, okay.  I wanted to say something because I thought the text implied
that the "#" comments were an m4 feature.

Isn't the fact that any lines before AC_INIT are ignored, whether they
begin with # or not?  So that's not a rule about # comments per se. 

How about:

Such comments will be included in the generated @file{configure} script,
and the @samp{#} is for the benefit of @code{sh}.  (The exception is
that lines before AC_INIT, such as the one above, are stripped from the
output.)

Or would you prefer removing the remark entirely?

> | -If you want to disable @command{autoconf}'s defaults and @code{WARNING}
> | +If you want to disable @command{autoconf}'s defaults and @code{WARNING},
> 
> s/WARNING/&S/

Right.

> |  @noindent
> | -The long @var{separator}s can be used to ease parsing of complex
> | +A long @var{separator} can be used to improve the readability of complex
> 
> Here I was really referring to mechanical reading, so I don't know if
> `readability' really applies.

Oh, I misunderstood you.  Using a separator like "|:::::|" didn't make
sense to me as a way to improve mechanical parsing, when a single
character ":" is usually enough for that purpose.  I guess you were
worried about cases where the individual items might contain a ":"? But
this is confusing, because the following example didn't illustrate such a
case.

(My inclination was actually to delete that entire paragraph and the
following example.  I think the usage of the custom separator string is
pretty clear to anyone who would need such a thing, and the point of the
example could be confusing to someone else.)

> | @@ -2052,6 +2057,9 @@
> |  @end group
> |  @end example
> |  
> | +(Be careful if you copy these lines directly into your Makefile, as you
> | +will need to convert the indented lines to start with the tab character.)
> | +
> 
> There should be a @noindent right before this paragraph.

Okay.

> | -For instance:
> | +For example:
> 
> What is the difference?

Not much difference, it was mostly blind instinct that made me want to
change words in this case.  In retrospect, partially I was tired of "for
instance" all over the place =), but partially it is because they have a
slight difference in connotation.  "For example" to me sounds more active
and important than "for instance;" the latter leans more towards an
aside.

> 
> | +One can then run:
> |  @example
> |  ./config.status host.h object.h
> |  @end example
> | -to establish the links.
> | +to create the links.
> |  @end defmac
> 
> A @noindent is missing after @end example.

Okay.

> | @@ -8025,10 +8036,10 @@
> |  beginning of a line, followed by a comment that repeats the name of the
> |  macro being defined.  If you want to avoid the new-line which is then
> |  introduced, use @code{dnl}.  Better yet, use @samp{[]dnl} @emph{even}
> | -behind of parenthesis, since because of the M4 evaluation rule the
> | +inside of parentheses: because of the M4 evaluation rules, the
> 
> Hm, actually I meant `after the closing paren', not inside.

Ah.  The remark is confusing to me, because it wasn't clear to me that you
were referring to the parentheses after a macro call--the phrasing seemed
to apply it to the preceding remark about the closing "[)". Moreover, the
subsequent example uses ...CPP()dnl and not ...CPP()[]dnl! If you want to
keep it, I'll rephrase it a bit and modify the example to use []dnl after
the parentheses.

Honestly, my inclination would be to not worry about extra newlines
introduced in the configure script, and to recommend that the user not
bother with dnl.  The price you pay in readability of the autoconf macro
is not worth the slight increase in readability of the configure script
(which is rarely looked at anyway).

I'll submit a patch for all of the above stuff once everything is clear.

Steven




reply via email to

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