Re: more documentation proofreading

[Akim Demaille]

>>>>> "Steven" == Steven G Johnson <address@hidden> writes:

First of all, thanks a lot for all your information on English!


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

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

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

No, they are not ignored: they are *executed*, but (unless you play
with divert), nothing is output.  For instance, you may `define' etc.
You can AC_CONFIG_HEADERS if you wish, it will be honored, as it
doesn't produce any real code, just stores data handled by AC_OUTPUT
later.

Steven> How about:

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

Steven> Or would you prefer removing the remark entirely?

This is a good approximation, but it leaves the most important thing
aside: comments *inside* macro definition will of course be output,
but not comments outside (i.e., typically comments in aclocal.m4 which
are not in a macro body).

But I don't recall whether this section is about configure.in and only
it, or it includes writing library m4 files.


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

Correct.

Steven> But this is confusing, because the following example didn't
Steven> illustrate such a case.

You are right!  Feel free to improve it.

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

Well, in this case, please leave at least enough indication so that
people know they can use separator which are totally unlikely to
appear in genuine macro args.


>> Hm, actually I meant `after the closing paren', not inside.

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

I don't have the text handy, but I trust your judgment.

Steven> Honestly, my inclination would be to not worry about extra
Steven> newlines introduced in the configure script, and to recommend
Steven> that the user not bother with dnl.

It depends upon the section.  If the section is about writing macros
(not using them), then we should keep it.  Don't forget newlines are
not meaningless in sh, and there are cases where you do not want to
issue one.