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

[Jeff King <peff@peff.net>]

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

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