{"thread":{"id":"61814","subject":"[PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor","startedAt":"2024-07-20T17:34:16Z","lastAt":"2024-07-23T18:04:04Z","messageCount":10,"participants":["Jean-Noël Avila via GitGitGadget","Junio C Hamano","Jean-Noël AVILA","Jean-Noël Avila","Eric Sunshine"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"499008","messageId":"pull.1765.git.1721496853517.gitgitgadget@gmail.com","threadId":"61814","inReplyTo":null,"subject":"[PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-07-20T17:34:13Z","receivedAt":"2024-07-20T17:34:16Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nAsciidoc.py does not have the concept of generalized roles, whereas\nasciidoctor interprets [foo]`blah` as blah with role foo in the\nsynopsis, making in effect foo disappear in the output. Note that\nsquare brackets not directly followed by an inline markup do not\ndefine a role, which is why we do not have the issue on other parts of\nthe documentation.\n\nIn order to get a consistant result across asciidoctor and\nasciidoc.py, the hack is to use the {empty} entity\nto split the bracket part from the inline format part.\n\nSigned-off-by: Jean-Noël Avila \n---\n doc: git-clone fix discrepancy between asciidoc and asciidoctor\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1765%2Fjnavila%2Ffix_git_clone_format-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1765/jnavila/fix_git_clone_format-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1765\n\n Documentation/git-clone.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 5de18de2ab8..8e925db7e9c 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -13,9 +13,9 @@ SYNOPSIS\n \t [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]\n \t [`-o` __] [`-b` __] [`-u` __] [`--reference` __]\n \t [`--dissociate`] [`--separate-git-dir` __]\n-\t [`--depth` __] [`--`[`no-`]`single-branch`] [`--no-tags`]\n-\t [++--recurse-submodules++[++=++____]] [`--`[`no-`]`shallow-submodules`]\n-\t [`--`[`no-`]`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]`reject-shallow`]\n+\t [`--depth` __] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]\n+\t [++--recurse-submodules++[++=++____]] [++--++[++no-++]{empty}++shallow-submodules++]\n+\t [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]\n \t [++--filter=++____] [`--also-filter-submodules`]] [`--`] __\n \t [__]\n \n\nbase-commit: a7dae3bdc8b516d36f630b12bb01e853a667e0d9\n-- \ngitgitgadget\n"},{"id":"499020","messageId":"xmqq8qxvhcy5.fsf@gitster.g","threadId":"61814","inReplyTo":"pull.1765.git.1721496853517.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-20T23:16:02Z","receivedAt":"2024-07-20T23:16:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" writes:\n\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n>\n> Asciidoc.py does not have the concept of generalized roles, whereas\n> asciidoctor interprets [foo]`blah` as blah with role foo in the\n> synopsis, making in effect foo disappear in the output. Note that\n> square brackets not directly followed by an inline markup do not\n> define a role, which is why we do not have the issue on other parts of\n> the documentation.\n\nThis was utterly misleading, at least to me, and it took a few times\nof reading for me to really understand what you wanted to say.\n\nIt does not matter that \"generalized roles\" is not known by\nAsciiDoc. What really causes the breakage is that a string inside\n[square brackets] followed by string inside `a pair of back quotes`\nis interpreted by Asciidoctor as \"generalized roles\" (whatever it\nis), even though we do not care at all about such a feature here.\n\nHow about phrasing it more like so?\n\n Writing a string inside [square brackets], immediately followed\n by a string inside `a pair of back quotes`, causes asciidoctor\n to eliminate the string inside [square brackets], because it is\n a syntax to trigger a \"generalized role\" feature, which we do\n not care about in the context of the synopsis section here.\n\n Work it around by inserting an otherwise no-op {empty} string to\n forbid asciidoctor from triggering that feature here. AsciiDoc\n is not affected negatively by this additional empty string.\n\nThe reondered result _might_ be easier to read than pre-2.45 version\nof documentation, but I somehow find the updated SYNOPSIS section\nalmost impossible to work with in the source form. And the need for\nthese otherwise no-op {empty} makes it even less pleasant to work\nwith.\n\nI wonder if there is a magic incantation that says \"everything\nshould be typeset in monospace in this block, unless ...\" so that we\ncan lose all these `back quotes`? And then the part that follows\n\"unless ...\" would say how we mark up the part which\nis the only thing exempt from \"everything is in monospace\" default.\n\nThanks for a quick response.\n\n> Documentation/git-clone.txt | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\n> index 5de18de2ab8..8e925db7e9c 100644\n> --- a/Documentation/git-clone.txt\n> +++ b/Documentation/git-clone.txt\n> @@ -13,9 +13,9 @@ SYNOPSIS\n> \t [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]\n> \t [`-o` __] [`-b` __] [`-u` __] [`--reference` __]\n> \t [`--dissociate`] [`--separate-git-dir` __]\n> -\t [`--depth` __] [`--`[`no-`]`single-branch`] [`--no-tags`]\n> -\t [++--recurse-submodules++[++=++____]] [`--`[`no-`]`shallow-submodules`]\n> -\t [`--`[`no-`]`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]`reject-shallow`]\n> +\t [`--depth` __] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]\n> +\t [++--recurse-submodules++[++=++____]] [++--++[++no-++]{empty}++shallow-submodules++]\n> +\t [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]\n> \t [++--filter=++____] [`--also-filter-submodules`]] [`--`] __\n> \t [__]\n> \n>\n> base-commit: a7dae3bdc8b516d36f630b12bb01e853a667e0d9\n"},{"id":"499021","messageId":"xmqq1q3nhcl2.fsf@gitster.g","threadId":"61814","inReplyTo":"xmqq8qxvhcy5.fsf@gitster.g","subject":"Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-20T23:23:53Z","receivedAt":"2024-07-20T23:23:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> The reondered result _might_ be easier to read than pre-2.45 version\n> of documentation, but I somehow find the updated SYNOPSIS section\n> almost impossible to work with in the source form. And the need for\n> these otherwise no-op {empty} makes it even less pleasant to work\n> with.\n>\n> I wonder if there is a magic incantation that says \"everything\n> should be typeset in monospace in this block, unless ...\" so that we\n> can lose all these `back quotes`? And then the part that follows\n> \"unless ...\" would say how we mark up the part which\n> is the only thing exempt from \"everything is in monospace\" default.\n>\n> Thanks for a quick response.\n>\n>> Documentation/git-clone.txt | 6 +++---\n>> 1 file changed, 3 insertions(+), 3 deletions(-)\n\nAh, another and *more* important thing.\n\nThe original series that added the new mark-up to \"clone\" and \"init\"\nupdated them as examples to illustrate the rules added by c42ea604\n(doc: rework CodingGuidelines with new formatting rules, 2024-03-29)\nto Documentation/CodingGuidelines. I _dislike_ the idea that we\nhave to sprinkle otherwise no-op {empty} all over the place, if we\nwere to update the SYNOPSIS part of all other commands consistently,\nbut if that is what it takes, we _should_ document that they need to\ndo so (and no, we should not assume that those who document the\ncommands _know_ why asciidoctor wants to eat the [string] there and\nwe should not expect them to insert {empty} without being told).\n\nThanks.\n\n\n\n>>\n>> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\n>> index 5de18de2ab8..8e925db7e9c 100644\n>> --- a/Documentation/git-clone.txt\n>> +++ b/Documentation/git-clone.txt\n>> @@ -13,9 +13,9 @@ SYNOPSIS\n>> \t [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]\n>> \t [`-o` __] [`-b` __] [`-u` __] [`--reference` __]\n>> \t [`--dissociate`] [`--separate-git-dir` __]\n>> -\t [`--depth` __] [`--`[`no-`]`single-branch`] [`--no-tags`]\n>> -\t [++--recurse-submodules++[++=++____]] [`--`[`no-`]`shallow-submodules`]\n>> -\t [`--`[`no-`]`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]`reject-shallow`]\n>> +\t [`--depth` __] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]\n>> +\t [++--recurse-submodules++[++=++____]] [++--++[++no-++]{empty}++shallow-submodules++]\n>> +\t [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]\n>> \t [++--filter=++____] [`--also-filter-submodules`]] [`--`] __\n>> \t [__]\n>> \n>>\n>> base-commit: a7dae3bdc8b516d36f630b12bb01e853a667e0d9\n"},{"id":"499031","messageId":"8404759.T7Z3S40VBb@cayenne","threadId":"61814","inReplyTo":"xmqq8qxvhcy5.fsf@gitster.g","subject":"Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-07-21T13:08:46Z","receivedAt":"2024-07-21T13:16:35Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le dimanche 21 juillet 2024, 01:16:02 CEST Junio C Hamano a écrit :\n> \"Jean-Noël Avila via GitGitGadget\" writes:\n> \n> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n> >\n> > Asciidoc.py does not have the concept of generalized roles, whereas\n> > asciidoctor interprets [foo]`blah` as blah with role foo in the\n> > synopsis, making in effect foo disappear in the output. Note that\n> > square brackets not directly followed by an inline markup do not\n> > define a role, which is why we do not have the issue on other parts of\n> > the documentation.\n> \n> This was utterly misleading, at least to me, and it took a few times\n> of reading for me to really understand what you wanted to say.\n> \n> It does not matter that \"generalized roles\" is not known by\n> AsciiDoc. What really causes the breakage is that a string inside\n> [square brackets] followed by string inside `a pair of back quotes`\n> is interpreted by Asciidoctor as \"generalized roles\" (whatever it\n> is), even though we do not care at all about such a feature here.\n>\n\nSorry for not being clear. Indeed I was wrong, Asciidoc.py also has this role \nmanagement behavior for any other inline markup (++, _, *, ^, ~) except for \nback-quoted text.\n \n> How about phrasing it more like so?\n> \n> Writing a string inside [square brackets], immediately followed\n> by a string inside `a pair of back quotes`, causes asciidoctor\n> to eliminate the string inside [square brackets], because it is\n> a syntax to trigger a \"generalized role\" feature, which we do\n> not care about in the context of the synopsis section here.\n> \n> Work it around by inserting an otherwise no-op {empty} string to\n> forbid asciidoctor from triggering that feature here. AsciiDoc\n> is not affected negatively by this additional empty string.\n> \n\nOK, but let's get rid of the \"generalized role\" stuff, then. \n\n> The reondered result _might_ be easier to read than pre-2.45 version\n> of documentation, but I somehow find the updated SYNOPSIS section\n> almost impossible to work with in the source form. And the need for\n> these otherwise no-op {empty} makes it even less pleasant to work\n> with.\n\nI can only agree. The fact that this \"feature\" is too easily triggered almost \nvoids all the \"painless technical doc editing for the rest of us\" argument \nthat is the main selling point of Asciidoc, Markdown and other lightweight \nmarkup systems.\n\n> \n> I wonder if there is a magic incantation that says \"everything\n> should be typeset in monospace in this block, unless ...\" so that we\n> can lose all these `back quotes`? And then the part that follows\n> \"unless ...\" would say how we mark up the part which\n> is the only thing exempt from \"everything is in monospace\" default.\n\nWhile doing the styling of synopsis, I tried to be smarter than that. There \nare basically 3 semantic entities in the grammar:\n\n * the __ in italic\n * the `keywords`, in monospace\n * the grammar signs: [, ], |, ..., (, ), etc. These signs are not typeset.\n\nSetting everything in monospace would mix keywords and grammar.\n\nWith this schema in mind, I don't find difficult to understand how the synopsis \nis written (putting aside the {empty} hack). Fair enough, this is more \ndifficult than just plain text, but the aim is still to get decent output.\n\n\n\n"},{"id":"499063","messageId":"xmqqplr5e5yk.fsf@gitster.g","threadId":"61814","inReplyTo":"8404759.T7Z3S40VBb@cayenne","subject":"Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-22T16:39:47Z","receivedAt":"2024-07-22T16:39:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël AVILA writes:\n\n> Sorry for not being clear. Indeed I was wrong, Asciidoc.py also has this role \n> management behavior for any other inline markup (++, _, *, ^, ~) except for \n> back-quoted text.\n> \n>> How about phrasing it more like so?\n>> \n>> Writing a string inside [square brackets], immediately followed\n>> by a string inside `a pair of back quotes`, causes asciidoctor\n>> to eliminate the string inside [square brackets], because it is\n>> a syntax to trigger a \"generalized role\" feature, which we do\n>> not care about in the context of the synopsis section here.\n>> \n>> Work it around by inserting an otherwise no-op {empty} string to\n>> forbid asciidoctor from triggering that feature here. AsciiDoc\n>> is not affected negatively by this additional empty string.\n>> \n>\n> OK, but let's get rid of the \"generalized role\" stuff, then. \n\nI agree it is not relevant what the feature is called, as that is\nsomething we did not want to trigger and take advantage of.\n\nIt still is necessary to mention the fact that [strings] are eaten\nby us unknowingly triggering the feature. \n\n> While doing the styling of synopsis, I tried to be smarter than that. There \n> are basically 3 semantic entities in the grammar:\n>\n> * the __ in italic\n> * the `keywords`, in monospace\n> * the grammar signs: [, ], |, ..., (, ), etc. These signs are not typeset.\n>\n> Setting everything in monospace would mix keywords and grammar.\n>\n> With this schema in mind, I don't find difficult to understand how the synopsis \n> is written (putting aside the {empty} hack). Fair enough, this is more \n> difficult than just plain text, but the aim is still to get decent output.\n\nThanks.\n\nIt appears that asciidoctor considers `monospaced` that results in\n... is a bad match in the SYNOPSIS section\n\n cf. https://lore.kernel.org/git/xmqqsew3hdmv.fsf@gitster.g/\n\nbut we should be able to sort it out.\n\n"},{"id":"499145","messageId":"89d00235-71db-4087-8ffb-7e93c3f470a0@free.fr","threadId":"61814","inReplyTo":"xmqqplr5e5yk.fsf@gitster.g","subject":"Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2024-07-23T11:06:06Z","receivedAt":"2024-07-23T11:06:12Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 22/07/2024 à 18:39, Junio C Hamano a écrit :\n> Jean-Noël AVILA writes:\n> \n>> Sorry for not being clear. Indeed I was wrong, Asciidoc.py also has this role \n>> management behavior for any other inline markup (++, _, *, ^, ~) except for \n>> back-quoted text.\n>> \n>>> How about phrasing it more like so?\n>>>\n>>> Writing a string inside [square brackets], immediately followed\n>>> by a string inside `a pair of back quotes`, causes asciidoctor\n>>> to eliminate the string inside [square brackets], because it is\n>>> a syntax to trigger a \"generalized role\" feature, which we do\n>>> not care about in the context of the synopsis section here.\n>>>\n>>> Work it around by inserting an otherwise no-op {empty} string to\n>>> forbid asciidoctor from triggering that feature here. AsciiDoc\n>>> is not affected negatively by this additional empty string.\n>>>\n>>\n>> OK, but let's get rid of the \"generalized role\" stuff, then. \n> \n> I agree it is not relevant what the feature is called, as that is\n> something we did not want to trigger and take advantage of.\n> \n> It still is necessary to mention the fact that [strings] are eaten\n> by us unknowingly triggering the feature. \n> \n>> While doing the styling of synopsis, I tried to be smarter than that. There \n>> are basically 3 semantic entities in the grammar:\n>>\n>> * the __ in italic\n>> * the `keywords`, in monospace\n>> * the grammar signs: [, ], |, ..., (, ), etc. These signs are not typeset.\n>>\n>> Setting everything in monospace would mix keywords and grammar.\n>>\n>> With this schema in mind, I don't find difficult to understand how the synopsis \n>> is written (putting aside the {empty} hack). Fair enough, this is more \n>> difficult than just plain text, but the aim is still to get decent output.\n> \n> Thanks.\n> \n> It appears that asciidoctor considers `monospaced` that results in\n> ... is a bad match in the SYNOPSIS section\n> \n> cf. https://lore.kernel.org/git/xmqqsew3hdmv.fsf@gitster.g/\n> \n> but we should be able to sort it out.\n> \n\n\nPlease hold on this patch. Cranking on your reflections about the ugly\nmarkup and upon advice from Dan Allen (of asciidoctor) [1], I'd like to\npush another way of managing the files, which would be to define a\ncustom 'synopsis' paragraph style which would allow to process\nautomatically the grammar.\n\nThanks\n\n[1]\nhttps://asciidoctor.zulipchat.com/#narrow/stream/279642-users/topic/Is.20there.20a.20way.20to.20disable.20role.20attributes.3F\n"},{"id":"499174","messageId":"xmqqv80w2ji8.fsf@gitster.g","threadId":"61814","inReplyTo":"89d00235-71db-4087-8ffb-7e93c3f470a0@free.fr","subject":"Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-23T15:52:31Z","receivedAt":"2024-07-23T15:52:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël Avila writes:\n\n> Please hold on this patch. Cranking on your reflections about the ugly\n> markup and upon advice from Dan Allen (of asciidoctor) [1], I'd like to\n> push another way of managing the files, which would be to define a\n> custom 'synopsis' paragraph style which would allow to process\n> automatically the grammar.\n\nSounds good. Anything that lets documenters write what they mean\nwithout involving an absolute nightmare of a markup sequence is what\nwe want here.\n\nBut I'd like to see such a larger scale work early in the next\ncycle, not close to the end of this cycle a few days before -rc2.\n\nIn the meantime, I am tempted to\n\n (1) apply Dscho's CSS change (but with fixes to avoid \"make\n distclean\" issue) and leaving git-clone as-is. or\n\n (2) revert the git-clone and git-init mark-up patches (76880f05\n (doc: git-clone: apply new documentation formatting guidelines,\n 2024-03-29) and (5cf7dfe9 (doc: git-init: apply new\n documentation formatting guidelines, 2024-03-29), which suffers\n from the being blocks. This will allow us not to worry\n about CSS change proposed by Dscho this close to the final. or\n\n (3) do nothing.\n\nI'd probably do (1). Even though chances of unintended regression\nmight be smaller with (2), which would only affect clone and init\nmanual pages (as opposed to anything that uses inside 
),\nit's less work (and more work to validate the result visually, which\nmay be a pain).\n\n> [1]\n> https://asciidoctor.zulipchat.com/#narrow/stream/279642-users/topic/Is.20there.20a.20way.20to.20disable.20role.20attributes.3F\n\nI've always felt [verse] was a bad choice (I honestly do not know\nwhere its use came from), and I am glad to finally find somebody\nagreeing ;-)\n\n\nThanks.\n"},{"id":"499181","messageId":"xmqqv80w0zrx.fsf@gitster.g","threadId":"61814","inReplyTo":"xmqqv80w2ji8.fsf@gitster.g","subject":"Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-23T17:44:02Z","receivedAt":"2024-07-23T17:44:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano  writes:\n\n> In the meantime, I am tempted to\n>\n>  (1) apply Dscho's CSS change (but with fixes to avoid \"make\n>      distclean\" issue) and leaving git-clone as-is.  or\n> ...\n> I'd probably do (1).  Even though chances of unintended regression\n> might be smaller with (2), which would only affect clone and init\n> manual pages (as opposed to anything that uses  inside 
),\n> it's less work (and more work to validate the result visually, which\n> may be a pain).\n\nSo, I decided to keep Dscho's latest CSS-workaround change intact,\nand queued a stupid and obvious workaround clearly marked as a\ntentative measure on top of it.  I am planning to merge these two\npatches down for the release candidates.\n\nWithout your incremental update to git-clone.txt, git-clone.html\nrendered through asciidoctor will say wrong things, so we'd need\nto apply it anyway.  So I cannot put your patch _on_ _hold_ for\nthe purpose of the upcoming release, if we wanted to ship a set of\nsource that produces correct version of git-clone.html.\n\nSo in the end, we'd need both ;-).\n\nThanks, both.\n\n----- >8 ---------- >8 ---------- >8 ---------- >8 -----\nSubject: [PATCH] Doc: fix Asciidoctor css workaround\n\nThe previous step introduced docinfo.html to be used to tweak the\nCSS used by the asciidoctor, that by default renders  inside\n
 as a block element, breaking the SYNOPSIS section of a few\npages that adopted a new convention we use since Git 2.45.\n\nBut in this project, HTML files are all generated.  We do not force\nany human to write HTML by hand, which is an unusual and cruel\npunishment.  \"*.html\" is in the .gitignore file, and \"make clean\"\nremoves them.  Having a tracked .html file makes \"make clean\" make\nthe tree dirty by removing the tracked docinfo.html file.\n\nLet's do an obvious, minimum and stupid workaround to generate that\nfile at runtime instead.  The mark-up is being rethought in a major\nway for the next development cycle, so what the CSS workaround we\nadded in the previous step may have to adjusted, possibly in a large\nway, anyway.\n\nSigned-off-by: Junio C Hamano \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-gda884b23f2\n\n\n"},{"id":"499182","messageId":"CAPig+cQK17Xt6p7PSO4Mn1CLx_ayceQdj8ZY1zBVG6-c33OvsQ@mail.gmail.com","threadId":"61814","inReplyTo":"xmqqv80w0zrx.fsf@gitster.g","subject":"Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2024-07-23T17:47:47Z","receivedAt":"2024-07-23T17:47:59Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Tue, Jul 23, 2024 at 1:44 PM Junio C Hamano  wrote:\n> Subject: [PATCH] Doc: fix Asciidoctor css workaround\n>\n> The previous step introduced docinfo.html to be used to tweak the\n> CSS used by the asciidoctor, that by default renders  inside\n> 
 as a block element, breaking the SYNOPSIS section of a few\n> pages that adopted a new convention we use since Git 2.45.\n>\n> But in this project, HTML files are all generated.  We do not force\n> any human to write HTML by hand, which is an unusual and cruel\n> punishment.  \"*.html\" is in the .gitignore file, and \"make clean\"\n> removes them.  Having a tracked .html file makes \"make clean\" make\n> the tree dirty by removing the tracked docinfo.html file.\n>\n> Let's do an obvious, minimum and stupid workaround to generate that\n> file at runtime instead.  The mark-up is being rethought in a major\n> way for the next development cycle, so what the CSS workaround we\n\nPerhaps? s/what/that/\n\n> added in the previous step may have to adjusted, possibly in a large\n> way, anyway.\n>\n> Signed-off-by: Junio C Hamano \n"},{"id":"499183","messageId":"xmqqr0bk0yun.fsf@gitster.g","threadId":"61814","inReplyTo":"CAPig+cQK17Xt6p7PSO4Mn1CLx_ayceQdj8ZY1zBVG6-c33OvsQ@mail.gmail.com","subject":"Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-23T18:04:00Z","receivedAt":"2024-07-23T18:04:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine  writes:\n\n> On Tue, Jul 23, 2024 at 1:44 PM Junio C Hamano  wrote:\n>> Subject: [PATCH] Doc: fix Asciidoctor css workaround\n>>\n>> The previous step introduced docinfo.html to be used to tweak the\n>> CSS used by the asciidoctor, that by default renders  inside\n>> 
 as a block element, breaking the SYNOPSIS section of a few\n>> pages that adopted a new convention we use since Git 2.45.\n>>\n>> But in this project, HTML files are all generated.  We do not force\n>> any human to write HTML by hand, which is an unusual and cruel\n>> punishment.  \"*.html\" is in the .gitignore file, and \"make clean\"\n>> removes them.  Having a tracked .html file makes \"make clean\" make\n>> the tree dirty by removing the tracked docinfo.html file.\n>>\n>> Let's do an obvious, minimum and stupid workaround to generate that\n>> file at runtime instead.  The mark-up is being rethought in a major\n>> way for the next development cycle, so what the CSS workaround we\n>\n> Perhaps? s/what/that/\n\nThanks, I ended up doing \"so what\" -> \"and\".\n\n>> added in the previous step may have to adjusted, possibly in a large\n>> way, anyway.\n>>\n>> Signed-off-by: Junio C Hamano \n"}]}