From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 15 Jan 2025 23:46:54 GMT
Subject: Re: [PATCH v2 1/5] doc: apply new documentation guidelines to git commit
Message-ID: <xmqqh65zvdw1.fsf@gitster.g>
In-Reply-To: <91cff84b5f8d9e1140e94dd96d259224ea905611.1736972628.git.gitgitgadget@gmail.com>

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

> -[verse]
> -'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
> +[synopsis]
> +git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
>  	   [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>]
>  	   [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
>  	   [--allow-empty-message] [--no-verify] [-e] [--author=<author>]

It is already nice enough that with just writing [synopsis] we do
not have to worry about backquoting literals emphasising
<placeholders> and other mark-up minutiae.  And then ...

> --C <commit>::
> ---reuse-message=<commit>::
> -	Take an existing commit object, and reuse the log message
> +`-C <commit>`::
> +`--reuse-message=<commit>`::

... we also are freed from the same worry whenever we use `here are
things that are treated pretty much the same way as in [synopsis]
section` notation like here.  Quite nice.

> @@ -507,12 +507,12 @@ COMMIT INFORMATION
>  Author and committer information is taken from the following environment
>  variables, if set:
>  
> -	GIT_AUTHOR_NAME
> -	GIT_AUTHOR_EMAIL
> -	GIT_AUTHOR_DATE
> -	GIT_COMMITTER_NAME
> -	GIT_COMMITTER_EMAIL
> -	GIT_COMMITTER_DATE
> + * `GIT_AUTHOR_NAME`
> + * `GIT_AUTHOR_EMAIL`
> + * `GIT_AUTHOR_DATE`
> + * `GIT_COMMITTER_NAME`
> + * `GIT_COMMITTER_EMAIL`
> + * `GIT_COMMITTER_DATE`

OK.