Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs

From: Jeff King <peff@peff.net>
Date: May 12, 2010, 11:23 UTC
Message-ID: <20100512112342.GA23847@coredump.intra.peff.net>
In-Reply-To: <20100512105002.GB17740@progeny.tock>

On Wed, May 12, 2010 at 05:50:02AM -0500, Jonathan Nieder wrote:

Show 21 quoted lines

> > Searching
> > for "conflict" even in just a list of options should come up with
> > "merge.conflictstyle", and I had always intended for such a gitconfig.5
> > to have a full list.
> 
> Makes sense.  So the breakdown of that page might be
> 
>   Synopsis
>   Description
>     Syntax
>   Configuration items
>     Sections
>     Index
>   Core configuration
>   Identity
>   Suppressing advice
>   Command aliases
>   Colored output
>   Paginated output
>   Examples
>   See also

Yes, I think that is sane. One other option would be to put a few things like "identity" into git(1) (where it would presumably be part of an overall identity section covering the concepts, config options, and environment variables).

> To keep this maintainable, I would like to have a single source file
> with a short and long description for each configuration item.  Then
> a script would process it into an index and snippets for the relevant
> command pages.

My plan was to actually include the config's long description in the relevant manpage (so it will be close to point of use, and you can see the context while editing), and then pull the information out of each page for the index. Adding a short description would probably be simplest as a specially formatted comment. E.g., in git-add.txt:

   add.ignore-errors::
   // @CONFIG: ignore errors on 'git-add'
           Continue adding files when some files cannot be added due to
           indexing errors. Equivalent to using '--ignore-errors'.

and then process it with something like:

  perl -ne '
    m{^// @CONFIG: (.*)} && print "$last - $1\n"; $last = $_
  ' git-*.txt >config-index.txt

So it's sort of literate programming for documentation. :) The comment thing is obviously a hack, but it should work well in practice. You might be able to do some semantic markup with special attributes in asciidoc.

> I’m anxious to get started.  Thanks for the pointers.

I'm happy you're working on this. Thanks.

-Peff