From 4152270645677aa505a59c90c42a5df33d779c79 Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Thu, 18 Jul 2024 08:55:13 +0200 Subject: [PATCH] asciidoctor: fix `synopsis` rendering 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 and displayed in a graphical web browser such as Firefox, Chrome, Edge, etc, the result is quite unpleasant to my eye, reading something like this: SYNOPSIS git clone [ --template= ] [ -l ] [ -s ] [ --no-hardlinks ] [ -q ] [ [... continuing like this ...] The reason is that AsciiDoctor's default style sheet contains this (see https://github.com/asciidoctor/asciidoctor/blob/854923b15533/src/stylesheets/asciidoctor.css#L519-L521 for context): pre > code { display: block; } It is this `display: block` that forces the parts that are enclosed in `` tags (such as the `git clone` or the `--template=` part) to be rendered on their own line. Side note: This seems not to affect console web browsers like `lynx` or `w3m`, most likely because most style sheet directions cannot be respected in text terminals and therefore they seem to punt on style sheets altogether. 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 `` 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. Even on the Git home page, where AsciiDoctor's default stylesheet is _not_ used, this change resulted in some unpleasant rendering where not only the font is changed for the `` sections of the synopsis, but padding and a different background color make the visual impression quite uneven. This has been addressed in the meantime, via https://github.com/git/git-scm.com/commit/a492d0565512. Signed-off-by: Johannes Schindelin --- Documentation/.gitignore | 1 + Documentation/Makefile | 1 + Documentation/docinfo.html | 5 +++++ 3 files changed, 7 insertions(+) create mode 100644 Documentation/docinfo.html diff --git a/Documentation/.gitignore b/Documentation/.gitignore index a48448de32f98b..d11567fbbe7135 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -1,5 +1,6 @@ *.xml *.html +!/docinfo.html *.[1-8] *.made *.texi diff --git a/Documentation/Makefile b/Documentation/Makefile index 3f2383a12c77d0..78e407e4bd1608 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 00000000000000..fb3560eb92b4ee --- /dev/null +++ b/Documentation/docinfo.html @@ -0,0 +1,5 @@ +