Re: [PATCH 0/3] doc lint fixes for pack-refs and refs
- From
Jean-Noël AVILA <jn.avila@free.fr>
- Date
- Sep 13, 2026, 10:26 UTC
- Message-ID
- <Uds1uZlUTZi1p6vFK4zhWg@free.fr>
- In-Reply-To
- <20260912191509.844954-1-tmz@pobox.com>
On Saturday, 12 September 2026 21:14:59 CEST Todd Zullinger wrote:
> I was reading git-refs(1) after noticing it learned some new tricks in the > 2.56.0 release notes. The formatting stood out because the first two
commands,
> migrate and verify are bold (in the man pages) but subsequent commands are
not.
Show 9 quoted lines
> The HTML is similarly affected, with those commands colored differently than > the rest in our online documentation: > > https://git-scm.com/docs/git-refs > > This is due to inconsistent backtick-quotes. > > This led me to the lint check, which I think might benefit from the small > change here to match commands as well as options. Running something like
this
Show 8 quoted lines
> reports a number of files which could also use some tweaks: > > cd Documentation && for i in *.adoc; do > output=$(perl lint-documentation-style.perl <$i 2>&1) > [[ -n $output ]] && printf '\n%s:\n%s\n' $i "$output" > done > > I _think_ we want to backtick-quote those when using the synopsis style.
(If
> not, then the change is wrong and we should remove the backticks from the
two
> commands in git-refs.adoc and other places.) > > As git-refs.adoc includes pack-refs-options.adoc, I updated it to
consistently
Show 13 quoted lines
> use backtick quoting and converted the only other file which includes it, > git-pack-refs.adoc. > > Todd Zullinger (3): > doc lint: match commands as well as options for synopsis style check > doc/pack-refs: convert synopsis and options to new style > doc/refs: backtick-quote commands and options consistently > > Documentation/git-pack-refs.adoc | 8 ++++---- > Documentation/git-refs.adoc | 14 +++++++------- > Documentation/lint-documentation-style.perl | 4 ++-- > Documentation/pack-refs-options.adoc | 10 +++++----- > 4 files changed, 18 insertions(+), 18 deletions(-)
When I put this linting in place, I was specifically targeting the options. The other cases of use of definition list could range from commands to real definitions of words (see gitglossary.adoc and git-add.adoc), and extending the match can trigger false positives. Backticked terms are supposed to be immutable for translators, so this formatting should not be used for real definitions. For this reason, the regex is restricted on purpose, but selecting the files to check to allow to extend the range of checks. , FWIW, the proposed change triggers false positives for git-add.adoc, git- push.adoc, git-difftool.adoc, git-daemon.adoc and git-fetch.adoc.