asciidoctor: fix `synopsis` rendering
commit8bfc3e47a73b108fd8e7f9c3b9e7714b9f418fa8
authorJohannes Schindelin <johannes.schindelin@gmx.de>
Mon, 22 Jul 2024 20:25:49 +0000 (22 20:25 +0000)
committerJunio C Hamano <gitster@pobox.com>
Mon, 22 Jul 2024 21:13:44 +0000 (22 14:13 -0700)
tree1ac0a635dcfb390f4702efd11f489b9c80dd9470
parentebb55042a4416a07c27ba45eeb24e6ff1899f360
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=
 <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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/.gitignore
Documentation/Makefile
Documentation/docinfo.html [new file with mode: 0644]