bug#13524: Improving user experience for non-recursive builds

[Peter Rosin]

On 2013-02-04 12:23, Stefano Lattarini wrote:
> On 02/04/2013 12:10 AM, Peter Rosin wrote:
>> On 2013-02-03 21:42, Stefano Lattarini wrote:
>>> I've pushed the promised patches to the rewindable branch
>>> 'experimental/preproc' (based off of maint).  I'll also soon
>>> send them to the list to simplify review (I will drop the
>>> bug tracker from CC:, to avoid cluttering up the report).
>>>
>>> As usual, reviews are welcome.
>>
>> I like the end result of this series, I especially like that I don't have
>> to type &{this}& anymore. But I have some doubts whether the longish
>> way to get there is really all that interesting?
>>
> No, not really; the different approaches and names we tried can just be
> reported in the commit message, rather than littering up the Git history.
> 
> So I'll squash all the patches, excluding only the second one, which I
> still wish to keep separate.

Good.

>> [SNIP]  rest of rationle
> 
>> Another thing is that your new NEWS item is a bit awkward, and its
>> single sentence is simply too long and winding IMHO. The * heading
>> also needs an update.
>>
>> From your 5/6:
>>
>> * Current directory in makefile fragments:
>>
> Oops, I had indeed forgotten to update this!
> 
>>   - The special Automake-time substitutions '{RELDIR}' and '{CANON_RELDIR}'
>>     (and their abbreviated versions, '{D}' and '{C}' respectively) can now
>>     be used in an included Makefile fragment to indicate respectively the
>>     relative directory of that fragment and its canonicalized version,
>>     relative to the including Makefile:
>>
>> My suggestion:
>>
>> * Relative directory in Makefile fragments:
>>
>>   - The special Automake-time substitutions '{RELDIR}' and '{CANON_RELDIR}'
>>     (and their abbreviated versions, '{D}' and '{C}' respectively) can now
>>     be used in an included Makefile fragment.  They are substituted with
>>     the relative directory of the included fragment, or its canonicalized
>>     version, compared to the top level including Makefile:
>>
> Yes, better.  But I find the following even better (marginally):
> 
>     The special Automake-time substitutions '{RELDIR}' and '{CANON_RELDIR}'
>     (and their abbreviated versions, '{D}' and '{C}' respectively) can now
>     be used in an included Makefile fragment.  They are substituted,
>     respectively, with the relative directory of the included fragment and
>     its canonicalized version, compared to the top level including Makefile:
> 
> OK?

I still like my version better, I think that the slight ambiguity you aim
to kill with the extra "respectively" is not going to fool anyone, and I
find that the twist it adds just makes it harder to read the dang thing.
But I'm not a native speaker, so what do I know?

New (and final, from me) attempt:

* Relative directory in Makefile fragments:

  - The special Automake-time substitutions '{RELDIR}' and '{CANON_RELDIR}'
    (and their abbreviated versions, '{D}' and '{C}' respectively) can now
    be used in an included Makefile fragment.  The former is substituted
    with the relative directory of the included fragment (compared to the
    top level including Makefile), and the latter with the canonicalized
    version of the same relative directory:

Cheers,
Peter