[PATCH 0/4] doc improvements for config includes

From: Jeff King <peff@peff.net>
Date: May 11, 2017, 09:09 UTC
Message-ID: <20170511090905.tvkb4bk2ddjzjip4@sigill.intra.peff.net>
In-Reply-To: <20170511075437.yjxs6oit7ibe7rkq@sigill.intra.peff.net>

On Thu, May 11, 2017 at 03:54:37AM -0400, Jeff King wrote:

Show 16 quoted lines

> On Thu, May 11, 2017 at 09:49:09AM +0200, Ævar Arnfjörð Bjarmason wrote:
> 
> > > I don't like this because it copies the rules for _one_ property to the
> > > conditional section. What happens when you're looking for some other
> > > property of include.path?
> > 
> > Yeah, as I said once I wrote it up I found it wasn't really any
> > better, but just wanted to send an explanation for why I didn't find
> > it while I remembered, as a sort of case study.
> > [...]
> > > I suspect that whole paragraph under Includes could be reworded to make
> > > it clear that anything it is saying applies equally to include.$key and
> > > includeIf.*.$key, and then that would future-proof us for other
> > > modifications.
> 
> What about this:

I think this is the right path, but I actually ended up with an introductory paragraph about the two sections. I hope it makes the same point but is a bit less clunky.

Here's a series that I think covers all the bits discussed here, and a few others.

  [1/4]: docs/config: clarify include/includeIf relationship
  [2/4]: docs/config: give a relative includeIf example
  [3/4]: docs/config: avoid the term "expand" for includes
  [4/4]: docs/config: consistify include.path examples

 Documentation/config.txt | 31 +++++++++++++++++++++----------
 1 file changed, 21 insertions(+), 10 deletions(-)

-Peff