From: Jean-Noël AVILA Date: Thu, 12 Mar 2026 17:34:24 GMT Subject: Re: [PATCH 1/3] doc: interpret-trailers: convert to synopsis style Message-ID: <1953989.tdWV9SEqCh@piment-oiseau> In-Reply-To: On Wednesday, 11 March 2026 23:31:04 CET kristofferhaugsbakk@fastmail.com wrote: > From: Kristoffer Haugsbakk > > See e.g. 0ae23ab5 (doc: convert git worktree to synopsis style, > 2025-10-05) for the markup rules for this style. > > There aren’t many subtleties to the transformation of this doc since it > doesn’t use any advanced constructs. The only thing is that `": "` is > used instead of `': '` to refer to effective inline-verbatim with > a space (␠). I also use (_) for emphasis although (') gives the > same result. > > Also prefer linking to Git commands instead of saying > e.g. `git format-patch`. > > Signed-off-by: Kristoffer Haugsbakk > --- > Documentation/git-interpret-trailers.adoc | 126 +++++++++++----------- > 1 file changed, 63 insertions(+), 63 deletions(-) > > diff --git a/Documentation/git-interpret-trailers.adoc > b/Documentation/git-interpret-trailers.adoc index fd335fe772a..8a6c1bff472 100644 > --- a/Documentation/git-interpret-trailers.adoc > +++ b/Documentation/git-interpret-trailers.adoc > @@ -7,14 +7,14 @@ git-interpret-trailers - Add or parse structured information in > commit messages > > SYNOPSIS > -------- > -[verse] > -'git interpret-trailers' [--in-place] [--trim-empty] > +[synopsis] > +git interpret-trailers [--in-place] [--trim-empty] > [(--trailer (|) [(=|:)])...] > [--parse] [...] > > DESCRIPTION > ----------- > -Add or parse 'trailer' lines that look similar to RFC 822 e-mail > +Add or parse _trailer_ lines that look similar to RFC 822 e-mail > headers, at the end of the otherwise free-form part of a commit > message. For example, in the following commit message > > @@ -27,10 +27,10 @@ Signed-off-by: Alice > Signed-off-by: Bob > ------------------------------------------------ > > -the last two lines starting with "Signed-off-by" are trailers. > +the last two lines starting with `Signed-off-by` are trailers. > > This command reads commit messages from either the > - arguments or the standard input if no is specified. > +__ arguments or the standard input if no __ is specified. > If `--parse` is specified, the output consists of the parsed trailers > coming from the input, without influencing them with any command line > options or configuration variables. > @@ -43,7 +43,7 @@ to each input file. The result is emitted on the standard output. > > This command can also operate on the output of linkgit:git-format-patch[1], > which is more elaborate than a plain commit message. Namely, such output > -includes a commit message (as above), a "---" divider line, and a patch part. > +includes a commit message (as above), a `---` divider line, and a patch part. > For these inputs, the divider and patch parts are not modified by > this command and are emitted as is on the output, unless > `--no-divider` is specified. > @@ -53,24 +53,24 @@ are applied to each input and the way any existing trailer in > the input is changed. They also make it possible to > automatically add some trailers. > > -By default, a '=' or ':' argument given > +By default, a `=` or `:` argument given > using `--trailer` will be appended after the existing trailers only if > -the last trailer has a different (, ) pair (or if there > -is no existing trailer). The and parts will be trimmed > +the last trailer has a different (__, __) pair (or if there > +is no existing trailer). The __ and __ parts will be trimmed > to remove starting and trailing whitespace, and the resulting trimmed > - and will appear in the output like this: > +__ and __ will appear in the output like this: > > ------------------------------------------------ > key: value > ------------------------------------------------ > > -This means that the trimmed and will be separated by > -`': '` (one colon followed by one space). > +This means that the trimmed __ and __ will be separated by > +": " (one colon followed by one space). > > -For convenience, a can be configured to make using `--trailer` > +For convenience, a __ can be configured to make using `-- trailer` > shorter to type on the command line. This can be configured using the > -'trailer..key' configuration variable. The must be a prefix > -of the full string, although case sensitivity does not matter. For > +`trailer..key` configuration variable. The __ must be Here, I guess that __ is in fact __ . We do not use camelCase for placeholders. > a > prefix +of the full __ string, although case sensitivity does not matter. For > example, if you have > > ------------------------------------------------ > @@ -91,13 +91,13 @@ least one Git-generated or user-configured trailer and consists > of at least 25% trailers. > The group must be preceded by one or more empty (or whitespace-only) lines. > The group must either be at the end of the input or be the last > -non-whitespace lines before a line that starts with '---' (followed by a > +non-whitespace lines before a line that starts with `---` (followed by a > space or the end of the line). > > When reading trailers, there can be no whitespace before or inside the > -, but any number of regular space and tab characters are allowed > -between the and the separator. There can be whitespaces before, > -inside or after the . The may be split over multiple lines > +__, but any number of regular space and tab characters are allowed > +between the __ and the separator. There can be whitespaces before, > +inside or after the __. The __ may be split over multiple lines > with each subsequent line starting with at least one whitespace, like > the "folding" in RFC 822. Example: > > @@ -111,77 +111,77 @@ rules for RFC 822 headers. For example they do not follow the > encoding rule. > > OPTIONS > ------- > ---in-place:: > +`--in-place`:: > Edit the files in place. > > ---trim-empty:: > - If the part of any trailer contains only whitespace, > +`--trim-empty`:: > + If the __ part of any trailer contains only whitespace, > the whole trailer will be removed from the output. > This applies to existing trailers as well as new trailers. > > ---trailer [(=|:)]:: > - Specify a (, ) pair that should be applied as a > +`--trailer [(=|:)]`:: > + Specify a (__, __) pair that should be applied as a > trailer to the inputs. See the description of this > command. > > ---where :: > ---no-where:: > +`--where `:: > +`--no-where`:: > Specify where all new trailers will be added. A setting > - provided with '--where' overrides the `trailer.where` and any > + provided with `--where` overrides the `trailer.where` and any > applicable `trailer..where` configuration variables Here also, it's instead of . > - and applies to all '--trailer' options until the next occurrence of > - '--where' or '--no-where'. Upon encountering '--no-where', clear the > - effect of any previous use of '--where', such that the relevant configuration > + and applies to all `--trailer` options until the next occurrence of > + `--where` or `--no-where`. Upon encountering `--no-where`, clear the > + effect of any previous use of `--where`, such that the relevant configuration > variables are no longer overridden. Possible placements are `after`, > `before`, `end` or `start`. > > ---if-exists :: > ---no-if-exists:: > +`--if-exists `:: > +`--no-if-exists`:: > Specify what action will be performed when there is already at > - least one trailer with the same in the input. A setting > - provided with '--if-exists' overrides the `trailer.ifExists` and any > + least one trailer with the same __ in the input. A setting > + provided with `--if-exists` overrides the `trailer.ifExists` and any > applicable `trailer..ifExists` configuration variables Idem > - and applies to all '--trailer' options until the next occurrence of > - '--if-exists' or '--no-if-exists'. Upon encountering '--no-if- exists', clear the > - effect of any previous use of '--if-exists', such that the relevant configuration > + and applies to all `--trailer` options until the next occurrence of > + `--if-exists` or `--no-if-exists`. Upon encountering `--no-if- exists`, clear the > + effect of any previous use of `--if-exists`, such that the relevant configuration > variables are no longer overridden. Possible actions are `addIfDifferent`, > `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. > > ---if-missing :: > ---no-if-missing:: > +`--if-missing `:: > +`--no-if-missing`:: > Specify what action will be performed when there is no other > - trailer with the same in the input. A setting > - provided with '--if-missing' overrides the `trailer.ifMissing` and any > + trailer with the same __ in the input. A setting > + provided with `--if-missing` overrides the `trailer.ifMissing` and any > applicable `trailer..ifMissing` configuration variables Idem > - and applies to all '--trailer' options until the next occurrence of > - '--if-missing' or '--no-if-missing'. Upon encountering '--no-if- missing', > - clear the effect of any previous use of '--if-missing', such that the relevant > + and applies to all `--trailer` options until the next occurrence of > + `--if-missing` or `--no-if-missing`. Upon encountering `--no-if- missing`, > + clear the effect of any previous use of `--if-missing`, such that the relevant > configuration variables are no longer overridden. Possible actions are > `doNothing` or `add`. > > ---only-trailers:: > +`--only-trailers`:: > Output only the trailers, not any other parts of the input. > > ---only-input:: > +`--only-input`:: > Output only trailers that exist in the input; do not add any > from the command-line or by applying `trailer.*` configuration The star here stands for a placeholder. Let's name it and use synopsis style: `trailer.` > variables. > > ---unfold:: > +`--unfold`:: > If a trailer has a value that runs over multiple lines (aka "folded"), > reformat the value into a single line. > > ---parse:: > +`--parse`:: > A convenience alias for `--only-trailers --only-input > --unfold`. This makes it easier to only see the trailers coming from the > input without influencing them with any command line options or > configuration variables, while also making the output machine- friendly with > - --unfold. > + `--unfold`. > > ---no-divider:: > +`--no-divider`:: > Do not treat `---` as the end of the commit message. Use this > when you know your input contains just the commit message itself > - (and not an email or the output of `git format-patch`). > + (and not an email or the output of linkgit:git-format-patch[1]). > > CONFIGURATION VARIABLES > ----------------------- > @@ -193,7 +193,7 @@ include::config/trailer.adoc[] > EXAMPLES > -------- > > -* Configure a 'sign' trailer with a 'Signed-off-by' key, and then > +* Configure a `sign` trailer with a `Signed-off-by` key, and then > add two of these trailers to a commit message file: > + > ------------ > @@ -230,8 +230,8 @@ Signed-off-by: Bob > Acked-by: Alice > ------------ > > -* Extract the last commit as a patch, and add a 'Cc' and a > - 'Reviewed-by' trailer to it: > +* Extract the last commit as a patch, and add a `Cc` and a > + `Reviewed-by` trailer to it: > + > ------------ > $ git format-patch -1 > @@ -239,9 +239,9 @@ $ git format-patch -1 > $ git interpret-trailers --trailer 'Cc: Alice ' -- trailer > 'Reviewed-by: Bob ' 0001-foo.patch >0001-bar.patch ------------ > > -* Configure a 'sign' trailer with a command to automatically add a > - 'Signed-off-by: ' with the author information only if there is no > - 'Signed-off-by: ' already, and show how it works: > +* Configure a `sign` trailer with a command to automatically add a > + "Signed-off-by: " with the author information only if there is no > + "Signed-off-by: " already, and show how it works: > + > ------------ > $ cat msg1.txt > @@ -272,7 +272,7 @@ body text > Signed-off-by: Alice > ------------ > > -* Configure a 'fix' trailer with a key that contains a '#' and no > +* Configure a `fix` trailer with a key that contains a `#` and no > space after this character, and show how it works: > + > ------------ > @@ -284,7 +284,7 @@ subject > Fix #42 > ------------ > > -* Configure a 'help' trailer with a cmd use a script `glog-find-author` > +* Configure a `help` trailer with a cmd use a script `glog-find-author` > which search specified author identity from git log in git repository > and show how it works: > + > @@ -308,7 +308,7 @@ Helped-by: Junio C Hamano > Helped-by: Christian Couder > ------------ > > -* Configure a 'ref' trailer with a cmd use a script `glog-grep` > +* Configure a `ref` trailer with a cmd use a script `glog-grep` > to grep last relevant commit from git log in the git repository > and show how it works: > + > @@ -331,7 +331,7 @@ body text > Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) > ------------ > > -* Configure a 'see' trailer with a command to show the subject of a > +* Configure a `see` trailer with a command to show the subject of a > commit that is related, and show how it works: > + > ------------ > @@ -359,8 +359,8 @@ See-also: fe3187489d69c4 (subject of related commit) > * Configure a commit template with some trailers with empty values > (using sed to show and keep the trailing spaces at the end of the > trailers), then configure a commit-msg hook that uses > - 'git interpret-trailers' to remove trailers with empty values and > - to add a 'git-version' trailer: > + linkgit:git-interpret-trailers[1] to remove trailers with empty values We are already in the manual page of git-interpret-trailer. It is useless to provide a link to the current manpage. > and > + to add a `git-version` trailer: > + > ------------ > $ cat temp.txt Thanks.