Re: [PATCH v2 2/4] Documentation: list all type specifiers in config prose

[Jeff King <peff@peff.net>]

On Fri, Mar 23, 2018 at 08:55:54PM -0400, Taylor Blau wrote:

> The documentation for the `git-config(1)` builtin has not been recently
> updated to include new types, such as `--bool-or-int`, and
> `--expiry-date`. To ensure completeness when adding a new type
> specifier, let's update the existing documentation to include the new
> types.
> 
> Since this paragraph is growing in length, let's also convert this to a
> list so that it can be read with greater ease. We provide a minimal
> description of all valid type specifiers, and reference the <<OPTIONS>>
> section where each specifier is described in full detail.
> 
> This commit also prepares for the new type specifier `--color`, so that
> this section will not lag behind when yet more new specifiers are added.

Thanks for reformatting; the result is much easier to read. One nit:

> -The type specifier can be either `--int` or `--bool`, to make
> -'git config' ensure that the variable(s) are of the given type and
> -convert the value to the canonical form (simple decimal number for int,
> -a "true" or "false" string for bool), or `--path`, which does some
> -path expansion (see `--path` below).  If no type specifier is passed, no
> -checks or transformations are performed on the value.
> +A type specifier option can be used to force interpretation of values and
> +conversion to canonical form.  Currently supported type specifiers are:
> +
> +`bool`::
> +    The value is taken as a boolean.
> +
> +`int`::
> +    The value is taken as an integer.
> +
> +`bool-or-int`::
> +    The value is taken as a boolean or integer, as above.
> +
> +`path`::
> +    The value is taken as a filepath.
> +
> +`expiry-date`::
> +    The value is taken as a timestamp.
> +
> +For more information about the above type specifiers, see <<OPTIONS>> below.

The connection between "bool" here and "--bool" below isn't made
explicit. We probably should mention it.

Some of the details for the types are lost. E.g., what is a filepath?
The fact that we expand is not mentioned. I'm not sure how much that
matters, though. The full descriptions should be covered under "--path"
(and "--int", etc).

In fact, that kind of makes me wonder if this "type" list should not
exist at all. If we instead grouped the options and said "these are the
type options", then we'd only need one list.

I'm OK to punt on that for now, though, in the interest of not holding
up this patch series. I do think we should say something like:

  Each type can be specified with the matching command-line option
  (e.g., `--bool`, `--int`, etc); see <<OPTIONS>> below.

-Peff