Skip to content

Commit

Permalink
asciidoctor: fix synopsis rendering (#5064)
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.

Thanks for taking the time to contribute to Git!

Those seeking to contribute to the Git for Windows fork should see
http://gitforwindows.org/#contribute on how to contribute Windows
specific
enhancements.

If your contribution is for the core Git functions and documentation
please be aware that the Git community does not use the github.com
issues
or pull request mechanism for their contributions.

Instead, we use the Git mailing list ([email protected]) for code and
documentation submissions, code reviews, and bug reports. The
mailing list is plain text only (anything with HTML is sent directly
to the spam folder).

Nevertheless, you can use GitGitGadget (https://gitgitgadget.github.io/)
to conveniently send your Pull Requests commits to our mailing list.

For a single-commit pull request, please *leave the pull request
description
empty*: your commit message itself should describe your changes.

Please read the "guidelines for contributing" linked above!
  • Loading branch information
dscho authored and Git for Windows Build Agent committed Jul 19, 2024
2 parents 3490858 + 7744e28 commit ac490f7
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 ac490f7

Please sign in to comment.