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

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

quoted

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