Re: [PATCH v3 1/4] doc: convert git-submodule to synopsis style

> On Tue, Feb 3, 2026, at 18:03, Jean-Noël Avila via GitGitGadget wrote:
>> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>>
>>  * convert commands to synopsis style
>>  * use _<placeholder>_ for arguments
>>  * convert inline lists into proper definition lists
>>  * minor formatting fixes
>>
>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
>> Reviewed-by: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
> 
> `Reviewed-by` is a special case. It’s the only trailer that has to be
> given explicitly by the person.
> 
> (trailers that credit other people should also come before the signoff)
> 
> Thanks for the credit, of course. :)
> 
>> ---
>>  Documentation/git-submodule.adoc | 389 ++++++++++++++++---------------
>>  1 file changed, 196 insertions(+), 193 deletions(-)
>>
>> diff --git a/Documentation/git-submodule.adoc b/Documentation/git-submodule.adoc
>> index 95beaee561..e581b0c7aa 100644
>> --- a/Documentation/git-submodule.adoc
>> +++ b/Documentation/git-submodule.adoc
>> @@ -8,19 +8,19 @@ git-submodule - Initialize, update or inspect submodules
>> [snip]
>>  DESCRIPTION
>> @@ -34,16 +34,16 @@ COMMANDS
>>  With no arguments, shows the status of existing submodules.  Several
>>  subcommands are available to perform operations on the submodules.
>>
>> -add [-b <branch>] [-f|--force] [--name <name>] [--reference
>> <repository>] [--ref-format <format>] [--depth <depth>] [--]
>> <repository> [<path>]::
>> +`add [-b <branch>] [-f | --force] [--name <name>] [--reference
>> <repository>] [--ref-format <format>] [--depth <depth>] [--]
>> <repository> [<path>]`::
>>  	Add the given repository as a submodule at the given path
>>  	to the changeset to be committed next to the current
>>  	project: the current project is termed the "superproject".
>>  +
>> -<repository> is the URL of the new submodule's origin repository.
>> -This may be either an absolute URL, or (if it begins with ./
>> -or ../), the location relative to the superproject's default remote
>> -repository (Please note that to specify a repository 'foo.git'
>> -which is located right next to a superproject 'bar.git', you'll
>> +_<repository>_ is the URL of the new submodule's `origin` repository.
> 
> This (`origin`) is new. I have never used git-submodule(1). Is this
> *code* or is it jargon for something like “original” repository? It came
> in commit ec05df35 (git-submodule - make "submodule add" more strict,
> and document it, 2008-07-09):
> 
>     With this patch, the URL locating the submodule's origin repository can be
>     either an absolute URL, or (if it begins with ./ or ../) can express the
>     submodule's repository location relative to the superproject's origin.
> 
> The "origin" that I referred to in the previous round was this sentence
> a little way down:
> 
>     If no such remote-tracking branch exists or the HEAD is detached,
>     "origin" is assumed to be the default remote.
> 
> And here I read “origin” as a real, concrete name. Which is why I
> thought `origin` would fit instead.
> 

>> +This may be either an absolute URL, or (if it begins with `./`
>> +or `../`), the location relative to the superproject's default remote
>> +repository (Please note that to specify a repository `foo.git`
>> +which is located right next to a superproject `bar.git`, you'll
>> [snip]
>>
>> -status [--cached] [--recursive] [--] [<path>...]::
>> +`status [--cached] [--recursive] [--] [<path>...]`::
>>  	Show the status of the submodules. This will print the SHA-1 of the
>>  	currently checked out commit for each submodule, along with the
>> -	submodule path and the output of 'git describe' for the
>> +	submodule path and the output of linkgit:git-describe[1] for the
>>  	SHA-1. Each SHA-1 will possibly be prefixed with `-` if the submodule
>> is
>>  	not initialized, `+` if the currently checked out submodule commit
>>  	does not match the SHA-1 found in the index of the containing
>> @@ -95,7 +95,7 @@ submodules with respect to the commit recorded in the
>> index or the HEAD,
> 
> Nit: There are some remaining “HEAD” without backticks.
> 
> The phrasing “the HEAD” does also keep recurring. Might be worth
> replacing with just `HEAD` at this point?