[PATCH] asciidoctor: fix `synopsis` rendering

[PATCH] asciidoctor: fix `synopsis` rendering

[Johannes Schindelin via GitGitGadget]

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

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 https://github.com/git-for-windows/git/issues/5063.

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 submitted 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.

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

 Documentation/Makefile     | 1 +
 Documentation/docinfo.html | 5 +++++
 2 files changed, 6 insertions(+)
 create mode 100644 Documentation/docinfo.html

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

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

[Junio C Hamano]

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

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

> 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

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

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

With Jean-Noël Avila's {empty} patch applied, would this patch be
still necessary?  

I am wondering if the reason why "git clone" page needs this patch
while others do not may have something to do with the mistaken
triggering of "generalized roles" feature (whatever it is).  Even
though I dislike that we have to resort to the {empty} hack, if the
misrendered block display you are fixing with this patch is due to
the "generalized roles" problem, fixing the latter would also be the
right fix for your problem.

Thanks.


>> 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

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> 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.
>
> With Jean-Noël Avila's {empty} patch applied, would this patch be
> still necessary?  

The answer is no.  I managed to reproduce the problem your patch
fixes locally, applied Jean-Noël's patch which corrected the mark-up
to avoid losing text in the [square brackets], but the problem still
reproduced.  It really seems that the `monospaced` text that are used
in the SYNOPSIS section are rendered with display:block.

I am not sure if forcing any <code> that appears as a (direct or
indirect) descendant of <pre> with custom css is specific enough,
but that certainly covers the breakage we see on the page.

So the difference I observed between git-clone.html and say git-add.html
is purely coming from use of `monospaced` in SYNOPSIS, and not
because the unintended triggering of a feature by [text]`more text` that
Jean-Noël's patch fixes.  With or without that fix, the css tweak is
still needed (it may be overly generic and may require us to tighten
the selector later, but we can worry about it when somebody finds an
actual breakage).

It is unfortunate that all .html files ought to be generated in this
project (in other words, nobody writes HTML by hand), but asciidoc(tor)
insists that docinfo for html backend must be stored in a file whose
extension is .html, which caused a "huh?" Ramsay reported earlier.

Will queue.  Thanks.

[PATCH v2] asciidoctor: fix `synopsis` rendering

[Johannes Schindelin via GitGitGadget]

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

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

[Junio C Hamano]

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

