Re: [PATCH] asciidoctor: fix `synopsis` rendering

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 20, 2024, 23:01 UTC
Message-ID: <xmqqsew3hdmv.fsf@gitster.g>
In-Reply-To: <pull.1749.git.git.1721507416683.gitgitgadget@gmail.com>

"Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 27 quoted lines

> 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, 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 ...]

Hmph, this may probably depend on the version of asciidoctor, but I am getting quite different output. It looks very similar to what is shown at https://git-scm.com/docs/git-clone/2.45.0.

Even more puzzling, with or without this patch applied, I do not see any difference in the rendered output of samples I used, which were "clone", which has the changes from 76880f0510c and "add", which hasn't been broken by the series.

 $ make -C Documentation USE_ASCIIDOCTOR=YesPlease git-{clone,add}.{html,1}
 $ man -l Documentation/git-clone.1
 $ lynx Documentation/git-clone.html
 $ man -l Documentation/git-add.1
 $ lynx Documentation/git-add.html

The rendered result is bad in the same way with or without this patch applied, and "git clone" manual page is simply incorrect by mangling a handful of command line options. A recent bug report in the thread that contains

    https://lore.kernel.org/git/xmqqle1xjm1s.fsf@gitster.g/

gives us more details.

Show 25 quoted lines

> 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