Skip to content

Commit 8c57d22

Browse files
authored
asciidoctor: fix synopsis rendering (git-for-windows#5064)
Since 76880f0 (doc: git-clone: apply new documentation formatting guidelines, 2024-03-29), the synopsis of `git clone`'s manual page is rendered differently than before; Its parent commit did the same for `git init`. The result looks quite nice. When rendered with AsciiDoc, that is. When rendered using AsciiDoctor, the result is quite unpleasant to my eye, reading something like this: SYNOPSIS git clone [ --template= <template-directory>] [ -l ] [ -s ] [ --no-hardlinks ] [ -q ] [ [... continuing like this ...] Even on the Git home page, where AsciiDoctor's default stylesheet is not used, this change results in some unpleasant rendering where not only the font is changed for the `<code>` sections of the synopsis, but padding and a different background color make the visual impression quite uneven: compare https://git-scm.com/docs/git-clone/2.45.0 to https://git-scm.com/docs/git-clone/2.44.0. To fix this, let's apply the method recommended by AsciiDoctor in https://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/#customize-docinfo to partially override AsciiDoctor's default style sheet so that the `<code>` sections of the synopsis are no longer each rendered on their own, individual lines. This fixes git-for-windows#5063. Thanks for taking the time to contribute to Git! Those seeking to contribute to the Git for Windows fork should see http://gitforwindows.org/#contribute on how to contribute Windows specific enhancements. If your contribution is for the core Git functions and documentation please be aware that the Git community does not use the github.com issues or pull request mechanism for their contributions. Instead, we use the Git mailing list ([email protected]) for code and documentation submissions, code reviews, and bug reports. The mailing list is plain text only (anything with HTML is sent directly to the spam folder). Nevertheless, you can use GitGitGadget (https://gitgitgadget.github.io/) to conveniently send your Pull Requests commits to our mailing list. For a single-commit pull request, please *leave the pull request description empty*: your commit message itself should describe your changes. Please read the "guidelines for contributing" linked above!
2 parents f46b4dc + ee3ee00 commit 8c57d22

File tree

2 files changed

+6
-0
lines changed

2 files changed

+6
-0
lines changed

Documentation/Makefile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,7 @@ ASCIIDOC_DOCBOOK = docbook5
204204
ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
205205
ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
206206
ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
207+
ASCIIDOC_EXTRA += -adocinfo=shared
207208
ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
208209
DBLATEX_COMMON =
209210
XMLTO_EXTRA += --skip-validation

Documentation/docinfo.html

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<style>
2+
pre>code {
3+
display: inline;
4+
}
5+
</style>

0 commit comments

Comments
 (0)