> 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`.
> ...
>  Documentation/.gitignore   | 1 +
>  Documentation/Makefile     | 1 +
>  Documentation/docinfo.html | 5 +++++
>  3 files changed, 7 insertions(+)
>  create mode 100644 Documentation/docinfo.html

I think our mails crossed.  You need something like this squashed
in, or "make distclean" would make the tree dirty as Ramsay
reported.

 Documentation/Makefile                          | 5 +++++
 Documentation/{docinfo.html => docinfo-html.in} | 0
 2 files changed, 5 insertions(+)
 rename Documentation/{docinfo.html => docinfo-html.in} (100%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 78e407e4bd..371d56eb5e 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -209,6 +209,8 @@ XMLTO_EXTRA += --skip-validation
 XMLTO_EXTRA += -x manpage.xsl
 endif
 
+ASCIIDOC_DEPS += docinfo.html
+
 SHELL_PATH ?= $(SHELL)
 # Shell quote;
 SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
@@ -337,6 +339,9 @@ clean:
 	$(RM) $(cmds_txt) $(mergetools_txt) *.made
 	$(RM) GIT-ASCIIDOCFLAGS
 
+docinfo.html: docinfo-html.in
+	$(QUIET_GEN)$(RM) $@ && cat $< >$@
+
 $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<
 
diff --git a/Documentation/docinfo.html b/Documentation/docinfo-html.in
similarity index 100%
rename from Documentation/docinfo.html
rename to Documentation/docinfo-html.in
-- 
2.46.0-rc1-48-g0900f1888e

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> I think our mails crossed.  You need something like this squashed
> in, or "make distclean" would make the tree dirty as Ramsay
> reported.
> ...

And I needed to undo the .gitignore change between v1 and v2 to
match (otherwise ci/lib.sh notices that docinfo.html is an
"unignored build artifact" and complains).

An updated SQUASH??? fixup looks like this.

Thanks.

 Documentation/.gitignore                        | 1 -
 Documentation/Makefile                          | 5 +++++
 Documentation/{docinfo.html => docinfo-html.in} | 0
 3 files changed, 5 insertions(+), 1 deletion(-)
 rename Documentation/{docinfo.html => docinfo-html.in} (100%)

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index d11567fbbe..a48448de32 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -1,6 +1,5 @@
 *.xml
 *.html
-!/docinfo.html
 *.[1-8]
 *.made
 *.texi
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 78e407e4bd..371d56eb5e 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -209,6 +209,8 @@ XMLTO_EXTRA += --skip-validation
 XMLTO_EXTRA += -x manpage.xsl
 endif
 
+ASCIIDOC_DEPS += docinfo.html
+
 SHELL_PATH ?= $(SHELL)
 # Shell quote;
 SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
@@ -337,6 +339,9 @@ clean:
 	$(RM) $(cmds_txt) $(mergetools_txt) *.made
 	$(RM) GIT-ASCIIDOCFLAGS
 
+docinfo.html: docinfo-html.in
+	$(QUIET_GEN)$(RM) $@ && cat $< >$@
+
 $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<
 
diff --git a/Documentation/docinfo.html b/Documentation/docinfo-html.in
similarity index 100%
rename from Documentation/docinfo.html
rename to Documentation/docinfo-html.in
-- 
2.46.0-rc1-52-g816ffef0a1

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

[Johannes Schindelin]

Hi Junio,

On Mon, 22 Jul 2024, Junio C Hamano wrote:

> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 78e407e4bd..371d56eb5e 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -209,6 +209,8 @@ XMLTO_EXTRA += --skip-validation
>  XMLTO_EXTRA += -x manpage.xsl
>  endif
>
> +ASCIIDOC_DEPS += docinfo.html
> +
>  SHELL_PATH ?= $(SHELL)
>  # Shell quote;
>  SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
> @@ -337,6 +339,9 @@ clean:
>  	$(RM) $(cmds_txt) $(mergetools_txt) *.made
>  	$(RM) GIT-ASCIIDOCFLAGS
>
> +docinfo.html: docinfo-html.in
> +	$(QUIET_GEN)$(RM) $@ && cat $< >$@
> +
>  $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
>  	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<
>

Hmm. This adds a "template" for no other reason than to appease the rule
that all `.html` files in `Documentation/` _must_ be generated. Typically,
templates are only added if anything in them needs to be interpolated to
reflect the particular build, which is not the case here.

Have you considered one of these alternatives?

1. https://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/#customize-extend
   talks about two ways to extend the default style sheet that do _not_
   need to add an `.html` file:

   a. add a `.css` file instead that `@import`s AsciiDoctor's default style
      sheet from a CDN.

      Upside: it is very clean, short, does not need any Makefile rule to
      generate a file that is arguable in no need of being generated.

      Downside: since the `@import` statement cannot refer to a file in the
      same directory as the `.css` file, it incurs a web request. This
      would prevent the build from working on an air-gapped system (such as
      when on a beautiful island without internet access).

   b. generate a `.css` file by merging AsciiDoctor's default style sheet
      with a small CSS snippet.

      Upside: it is again very clean.

      Downside: this would now require a Makefile rule when previously we
      managed without one.

2. simply adjust the `check_unignored_build_artifacts()` function to know
   about `docinfo.html`.

   Upside: it is still short and does not need any Makefile rule where
   previously no such thing was required.

   Downside: the simple rule "all .html files in Documentation/ _must_ be
   generated" would no longer hold true, making the architecture slightly
   harder to explain to newcomers.

3. stop mixing generated and source files in `Documentation/`. Instead,
   put the HTML files into a subdirectory that is clearly marked as
   containing only generated files.

   Upside: this would provide an overall cleaner architecture.

   Downside: lots of work, may require some convincing of oldtimers who
   see nothing wrong with mixing source and generated files.

Ciao,
Johannes

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

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Hmm. This adds a "template" for no other reason than to appease the rule
> that all `.html` files in `Documentation/` _must_ be generated. Typically,
> templates are only added if anything in them needs to be interpolated to
> reflect the particular build, which is not the case here.

Consider that we leave the door open for future enhancements (like,
lose the conditional compilation and instead make it an empty file
when AsciiDoc and not asciidoctor is in use).

> Have you considered one of these alternatives?

No, because I am not interested in anything more elaborate a few
days before tagging -rc2.  If this is not meant for the upcoming
release, then I am all ears (and eyes), but otherwise, let's just do
the simplest and the most obvious thing to unbreak users for the
upcoming release and leave a more elaborate engineering to next
cycle.

Jean-Noël is planning to undo the overly elaborate mark-up and that
may eliminate the need to work around "<code> in <pre> is made into
a block element" behaviour of default asciidoctor style in the first
place, so the longer term plan should take that into account as well.

Thanks.