On 16 September 2011 22:36, Eric Blake <ebl...@redhat.com> wrote:
> On 09/16/2011 03:30 PM, Eric Blake wrote:
>>
>> On 09/16/2011 03:28 PM, Reuben Thomas wrote:
>>>
>>> On 16 September 2011 22:27, Eric Blake<ebl...@redhat.com> wrote:
>>>>
>>>> I'd keep this as:
>>>>
>>>> @item
>>>> Use @code{AC_DEFINE} but have @command{configure} compute the literal
>>>> value of @code{datadir} and others.
>>>>
>>>> This solution does not conform to the GNU Coding Standards.
>>>>
>>>> that is, just remove the mention of the obsolete archive macro.
>>>
>>> Why document a solution that is non-GCS compliant when there are
>>> GCS-compliant solutions?
>>
>> For teaching purposes. Look at the context - this is part of a larger
>> list of @items, each giving pros and cons about potential solutions,
>> before settling on WHY we picked the last bullet as our preferred
>> solution.
>
> But to be honest, we could reorder that list a bit: float the @item on
> AC_DEFIN to the front of the list, since it's the worst solution, split the
> @item about compile-time substitutions into two (one using -D, and one using
> a dedicated header), all before settling on the last @item of computing
> runtime relativity to $prefix.
I agree with most of this, but:
1. Drop the AC_DEFINE item, as it's a dead end (and, being non-GCS,
unusable) not a logical refinement of a developing technique (I do
agree that gradually building up complex techniques, with motivation
and explanation, is a good feature of GNU manuals).
2. The paragraph before the list makes it sound like a list of
alternatives, not the development of a solution ("There
are several means to achieve a similar goal"). This needs fixing.
3. The last bullet point doesn't really belong in the list, since it's
not really a solution (or at best, it's a solution left as an exercise
to the reader). I suggest breaking it out into a final paragraph.
4. The remaining bullet points need then to be rewritten to show why
each successive refiinement is needed.
5. Actually, the current second bullet point is a special case
solution. (It says it is suitable "when compiling a program".)
--
http://rrt.sc3d.org
