Skip to content

Commit

Permalink
asciidoctor: fix synopsis rendering
Browse files Browse the repository at this point in the history
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 #5063.

Signed-off-by: Johannes Schindelin <[email protected]>
  • Loading branch information
dscho authored and Git for Windows Build Agent committed Jul 19, 2024
1 parent f806d5d commit 7744e28
Show file tree
Hide file tree
Showing 2 changed files with 6 additions and 0 deletions.
1 change: 1 addition & 0 deletions Documentation/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,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
Expand Down
5 changes: 5 additions & 0 deletions Documentation/docinfo.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<style>
pre>code {
display: inline;
}
</style>

0 comments on commit 7744e28

Please sign in to comment.