Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 20, 2024, 22:57 UTC
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.

Show 9 quoted lines

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

Show 5 quoted lines

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

Show 5 quoted lines

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

Show 6 quoted lines

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

Show 6 quoted lines

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