Thread (6 messages) flat view 6 messages, 2 authors, 16h ago
HOTtoday

[PATCH 0/3] doc lint fixes for pack-refs and refs

From: Todd Zullinger <hidden>
Date: 2026-09-12 19:15:34

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

-- 
2.56.0.rc0
Keyboard shortcuts
hback out one level
jnext message in thread
kprevious message in thread
ldrill in
Escclose help / fold thread tree
?toggle this help