[PATCH v2] asciidoctor: fix `synopsis` rendering

["Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com>]

From: Johannes Schindelin <johannes.schindelin@gmx.de>

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=
	 <template-directory>]
		  [
	 -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
`<code>` 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
`<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.

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 `<code>` 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 <johannes.schindelin@gmx.de>
---
    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 merged 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.
    
    Changes since v1:
    
     * Clarified the commit message to motivate better why this patch is
       required.
     * Exempted the docinfo.html file in .gitignore from being mistaken for
       an untrackable file.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1749%2Fdscho%2Ffix-synopses-rendering-with-asciidoctor-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1749/dscho/fix-synopses-rendering-with-asciidoctor-v2
Pull-Request: https://github.com/git/git/pull/1749

Range-diff vs v1:

 1:  ee3ee00a199 ! 1:  41522706456 asciidoctor: fix `synopsis` rendering
     @@ Commit message
          `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,
     +    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
     @@ Commit message
                   ] [
                  [... 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.
     +    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
     +    `<code>` 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
     @@ Commit message
      
          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 `<code>` 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 <johannes.schindelin@gmx.de>
      
     + ## Documentation/.gitignore ##
     +@@
     + *.xml
     + *.html
     ++!/docinfo.html
     + *.[1-8]
     + *.made
     + *.texi
     +
       ## Documentation/Makefile ##
      @@ Documentation/Makefile: ASCIIDOC_DOCBOOK = docbook5
       ASCIIDOC_EXTRA += -acompat-mode -atabsize=8


 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 a48448de32f..d11567fbbe7 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 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