{"thread":{"id":"61815","subject":"[PATCH] asciidoctor: fix `synopsis` rendering","startedAt":"2024-07-20T20:30:19Z","lastAt":"2024-07-23T16:43:25Z","messageCount":9,"participants":["Johannes Schindelin via GitGitGadget","Junio C Hamano","Johannes Schindelin"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"499009","messageId":"pull.1749.git.git.1721507416683.gitgitgadget@gmail.com","threadId":"61815","inReplyTo":null,"subject":"[PATCH] asciidoctor: fix `synopsis` rendering","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-07-20T20:30:16Z","receivedAt":"2024-07-20T20:30:19Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin <johannes.schindelin@gmx.de>\n\nSince 76880f0510c (doc: git-clone: apply new documentation formatting\nguidelines, 2024-03-29), the synopsis of `git clone`'s manual page is\nrendered differently than before; Its parent commit did the same for\n`git init`.\n\nThe result looks quite nice. When rendered with AsciiDoc, that is. When\nrendered using AsciiDoctor, the result is quite unpleasant to my eye,\nreading something like this:\n\n\tSYNOPSIS\n\n\t git clone\n\t  [\n\t --template=\n\t <template-directory>]\n\t\t  [\n\t -l\n\t ] [\n\t -s\n\t ] [\n\t --no-hardlinks\n\t ] [\n\t -q\n\t ] [\n\t[... continuing like this ...]\n\nEven on the Git home page, where AsciiDoctor's default stylesheet is not\nused, this change results in some unpleasant rendering where not only\nthe font is changed for the `<code>` sections of the synopsis, but\npadding and a different background color make the visual impression\nquite uneven: compare https://git-scm.com/docs/git-clone/2.45.0 to\nhttps://git-scm.com/docs/git-clone/2.44.0.\n\nTo fix this, let's apply the method recommended by AsciiDoctor in\nhttps://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/#customize-docinfo\nto partially override AsciiDoctor's default style sheet so that the\n`<code>` sections of the synopsis are no longer each rendered on their\nown, individual lines.\n\nThis fixes https://github.com/git-for-windows/git/issues/5063.\n\nSigned-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>\n---\n    asciidoctor: fix synopsis rendering\n    \n    This was reported in https://github.com/git-for-windows/git/issues/5063\n    and has been fixed in Git for Windows already (in\n    https://github.com/git-for-windows/git/pull/5064, because Git for\n    Windows uses AsciiDoctor to render the HTML help pages).\n    \n    A related fix for https://git-scm.com/docs/ (where AsciiDoctor is used,\n    too) was submitted as part of\n    https://github.com/git/git-scm.com/pull/1855.\n    \n    This patch is based on ja/doc-markup-updates, but also applies cleanly\n    to the default branch.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1749%2Fdscho%2Ffix-synopses-rendering-with-asciidoctor-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1749/dscho/fix-synopses-rendering-with-asciidoctor-v1\nPull-Request: https://github.com/git/git/pull/1749\n\n Documentation/Makefile     | 1 +\n Documentation/docinfo.html | 5 +++++\n 2 files changed, 6 insertions(+)\n create mode 100644 Documentation/docinfo.html\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3f2383a12c7..78e407e4bd1 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -202,6 +202,7 @@ ASCIIDOC_DOCBOOK = docbook5\n ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n+ASCIIDOC_EXTRA += -adocinfo=shared\n ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n DBLATEX_COMMON =\n XMLTO_EXTRA += --skip-validation\ndiff --git a/Documentation/docinfo.html b/Documentation/docinfo.html\nnew file mode 100644\nindex 00000000000..fb3560eb92b\n--- /dev/null\n+++ b/Documentation/docinfo.html\n@@ -0,0 +1,5 @@\n+<style>\n+pre>code {\n+   display: inline;\n+}\n+</style>\n\nbase-commit: 76880f0510c6be9f6385f2d43dcfcba4eca9ccbc\n-- \ngitgitgadget\n"},{"id":"499019","messageId":"xmqqsew3hdmv.fsf@gitster.g","threadId":"61815","inReplyTo":"pull.1749.git.git.1721507416683.gitgitgadget@gmail.com","subject":"Re: [PATCH] asciidoctor: fix `synopsis` rendering","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-20T23:01:12Z","receivedAt":"2024-07-20T23:01:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Johannes Schindelin via GitGitGadget\" <gitgitgadget@gmail.com>\nwrites:\n\n> From: Johannes Schindelin <johannes.schindelin@gmx.de>\n>\n> Since 76880f0510c (doc: git-clone: apply new documentation formatting\n> guidelines, 2024-03-29), the synopsis of `git clone`'s manual page is\n> rendered differently than before; Its parent commit did the same for\n> `git init`.\n>\n> The result looks quite nice. When rendered with AsciiDoc, that is. When\n> rendered using AsciiDoctor, the result is quite unpleasant to my eye,\n> reading something like this:\n>\n> \tSYNOPSIS\n>\n> \t git clone\n> \t  [\n> \t --template=\n> \t <template-directory>]\n> \t\t  [\n> \t -l\n> \t ] [\n> \t -s\n> \t ] [\n> \t --no-hardlinks\n> \t ] [\n> \t -q\n> \t ] [\n> \t[... continuing like this ...]\n\nHmph, this may probably depend on the version of asciidoctor, but I\nam getting quite different output.  It looks very similar to what is\nshown at https://git-scm.com/docs/git-clone/2.45.0.\n\nEven more puzzling, with or without this patch applied, I do not see\nany difference in the rendered output of samples I used, which were\n\"clone\", which has the changes from 76880f0510c and \"add\", which\nhasn't been broken by the series.\n\n $ make -C Documentation USE_ASCIIDOCTOR=YesPlease git-{clone,add}.{html,1}\n $ man -l Documentation/git-clone.1\n $ lynx Documentation/git-clone.html\n $ man -l Documentation/git-add.1\n $ lynx Documentation/git-add.html\n\nThe rendered result is bad in the same way with or without this\npatch applied, and \"git clone\" manual page is simply incorrect by\nmangling a handful of command line options.  A recent bug report in\nthe thread that contains\n\n    https://lore.kernel.org/git/xmqqle1xjm1s.fsf@gitster.g/\n\ngives us more details.\n\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 3f2383a12c7..78e407e4bd1 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -202,6 +202,7 @@ ASCIIDOC_DOCBOOK = docbook5\n>  ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n>  ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n>  ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n> +ASCIIDOC_EXTRA += -adocinfo=shared\n>  ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n>  DBLATEX_COMMON =\n>  XMLTO_EXTRA += --skip-validation\n> diff --git a/Documentation/docinfo.html b/Documentation/docinfo.html\n> new file mode 100644\n> index 00000000000..fb3560eb92b\n> --- /dev/null\n> +++ b/Documentation/docinfo.html\n> @@ -0,0 +1,5 @@\n> +<style>\n> +pre>code {\n> +   display: inline;\n> +}\n> +</style>\n>\n> base-commit: 76880f0510c6be9f6385f2d43dcfcba4eca9ccbc\n"},{"id":"499022","messageId":"xmqqr0bnfwap.fsf@gitster.g","threadId":"61815","inReplyTo":"xmqqsew3hdmv.fsf@gitster.g","subject":"Re: [PATCH] asciidoctor: fix `synopsis` rendering","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-21T00:01:02Z","receivedAt":"2024-07-21T00:01:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> The rendered result is bad in the same way with or without this\n> patch applied, and \"git clone\" manual page is simply incorrect by\n> mangling a handful of command line options.  A recent bug report in\n> the thread that contains\n>\n>     https://lore.kernel.org/git/xmqqle1xjm1s.fsf@gitster.g/\n>\n> gives us more details.\n\nWith Jean-Noël Avila's {empty} patch applied, would this patch be\nstill necessary?  \n\nI am wondering if the reason why \"git clone\" page needs this patch\nwhile others do not may have something to do with the mistaken\ntriggering of \"generalized roles\" feature (whatever it is).  Even\nthough I dislike that we have to resort to the {empty} hack, if the\nmisrendered block display you are fixing with this patch is due to\nthe \"generalized roles\" problem, fixing the latter would also be the\nright fix for your problem.\n\nThanks.\n\n\n>> diff --git a/Documentation/Makefile b/Documentation/Makefile\n>> index 3f2383a12c7..78e407e4bd1 100644\n>> --- a/Documentation/Makefile\n>> +++ b/Documentation/Makefile\n>> @@ -202,6 +202,7 @@ ASCIIDOC_DOCBOOK = docbook5\n>>  ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n>>  ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n>>  ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n>> +ASCIIDOC_EXTRA += -adocinfo=shared\n>>  ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n>>  DBLATEX_COMMON =\n>>  XMLTO_EXTRA += --skip-validation\n>> diff --git a/Documentation/docinfo.html b/Documentation/docinfo.html\n>> new file mode 100644\n>> index 00000000000..fb3560eb92b\n>> --- /dev/null\n>> +++ b/Documentation/docinfo.html\n>> @@ -0,0 +1,5 @@\n>> +<style>\n>> +pre>code {\n>> +   display: inline;\n>> +}\n>> +</style>\n>>\n>> base-commit: 76880f0510c6be9f6385f2d43dcfcba4eca9ccbc\n"},{"id":"499062","messageId":"xmqqy15te6i8.fsf@gitster.g","threadId":"61815","inReplyTo":"xmqqr0bnfwap.fsf@gitster.g","subject":"Re: [PATCH] asciidoctor: fix `synopsis` rendering","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-22T16:27:59Z","receivedAt":"2024-07-22T16:28:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Junio C Hamano <gitster@pobox.com> writes:\n>\n>> The rendered result is bad in the same way with or without this\n>> patch applied, and \"git clone\" manual page is simply incorrect by\n>> mangling a handful of command line options.  A recent bug report in\n>> the thread that contains\n>>\n>>     https://lore.kernel.org/git/xmqqle1xjm1s.fsf@gitster.g/\n>>\n>> gives us more details.\n>\n> With Jean-Noël Avila's {empty} patch applied, would this patch be\n> still necessary?  \n\nThe answer is no.  I managed to reproduce the problem your patch\nfixes locally, applied Jean-Noël's patch which corrected the mark-up\nto avoid losing text in the [square brackets], but the problem still\nreproduced.  It really seems that the `monospaced` text that are used\nin the SYNOPSIS section are rendered with display:block.\n\nI am not sure if forcing any <code> that appears as a (direct or\nindirect) descendant of <pre> with custom css is specific enough,\nbut that certainly covers the breakage we see on the page.\n\nSo the difference I observed between git-clone.html and say git-add.html\nis purely coming from use of `monospaced` in SYNOPSIS, and not\nbecause the unintended triggering of a feature by [text]`more text` that\nJean-Noël's patch fixes.  With or without that fix, the css tweak is\nstill needed (it may be overly generic and may require us to tighten\nthe selector later, but we can worry about it when somebody finds an\nactual breakage).\n\nIt is unfortunate that all .html files ought to be generated in this\nproject (in other words, nobody writes HTML by hand), but asciidoc(tor)\ninsists that docinfo for html backend must be stored in a file whose\nextension is .html, which caused a \"huh?\" Ramsay reported earlier.\n\nWill queue.  Thanks.\n"},{"id":"499079","messageId":"pull.1749.v2.git.git.1721679949618.gitgitgadget@gmail.com","threadId":"61815","inReplyTo":"pull.1749.git.git.1721507416683.gitgitgadget@gmail.com","subject":"[PATCH v2] asciidoctor: fix `synopsis` rendering","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-07-22T20:25:49Z","receivedAt":"2024-07-22T20:25:56Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin <johannes.schindelin@gmx.de>\n\nSince 76880f0510c (doc: git-clone: apply new documentation formatting\nguidelines, 2024-03-29), the synopsis of `git clone`'s manual page is\nrendered differently than before; Its parent commit did the same for\n`git init`.\n\nThe result looks quite nice. When rendered with AsciiDoc, that is. When\nrendered using AsciiDoctor and displayed in a graphical web browser such\nas Firefox, Chrome, Edge, etc, the result is quite unpleasant to my eye,\nreading something like this:\n\n\tSYNOPSIS\n\n\t git clone\n\t  [\n\t --template=\n\t <template-directory>]\n\t\t  [\n\t -l\n\t ] [\n\t -s\n\t ] [\n\t --no-hardlinks\n\t ] [\n\t -q\n\t ] [\n\t[... continuing like this ...]\n\nThe reason is that AsciiDoctor's default style sheet contains this (see\nhttps://github.com/asciidoctor/asciidoctor/blob/854923b15533/src/stylesheets/asciidoctor.css#L519-L521\nfor context):\n\n\tpre > code {\n\t  display: block;\n\t}\n\nIt is this `display: block` that forces the parts that are enclosed in\n`<code>` tags (such as the `git clone` or the `--template=` part) to be\nrendered on their own line.\n\nSide note: This seems not to affect console web browsers like `lynx` or\n`w3m`, most likely because most style sheet directions cannot be\nrespected in text terminals and therefore they seem to punt on style\nsheets altogether.\n\nTo fix this, let's apply the method recommended by AsciiDoctor in\nhttps://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/#customize-docinfo\nto partially override AsciiDoctor's default style sheet so that the\n`<code>` sections of the synopsis are no longer each rendered on their\nown, individual lines.\n\nThis fixes https://github.com/git-for-windows/git/issues/5063.\n\nEven on the Git home page, where AsciiDoctor's default stylesheet is\n_not_ used, this change resulted in some unpleasant rendering where not\nonly the font is changed for the `<code>` sections of the synopsis, but\npadding and a different background color make the visual impression\nquite uneven. This has been addressed in the meantime, via\nhttps://github.com/git/git-scm.com/commit/a492d0565512.\n\nSigned-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>\n---\n    asciidoctor: fix synopsis rendering\n    \n    This was reported in https://github.com/git-for-windows/git/issues/5063\n    and has been fixed in Git for Windows already (in\n    https://github.com/git-for-windows/git/pull/5064, because Git for\n    Windows uses AsciiDoctor to render the HTML help pages).\n    \n    A related fix for https://git-scm.com/docs/ (where AsciiDoctor is used,\n    too) was merged as part of https://github.com/git/git-scm.com/pull/1855.\n    \n    This patch is based on ja/doc-markup-updates, but also applies cleanly\n    to the default branch.\n    \n    Changes since v1:\n    \n     * Clarified the commit message to motivate better why this patch is\n       required.\n     * Exempted the docinfo.html file in .gitignore from being mistaken for\n       an untrackable file.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1749%2Fdscho%2Ffix-synopses-rendering-with-asciidoctor-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1749/dscho/fix-synopses-rendering-with-asciidoctor-v2\nPull-Request: https://github.com/git/git/pull/1749\n\nRange-diff vs v1:\n\n 1:  ee3ee00a199 ! 1:  41522706456 asciidoctor: fix `synopsis` rendering\n     @@ Commit message\n          `git init`.\n      \n          The result looks quite nice. When rendered with AsciiDoc, that is. When\n     -    rendered using AsciiDoctor, the result is quite unpleasant to my eye,\n     +    rendered using AsciiDoctor and displayed in a graphical web browser such\n     +    as Firefox, Chrome, Edge, etc, the result is quite unpleasant to my eye,\n          reading something like this:\n      \n                  SYNOPSIS\n     @@ Commit message\n                   ] [\n                  [... continuing like this ...]\n      \n     -    Even on the Git home page, where AsciiDoctor's default stylesheet is not\n     -    used, this change results in some unpleasant rendering where not only\n     -    the font is changed for the `<code>` sections of the synopsis, but\n     -    padding and a different background color make the visual impression\n     -    quite uneven: compare https://git-scm.com/docs/git-clone/2.45.0 to\n     -    https://git-scm.com/docs/git-clone/2.44.0.\n     +    The reason is that AsciiDoctor's default style sheet contains this (see\n     +    https://github.com/asciidoctor/asciidoctor/blob/854923b15533/src/stylesheets/asciidoctor.css#L519-L521\n     +    for context):\n     +\n     +            pre > code {\n     +              display: block;\n     +            }\n     +\n     +    It is this `display: block` that forces the parts that are enclosed in\n     +    `<code>` tags (such as the `git clone` or the `--template=` part) to be\n     +    rendered on their own line.\n     +\n     +    Side note: This seems not to affect console web browsers like `lynx` or\n     +    `w3m`, most likely because most style sheet directions cannot be\n     +    respected in text terminals and therefore they seem to punt on style\n     +    sheets altogether.\n      \n          To fix this, let's apply the method recommended by AsciiDoctor in\n          https://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/#customize-docinfo\n     @@ Commit message\n      \n          This fixes https://github.com/git-for-windows/git/issues/5063.\n      \n     +    Even on the Git home page, where AsciiDoctor's default stylesheet is\n     +    _not_ used, this change resulted in some unpleasant rendering where not\n     +    only the font is changed for the `<code>` sections of the synopsis, but\n     +    padding and a different background color make the visual impression\n     +    quite uneven. This has been addressed in the meantime, via\n     +    https://github.com/git/git-scm.com/commit/a492d0565512.\n     +\n          Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>\n      \n     + ## Documentation/.gitignore ##\n     +@@\n     + *.xml\n     + *.html\n     ++!/docinfo.html\n     + *.[1-8]\n     + *.made\n     + *.texi\n     +\n       ## Documentation/Makefile ##\n      @@ Documentation/Makefile: ASCIIDOC_DOCBOOK = docbook5\n       ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n\n\n Documentation/.gitignore   | 1 +\n Documentation/Makefile     | 1 +\n Documentation/docinfo.html | 5 +++++\n 3 files changed, 7 insertions(+)\n create mode 100644 Documentation/docinfo.html\n\ndiff --git a/Documentation/.gitignore b/Documentation/.gitignore\nindex a48448de32f..d11567fbbe7 100644\n--- a/Documentation/.gitignore\n+++ b/Documentation/.gitignore\n@@ -1,5 +1,6 @@\n *.xml\n *.html\n+!/docinfo.html\n *.[1-8]\n *.made\n *.texi\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3f2383a12c7..78e407e4bd1 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -202,6 +202,7 @@ ASCIIDOC_DOCBOOK = docbook5\n ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n+ASCIIDOC_EXTRA += -adocinfo=shared\n ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n DBLATEX_COMMON =\n XMLTO_EXTRA += --skip-validation\ndiff --git a/Documentation/docinfo.html b/Documentation/docinfo.html\nnew file mode 100644\nindex 00000000000..fb3560eb92b\n--- /dev/null\n+++ b/Documentation/docinfo.html\n@@ -0,0 +1,5 @@\n+<style>\n+pre>code {\n+   display: inline;\n+}\n+</style>\n\nbase-commit: 76880f0510c6be9f6385f2d43dcfcba4eca9ccbc\n-- \ngitgitgadget\n"},{"id":"499082","messageId":"xmqqplr59mvm.fsf@gitster.g","threadId":"61815","inReplyTo":"pull.1749.v2.git.git.1721679949618.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] asciidoctor: fix `synopsis` rendering","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-22T20:45:33Z","receivedAt":"2024-07-22T20:45:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Johannes Schindelin via GitGitGadget\" <gitgitgadget@gmail.com>\nwrites:\n\n> From: Johannes Schindelin <johannes.schindelin@gmx.de>\n>\n> Since 76880f0510c (doc: git-clone: apply new documentation formatting\n> guidelines, 2024-03-29), the synopsis of `git clone`'s manual page is\n> rendered differently than before; Its parent commit did the same for\n> `git init`.\n> ...\n>  Documentation/.gitignore   | 1 +\n>  Documentation/Makefile     | 1 +\n>  Documentation/docinfo.html | 5 +++++\n>  3 files changed, 7 insertions(+)\n>  create mode 100644 Documentation/docinfo.html\n\nI think our mails crossed.  You need something like this squashed\nin, or \"make distclean\" would make the tree dirty as Ramsay\nreported.\n\n Documentation/Makefile                          | 5 +++++\n Documentation/{docinfo.html => docinfo-html.in} | 0\n 2 files changed, 5 insertions(+)\n rename Documentation/{docinfo.html => docinfo-html.in} (100%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 78e407e4bd..371d56eb5e 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -209,6 +209,8 @@ XMLTO_EXTRA += --skip-validation\n XMLTO_EXTRA += -x manpage.xsl\n endif\n \n+ASCIIDOC_DEPS += docinfo.html\n+\n SHELL_PATH ?= $(SHELL)\n # Shell quote;\n SHELL_PATH_SQ = $(subst ','\\'',$(SHELL_PATH))\n@@ -337,6 +339,9 @@ clean:\n \t$(RM) $(cmds_txt) $(mergetools_txt) *.made\n \t$(RM) GIT-ASCIIDOCFLAGS\n \n+docinfo.html: docinfo-html.in\n+\t$(QUIET_GEN)$(RM) $@ && cat $< >$@\n+\n $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<\n \ndiff --git a/Documentation/docinfo.html b/Documentation/docinfo-html.in\nsimilarity index 100%\nrename from Documentation/docinfo.html\nrename to Documentation/docinfo-html.in\n-- \n2.46.0-rc1-48-g0900f1888e\n\n\n\n"},{"id":"499122","messageId":"xmqqle1s4x7n.fsf@gitster.g","threadId":"61815","inReplyTo":"xmqqplr59mvm.fsf@gitster.g","subject":"Re: [PATCH v2] asciidoctor: fix `synopsis` rendering","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-23T03:13:32Z","receivedAt":"2024-07-23T03:13:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> I think our mails crossed.  You need something like this squashed\n> in, or \"make distclean\" would make the tree dirty as Ramsay\n> reported.\n> ...\n\nAnd I needed to undo the .gitignore change between v1 and v2 to\nmatch (otherwise ci/lib.sh notices that docinfo.html is an\n\"unignored build artifact\" and complains).\n\nAn updated SQUASH??? fixup looks like this.\n\nThanks.\n\n Documentation/.gitignore                        | 1 -\n Documentation/Makefile                          | 5 +++++\n Documentation/{docinfo.html => docinfo-html.in} | 0\n 3 files changed, 5 insertions(+), 1 deletion(-)\n rename Documentation/{docinfo.html => docinfo-html.in} (100%)\n\ndiff --git a/Documentation/.gitignore b/Documentation/.gitignore\nindex d11567fbbe..a48448de32 100644\n--- a/Documentation/.gitignore\n+++ b/Documentation/.gitignore\n@@ -1,6 +1,5 @@\n *.xml\n *.html\n-!/docinfo.html\n *.[1-8]\n *.made\n *.texi\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 78e407e4bd..371d56eb5e 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -209,6 +209,8 @@ XMLTO_EXTRA += --skip-validation\n XMLTO_EXTRA += -x manpage.xsl\n endif\n \n+ASCIIDOC_DEPS += docinfo.html\n+\n SHELL_PATH ?= $(SHELL)\n # Shell quote;\n SHELL_PATH_SQ = $(subst ','\\'',$(SHELL_PATH))\n@@ -337,6 +339,9 @@ clean:\n \t$(RM) $(cmds_txt) $(mergetools_txt) *.made\n \t$(RM) GIT-ASCIIDOCFLAGS\n \n+docinfo.html: docinfo-html.in\n+\t$(QUIET_GEN)$(RM) $@ && cat $< >$@\n+\n $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<\n \ndiff --git a/Documentation/docinfo.html b/Documentation/docinfo-html.in\nsimilarity index 100%\nrename from Documentation/docinfo.html\nrename to Documentation/docinfo-html.in\n-- \n2.46.0-rc1-52-g816ffef0a1\n\n"},{"id":"499162","messageId":"a1d70653-182e-e063-5438-2b3179d011f7@gmx.de","threadId":"61815","inReplyTo":"xmqqplr59mvm.fsf@gitster.g","subject":"Re: [PATCH v2] asciidoctor: fix `synopsis` rendering","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2024-07-23T14:19:00Z","receivedAt":"2024-07-23T14:19:08Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Junio,\n\nOn Mon, 22 Jul 2024, Junio C Hamano wrote:\n\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 78e407e4bd..371d56eb5e 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -209,6 +209,8 @@ XMLTO_EXTRA += --skip-validation\n>  XMLTO_EXTRA += -x manpage.xsl\n>  endif\n>\n> +ASCIIDOC_DEPS += docinfo.html\n> +\n>  SHELL_PATH ?= $(SHELL)\n>  # Shell quote;\n>  SHELL_PATH_SQ = $(subst ','\\'',$(SHELL_PATH))\n> @@ -337,6 +339,9 @@ clean:\n>  \t$(RM) $(cmds_txt) $(mergetools_txt) *.made\n>  \t$(RM) GIT-ASCIIDOCFLAGS\n>\n> +docinfo.html: docinfo-html.in\n> +\t$(QUIET_GEN)$(RM) $@ && cat $< >$@\n> +\n>  $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n>  \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<\n>\n\nHmm. This adds a \"template\" for no other reason than to appease the rule\nthat all `.html` files in `Documentation/` _must_ be generated. Typically,\ntemplates are only added if anything in them needs to be interpolated to\nreflect the particular build, which is not the case here.\n\nHave you considered one of these alternatives?\n\n1. https://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/#customize-extend\n   talks about two ways to extend the default style sheet that do _not_\n   need to add an `.html` file:\n\n   a. add a `.css` file instead that `@import`s AsciiDoctor's default style\n      sheet from a CDN.\n\n      Upside: it is very clean, short, does not need any Makefile rule to\n      generate a file that is arguable in no need of being generated.\n\n      Downside: since the `@import` statement cannot refer to a file in the\n      same directory as the `.css` file, it incurs a web request. This\n      would prevent the build from working on an air-gapped system (such as\n      when on a beautiful island without internet access).\n\n   b. generate a `.css` file by merging AsciiDoctor's default style sheet\n      with a small CSS snippet.\n\n      Upside: it is again very clean.\n\n      Downside: this would now require a Makefile rule when previously we\n      managed without one.\n\n2. simply adjust the `check_unignored_build_artifacts()` function to know\n   about `docinfo.html`.\n\n   Upside: it is still short and does not need any Makefile rule where\n   previously no such thing was required.\n\n   Downside: the simple rule \"all .html files in Documentation/ _must_ be\n   generated\" would no longer hold true, making the architecture slightly\n   harder to explain to newcomers.\n\n3. stop mixing generated and source files in `Documentation/`. Instead,\n   put the HTML files into a subdirectory that is clearly marked as\n   containing only generated files.\n\n   Upside: this would provide an overall cleaner architecture.\n\n   Downside: lots of work, may require some convincing of oldtimers who\n   see nothing wrong with mixing source and generated files.\n\nCiao,\nJohannes\n"},{"id":"499176","messageId":"xmqqr0bk2h5p.fsf@gitster.g","threadId":"61815","inReplyTo":"a1d70653-182e-e063-5438-2b3179d011f7@gmx.de","subject":"Re: [PATCH v2] asciidoctor: fix `synopsis` rendering","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-23T16:43:14Z","receivedAt":"2024-07-23T16:43:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n\n> Hmm. This adds a \"template\" for no other reason than to appease the rule\n> that all `.html` files in `Documentation/` _must_ be generated. Typically,\n> templates are only added if anything in them needs to be interpolated to\n> reflect the particular build, which is not the case here.\n\nConsider that we leave the door open for future enhancements (like,\nlose the conditional compilation and instead make it an empty file\nwhen AsciiDoc and not asciidoctor is in use).\n\n> Have you considered one of these alternatives?\n\nNo, because I am not interested in anything more elaborate a few\ndays before tagging -rc2.  If this is not meant for the upcoming\nrelease, then I am all ears (and eyes), but otherwise, let's just do\nthe simplest and the most obvious thing to unbreak users for the\nupcoming release and leave a more elaborate engineering to next\ncycle.\n\nJean-Noël is planning to undo the overly elaborate mark-up and that\nmay eliminate the need to work around \"<code> in <pre> is made into\na block element\" behaviour of default asciidoctor style in the first\nplace, so the longer term plan should take that into account as well.\n\nThanks.\n"}]}