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

From: Junio C Hamano <[email-masked]>
Date: Sat, 20 Jul 2024 17:01:02 -0700

Junio C Hamano <[email-masked]> 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/[email-masked]/
>
> 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