{"thread":{"id":"59113","subject":"[PATCH] git-cat-file.txt: fix list continuations rendering literally","startedAt":"2023-01-18T09:09:40Z","lastAt":"2023-01-19T16:24:35Z","messageCount":4,"participants":["Martin Ågren","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"470590","messageId":"20230118082749.1252459-1-martin.agren@gmail.com","threadId":"59113","inReplyTo":null,"subject":"[PATCH] git-cat-file.txt: fix list continuations rendering literally","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2023-01-18T08:27:49Z","receivedAt":"2023-01-18T09:09:40Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"With Asciidoctor, all of the '+' introduced in a797c0ea04 (\"cat-file:\nadd mailmap support to --batch-check option\", 2022-12-20) render\nliterally rather than functioning as list continuations. With asciidoc,\nthis renders just fine. It's not too surprising that there is room for\nambiguity and surprises here, since we have lists within lists.\n\nSimply replacing all of these '+' with empty lines makes this render\nfine using both tools. Except, in the third hunk, where after this inner\n'*' list ends, we want to continue with more contents of the outer list\nitem (`--batch-command=`). We can solve any ambiguity here and\nmake this clear to both tools by wrapping the inner list in an open\nblock (using \"--\").\n\nFor consistency, let's wrap all three of these inner lists from\na797c0ea04 in open blocks. This also future-proofs us a little -- if we\never gain more contents after any of those first two lists, as we did\nalready in a797c0ea04 for the third list, we're prepared and should\nrender fine with both asciidoc and Asciidoctor from the start.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-cat-file.txt | 19 ++++++++++++-------\n 1 file changed, 12 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\nindex 830f0a2eff..411de2e27d 100644\n--- a/Documentation/git-cat-file.txt\n+++ b/Documentation/git-cat-file.txt\n@@ -93,47 +93,52 @@ OPTIONS\n \tPrint object information and contents for each object provided\n \ton stdin. May not be combined with any other options or arguments\n \texcept `--textconv`, `--filters`, or `--use-mailmap`.\n-\t+\n++\n+--\n \t* When used with `--textconv` or `--filters`, the input lines\n \t must specify the path, separated by whitespace. See the section\n \t `BATCH OUTPUT` below for details.\n-\t+\n+\n \t* When used with `--use-mailmap`, for commit and tag objects, the\n \t contents part of the output shows the identities replaced using the\n \t mailmap mechanism, while the information part of the output shows\n \t the size of the object as if it actually recorded the replacement\n \t identities.\n+--\n \n --batch-check::\n --batch-check=::\n \tPrint object information for each object provided on stdin. May not be\n \tcombined with any other options or arguments except `--textconv`, `--filters`\n \tor `--use-mailmap`.\n-\t+\n++\n+--\n \t* When used with `--textconv` or `--filters`, the input lines must\n \t specify the path, separated by whitespace. See the section\n \t `BATCH OUTPUT` below for details.\n-\t+\n+\n \t* When used with `--use-mailmap`, for commit and tag objects, the\n \t printed object information shows the size of the object as if the\n \t identities recorded in it were replaced by the mailmap mechanism.\n+--\n \n --batch-command::\n --batch-command=::\n \tEnter a command mode that reads commands and arguments from stdin. May\n \tonly be combined with `--buffer`, `--textconv`, `--use-mailmap` or\n \t`--filters`.\n-\t+\n++\n+--\n \t* When used with `--textconv` or `--filters`, the input lines must\n \t specify the path, separated by whitespace. See the section\n \t `BATCH OUTPUT` below for details.\n-\t+\n+\n \t* When used with `--use-mailmap`, for commit and tag objects, the\n \t `contents` command shows the identities replaced using the\n \t mailmap mechanism, while the `info` command shows the size\n \t of the object as if it actually recorded the replacement\n \t identities.\n-\n+--\n +\n `--batch-command` recognizes the following commands:\n +\n-- \n2.39.0.348.g5efb778ab0\n\n"},{"id":"470641","messageId":"xmqqzgaf4xrf.fsf@gitster.g","threadId":"59113","inReplyTo":"20230118082749.1252459-1-martin.agren@gmail.com","subject":"Re: [PATCH] git-cat-file.txt: fix list continuations rendering literally","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-01-18T16:23:48Z","receivedAt":"2023-01-18T16:26:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> With Asciidoctor, all of the '+' introduced in a797c0ea04 (\"cat-file:\n> add mailmap support to --batch-check option\", 2022-12-20) render\n> literally rather than functioning as list continuations. With asciidoc,\n> this renders just fine.\n\nGood to have somebody who is careful to notice these differences ;-)\n\n> For consistency, let's wrap all three of these inner lists from\n> a797c0ea04 in open blocks. This also future-proofs us a little -- if we\n> ever gain more contents after any of those first two lists, as we did\n> already in a797c0ea04 for the third list, we're prepared and should\n> render fine with both asciidoc and Asciidoctor from the start.\n\nNice.\n\nAre you comparing both roff output and html output, by the way?\n\nThanks.\n"},{"id":"470704","messageId":"CAN0heSokODyuYUEgaU8Ym_Evvmdp_y1-V0LxbsTECgm3sP9d-g@mail.gmail.com","threadId":"59113","inReplyTo":"xmqqzgaf4xrf.fsf@gitster.g","subject":"Re: [PATCH] git-cat-file.txt: fix list continuations rendering literally","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2023-01-19T08:04:26Z","receivedAt":"2023-01-19T08:04:45Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Wed, 18 Jan 2023 at 17:23, Junio C Hamano wrote:\n>\n> Are you comparing both roff output and html output, by the way?\n\nYes, I'm trying to make sure all four of\n\n {asciidoc, asciidoctor} x {man, html}\n\nagree and look good. For the manpages, I use our doc-diff script. (In\nthis case, I wanted an empty asciidoc diff (HEAD^ HEAD) and a good\nAsciidoctor diff (s/+//-ish).) For the html, it's a bit more manual\nlabour, switching between files in a browser and convincing myself\neverything is good, visually.\n\nLuckily, once both tools agree on the manpages and they look good, in my\nexperience, the html is probably also ok.\n\nMartin\n"},{"id":"470711","messageId":"xmqq5yd2332x.fsf@gitster.g","threadId":"59113","inReplyTo":"CAN0heSokODyuYUEgaU8Ym_Evvmdp_y1-V0LxbsTECgm3sP9d-g@mail.gmail.com","subject":"Re: [PATCH] git-cat-file.txt: fix list continuations rendering literally","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-01-19T16:24:06Z","receivedAt":"2023-01-19T16:24:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> On Wed, 18 Jan 2023 at 17:23, Junio C Hamano wrote:\n>>\n>> Are you comparing both roff output and html output, by the way?\n>\n> Yes, I'm trying to make sure all four of\n>\n> {asciidoc, asciidoctor} x {man, html}\n>\n> agree and look good. For the manpages, I use our doc-diff script. (In\n> this case, I wanted an empty asciidoc diff (HEAD^ HEAD) and a good\n> Asciidoctor diff (s/+//-ish).) For the html, it's a bit more manual\n> labour, switching between files in a browser and convincing myself\n> everything is good, visually.\n>\n> Luckily, once both tools agree on the manpages and they look good, in my\n> experience, the html is probably also ok.\n\nWonderful. Thanks for your careful work, as always.\n"}]}