From: Johannes Schindelin <johannes.schindelin@xxxxxx> Since 76880f0510c (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 https://github.com/git-for-windows/git/issues/5063. Signed-off-by: Johannes Schindelin <johannes.schindelin@xxxxxx> --- asciidoctor: fix synopsis rendering This was reported in https://github.com/git-for-windows/git/issues/5063 and has been fixed in Git for Windows already (in https://github.com/git-for-windows/git/pull/5064, because Git for Windows uses AsciiDoctor to render the HTML help pages). A related fix for https://git-scm.com/docs/ (where AsciiDoctor is used, too) was submitted as part of https://github.com/git/git-scm.com/pull/1855. This patch is based on ja/doc-markup-updates, but also applies cleanly to the default branch. Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1749%2Fdscho%2Ffix-synopses-rendering-with-asciidoctor-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1749/dscho/fix-synopses-rendering-with-asciidoctor-v1 Pull-Request: https://github.com/git/git/pull/1749 Documentation/Makefile | 1 + Documentation/docinfo.html | 5 +++++ 2 files changed, 6 insertions(+) create mode 100644 Documentation/docinfo.html diff --git a/Documentation/Makefile b/Documentation/Makefile index 3f2383a12c7..78e407e4bd1 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -202,6 +202,7 @@ ASCIIDOC_DOCBOOK = docbook5 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' +ASCIIDOC_EXTRA += -adocinfo=shared ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS DBLATEX_COMMON = XMLTO_EXTRA += --skip-validation diff --git a/Documentation/docinfo.html b/Documentation/docinfo.html new file mode 100644 index 00000000000..fb3560eb92b --- /dev/null +++ b/Documentation/docinfo.html @@ -0,0 +1,5 @@ +<style> +pre>code { + display: inline; +} +</style> base-commit: 76880f0510c6be9f6385f2d43dcfcba4eca9ccbc -- gitgitgadget
