From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 20 Feb 2024 22:57:12 GMT
Subject: Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax
Message-ID: <xmqqsf1mlp6f.fsf@gitster.g>
In-Reply-To: <17b0284c379e62a756e1bba008f4671f6afc0ad9.1708468374.git.gitgitgadget@gmail.com>

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

>  [verse]
> -'git rev-parse' [<options>] <args>...
> +'git rev-parse' [<options>] <arg>...

Good.  The "or more" is signalled by the ellipsis, not "args" being
plural.

> ---short[=length]::
> +--short[=<length>]::
>  	Same as `--verify` but shortens the object name to a unique
>  	prefix with at least `length` characters. The minimum length

This same comment applies throughout this patch, but in other places
when we use <placeholder> in the option argument description, don't
we use the same <placeholder> in text as well?  I am wondering if
the `length` (typeset in fixed-width) should become <length>.  What
do other recent[*] documentation pages commonly do?

	Side note: I say "recent" because rev-parse doc is one of
	the oldest ones that did not get typesetting attention they
	deserve, compared to more recent ones that got nitpicked
	while they were written and updated.

> ---branches[=pattern]::
> ---tags[=pattern]::
> ---remotes[=pattern]::
> +--branches[=<pattern>]::
> +--tags[=<pattern>]::
> +--remotes[=<pattern>]::
>  	Show all branches, tags, or remote-tracking branches,
>  	respectively (i.e., refs found in `refs/heads`,
>  	`refs/tags`, or `refs/remotes`, respectively).

Ditto.  We see `pattern` that may want to become <pattern> in the
description (after the post context of this hunk).

> ---glob=pattern::
> +--glob=<pattern>::
>  	Show all refs matching the shell glob pattern `pattern`. If
>  	the pattern does not start with `refs/`, this is automatically
>  	prepended.  If the pattern does not contain a globbing

Ditto.

> ---exclude-hidden=[fetch|receive|uploadpack]::
> +--exclude-hidden=(fetch|receive|uploadpack)::
>  	Do not include refs that would be hidden by `git-fetch`,
>  	`git-receive-pack` or `git-upload-pack` by consulting the appropriate
>  	`fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`

Good.

> ---since=datestring::
> ---after=datestring::
> +--since=<datestring>::
> +--after=<datestring>::
>  	Parse the date string, and output the corresponding
>  	--max-age= parameter for 'git rev-list'.

Good, modulo possibly "date string" -> "<datestring>".

> ---until=datestring::
> ---before=datestring::
> +--until=<datestring>::
> +--before=<datestring>::
>  	Parse the date string, and output the corresponding
>  	--min-age= parameter for 'git rev-list'.

Ditto.

> -<args>...::
> +<arg>...::
>  	Flags and parameters to be parsed.

Good.