{"thread":{"id":"50043","subject":"[PATCH 0/4] A few Asciidoctor-fixes","startedAt":"2018-12-15T11:28:04Z","lastAt":"2018-12-16T16:19:22Z","messageCount":18,"participants":["Martin Ågren","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"365427","messageId":"20181215112742.1475882-1-martin.agren@gmail.com","threadId":"50043","inReplyTo":null,"subject":"[PATCH 0/4] A few Asciidoctor-fixes","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-12-15T11:27:38Z","receivedAt":"2018-12-15T11:28:04Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"I have (ab)used doc-diff to try to find instances where Asciidoctor and\nAsciidoc render our documentation differently. (See [1] for details on\nthe hack.) This series fixes the differences that somehow stood out in\nthe diff. Many smaller differences remain.\n\nWith each patch, I am giving one or a few URLs which show the current\nAsciidoctor rendering at git-scm.com.\n\nWith Asciidoc, `doc-diff origin/master HEAD` reports that there is no\ndifference.\n\n[1] https://public-inbox.org/git/CAN0heSob+Ac4BvM-vuKvPZKxrTW53-d91a55NX5kC7ZyNXntWQ@mail.gmail.com/\n\nMartin Ågren (4):\n git-column.txt: fix section header\n git-init.txt: do not nest open blocks\n rev-list-options.txt: do not nest open blocks\n git-status.txt: render tables correctly under Asciidoctor\n\n Documentation/git-column.txt | 2 +-\n Documentation/git-init.txt | 4 -\n Documentation/git-status.txt | 162 +++++++++++++++--------------\n Documentation/rev-list-options.txt | 4 -\n 4 files changed, 86 insertions(+), 86 deletions(-)\n\n-- \n2.20.1\n\n"},{"id":"365428","messageId":"20181215112742.1475882-2-martin.agren@gmail.com","threadId":"50043","inReplyTo":"20181215112742.1475882-1-martin.agren@gmail.com","subject":"[PATCH 1/4] git-column.txt: fix section header","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-12-15T11:27:39Z","receivedAt":"2018-12-15T11:28:05Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"We have too few dashes under \"Examples\", which causes Asciidoctor to not\npick it up as a section header, but to instead just render the dashes\nliterally. This also seems to confuse Asciidoctor about dashes in\ngeneral around here. It misinterprets the listing blocks in this\nsection, again rendering the dashes literally.\n\nMake sure we have as many dashes as we have characters in \"Examples\".\nThis fixes the section-issue and, somehow, makes the listing blocks\nrender correctly.\n\nAsciidoc renders identically before and after this patch, both man-page\nand html.\n\nSigned-off-by: Martin Ågren \n---\n See https://git-scm.com/docs/git-column\n\n Documentation/git-column.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-column.txt b/Documentation/git-column.txt\nindex 763afabb6d..f58e9c43e6 100644\n--- a/Documentation/git-column.txt\n+++ b/Documentation/git-column.txt\n@@ -47,7 +47,7 @@ OPTIONS\n \tThe number of spaces between columns. One space by default.\n \n EXAMPLES\n-------\n+--------\n \n Format data by columns:\n ------------\n-- \n2.20.1\n\n"},{"id":"365429","messageId":"20181215112742.1475882-3-martin.agren@gmail.com","threadId":"50043","inReplyTo":"20181215112742.1475882-1-martin.agren@gmail.com","subject":"[PATCH 2/4] git-init.txt: do not nest open blocks","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-12-15T11:27:40Z","receivedAt":"2018-12-15T11:28:12Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"It appears we try to nest open blocks, but that does not work well with\nAsciidoctor, which fails to indent the inner block. This causes the\ninner block to be set as if it had nothing to do with `--shared`. Drop\nthe outer one. Asciidoc renders identically before and after this patch,\nboth man-page and html.\n\nSigned-off-by: Martin Ågren \n---\n See https://git-scm.com/docs/git-init#git-init---sharedfalsetrueumaskgroupallworldeverybody0xxx\n\n Documentation/git-init.txt | 4 ----\n 1 file changed, 4 deletions(-)\n\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex 3c5a67fb96..057076ca38 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -38,8 +38,6 @@ the repository to another place if --separate-git-dir is given).\n OPTIONS\n -------\n \n---\n-\n -q::\n --quiet::\n \n@@ -111,8 +109,6 @@ into it.\n If you provide a 'directory', the command is run inside it. If this directory\n does not exist, it will be created.\n \n---\n-\n TEMPLATE DIRECTORY\n ------------------\n \n-- \n2.20.1\n\n"},{"id":"365430","messageId":"20181215112742.1475882-4-martin.agren@gmail.com","threadId":"50043","inReplyTo":"20181215112742.1475882-1-martin.agren@gmail.com","subject":"[PATCH 3/4] rev-list-options.txt: do not nest open blocks","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-12-15T11:27:41Z","receivedAt":"2018-12-15T11:28:13Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Similar to the previous commit, it appears we try to nest open blocks,\nwhich does not work well with Asciidoctor. Drop the outer one. That\nfixes the indentation similar to the previous patch, and makes us stop\nrendering a literal '+' before \"Under --pretty=oneline ...\". Asciidoc\nrenders identically before and after this patch, both man-page and html.\n\nSigned-off-by: Martin Ågren \n---\n See https://git-scm.com/docs/git-log#git-log--g and\n https://git-scm.com/docs/git-rev-list#git-rev-list--g . The indentation\n doesn't look too bad, but the \"+ Under\" is clearly wrong.\n\n Documentation/rev-list-options.txt | 4 ----\n 1 file changed, 4 deletions(-)\n\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex bab5f50b17..98b538bc77 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -13,8 +13,6 @@ has a line that matches ``), unless otherwise noted.\n Note that these are applied before commit\n ordering and formatting options, such as `--reverse`.\n \n---\n-\n -::\n -n ::\n --max-count=::\n@@ -308,8 +306,6 @@ ifdef::git-rev-list[]\n \t`
` text will be printed with each progress update.\n endif::git-rev-list[]\n \n---\n-\n History Simplification\n ~~~~~~~~~~~~~~~~~~~~~~\n \n-- \n2.20.1\n\n"},{"id":"365431","messageId":"20181215112742.1475882-5-martin.agren@gmail.com","threadId":"50043","inReplyTo":"20181215112742.1475882-1-martin.agren@gmail.com","subject":"[PATCH 4/4] git-status.txt: render tables correctly under Asciidoctor","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-12-15T11:27:42Z","receivedAt":"2018-12-15T11:28:13Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Asciidoctor removes the indentation of each line in these tables, so the\nlast lines of each table have a completely broken alignment.\n\nSimilar to 379805051d (\"Documentation: render revisions correctly under\nAsciidoctor\", 2018-05-06), use an explicit literal block to indicate\nthat we want to keep the leading whitespace in the tables.\n\nBecause this gives us some extra indentation, we can remove the one that\nwe have been carrying explicitly. That is, drop the first four spaces of\nindentation on each line. With Asciidoc (8.6.10), this results in\nidentical rendering before and after this commit, both for git-status.1\nand git-status.html.\n\nSigned-off-by: Martin Ågren \n---\n See https://git-scm.com/docs/git-status#_short_format ,\n https://git-scm.com/docs/git-status#_branch_headers and\n https://git-scm.com/docs/git-status#_changed_tracked_entries .\n\n Documentation/git-status.txt | 162 ++++++++++++++++++-----------------\n 1 file changed, 85 insertions(+), 77 deletions(-)\n\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex d9f422d560..861d821d7f 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -197,31 +197,33 @@ codes can be interpreted as follows:\n Ignored files are not listed, unless `--ignored` option is in effect,\n in which case `XY` are `!!`.\n \n- X Y Meaning\n- -------------------------------------------------\n-\t [AMD] not updated\n- M [ MD] updated in index\n- A [ MD] added to index\n- D deleted from index\n- R [ MD] renamed in index\n- C [ MD] copied in index\n- [MARC] index and work tree matches\n- [ MARC] M work tree changed since index\n- [ MARC] D deleted in work tree\n- [ D] R renamed in work tree\n- [ D] C copied in work tree\n- -------------------------------------------------\n- D D unmerged, both deleted\n- A U unmerged, added by us\n- U D unmerged, deleted by them\n- U A unmerged, added by them\n- D U unmerged, deleted by us\n- A A unmerged, both added\n- U U unmerged, both modified\n- -------------------------------------------------\n- ? ? untracked\n- ! ! ignored\n- -------------------------------------------------\n+....\n+X Y Meaning\n+-------------------------------------------------\n+\t [AMD] not updated\n+M [ MD] updated in index\n+A [ MD] added to index\n+D deleted from index\n+R [ MD] renamed in index\n+C [ MD] copied in index\n+[MARC] index and work tree matches\n+[ MARC] M work tree changed since index\n+[ MARC] D deleted in work tree\n+[ D] R renamed in work tree\n+[ D] C copied in work tree\n+-------------------------------------------------\n+D D unmerged, both deleted\n+A U unmerged, added by us\n+U D unmerged, deleted by them\n+U A unmerged, added by them\n+D U unmerged, deleted by us\n+A A unmerged, both added\n+U U unmerged, both modified\n+-------------------------------------------------\n+? ? untracked\n+! ! ignored\n+-------------------------------------------------\n+....\n \n Submodules have more state and instead report\n \t\tM the submodule has a different HEAD than\n@@ -281,14 +283,16 @@ don't recognize.\n If `--branch` is given, a series of header lines are printed with\n information about the current branch.\n \n- Line Notes\n- ------------------------------------------------------------\n- # branch.oid | (initial) Current commit.\n- # branch.head | (detached) Current branch.\n- # branch.upstream If upstream is set.\n- # branch.ab + - If upstream is set and\n-\t\t\t\t\t the commit is present.\n- ------------------------------------------------------------\n+....\n+Line Notes\n+------------------------------------------------------------\n+# branch.oid | (initial) Current commit.\n+# branch.head | (detached) Current branch.\n+# branch.upstream If upstream is set.\n+# branch.ab + - If upstream is set and\n+\t\t\t\t\t the commit is present.\n+------------------------------------------------------------\n+....\n \n ### Changed Tracked Entries\n \n@@ -306,56 +310,60 @@ Renamed or copied entries have the following format:\n \n 2 \n \n- Field Meaning\n- --------------------------------------------------------\n- A 2 character field containing the staged and\n-\t\tunstaged XY values described in the short format,\n-\t\twith unchanged indicated by a \".\" rather than\n-\t\ta space.\n- A 4 character field describing the submodule state.\n-\t\t\"N...\" when the entry is not a submodule.\n-\t\t\"S\" when the entry is a submodule.\n-\t\t is \"C\" if the commit changed; otherwise \".\".\n-\t\t is \"M\" if it has tracked changes; otherwise \".\".\n-\t\t is \"U\" if there are untracked changes; otherwise \".\".\n- The octal file mode in HEAD.\n- The octal file mode in the index.\n- The octal file mode in the worktree.\n- The object name in HEAD.\n- The object name in the index.\n- The rename or copy score (denoting the percentage\n-\t\tof similarity between the source and target of the\n-\t\tmove or copy). For example \"R100\" or \"C75\".\n- The pathname. In a renamed/copied entry, this\n-\t\tis the target path.\n- When the `-z` option is used, the 2 pathnames are separated\n-\t\twith a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)\n-\t\tbyte separates them.\n- The pathname in the commit at HEAD or in the index.\n-\t\tThis is only present in a renamed/copied entry, and\n-\t\ttells where the renamed/copied contents came from.\n- --------------------------------------------------------\n+....\n+Field Meaning\n+--------------------------------------------------------\n+ A 2 character field containing the staged and\n+\t unstaged XY values described in the short format,\n+\t with unchanged indicated by a \".\" rather than\n+\t a space.\n+ A 4 character field describing the submodule state.\n+\t \"N...\" when the entry is not a submodule.\n+\t \"S\" when the entry is a submodule.\n+\t is \"C\" if the commit changed; otherwise \".\".\n+\t is \"M\" if it has tracked changes; otherwise \".\".\n+\t is \"U\" if there are untracked changes; otherwise \".\".\n+ The octal file mode in HEAD.\n+ The octal file mode in the index.\n+ The octal file mode in the worktree.\n+ The object name in HEAD.\n+ The object name in the index.\n+ The rename or copy score (denoting the percentage\n+\t of similarity between the source and target of the\n+\t move or copy). For example \"R100\" or \"C75\".\n+ The pathname. In a renamed/copied entry, this\n+\t is the target path.\n+ When the `-z` option is used, the 2 pathnames are separated\n+\t with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)\n+\t byte separates them.\n+ The pathname in the commit at HEAD or in the index.\n+\t This is only present in a renamed/copied entry, and\n+\t tells where the renamed/copied contents came from.\n+--------------------------------------------------------\n+....\n \n Unmerged entries have the following format; the first character is\n a \"u\" to distinguish from ordinary changed entries.\n \n u

\n \n- Field Meaning\n- --------------------------------------------------------\n- A 2 character field describing the conflict type\n-\t\tas described in the short format.\n- A 4 character field describing the submodule state\n-\t\tas described above.\n- The octal file mode in stage 1.\n- The octal file mode in stage 2.\n- The octal file mode in stage 3.\n- The octal file mode in the worktree.\n-

The object name in stage 1.\n-

The object name in stage 2.\n-

The object name in stage 3.\n- The pathname.\n- --------------------------------------------------------\n+....\n+Field Meaning\n+--------------------------------------------------------\n+ A 2 character field describing the conflict type\n+\t as described in the short format.\n+ A 4 character field describing the submodule state\n+\t as described above.\n+ The octal file mode in stage 1.\n+ The octal file mode in stage 2.\n+ The octal file mode in stage 3.\n+ The octal file mode in the worktree.\n+

The object name in stage 1.\n+

The object name in stage 2.\n+

The object name in stage 3.\n+ The pathname.\n+--------------------------------------------------------\n+....\n \n ### Other Items\n \n-- \n2.20.1\n\n"},{"id":"365444","messageId":"20181216104458.GC13704@sigill.intra.peff.net","threadId":"50043","inReplyTo":"20181215112742.1475882-1-martin.agren@gmail.com","subject":"Re: [PATCH 0/4] A few Asciidoctor-fixes","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-12-16T10:44:58Z","receivedAt":"2018-12-16T10:45:01Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Dec 15, 2018 at 12:27:38PM +0100, Martin Ågren wrote:\n\n> I have (ab)used doc-diff to try to find instances where Asciidoctor and\n> Asciidoc render our documentation differently. (See [1] for details on\n> the hack.) This series fixes the differences that somehow stood out in\n> the diff. Many smaller differences remain.\n\nI think the relevant bits from [1] are:\n\n * Use `make --always-make ... install-man` in doc-diff.\n * ./doc-diff -f HEAD HEAD # note -f\n * Add empty commit and tweak config.mak\n * ./doc-diff HEAD^ HEAD # note no -f\n\nTo make this easier, it would make sense to me to:\n\n - teach doc-diff a flag for marking one or both of the endpoints to be\n built with asciidoctor versus asciidoc\n\n - mark the asciidoc/asciidoctor in the directory name. That name\n serves as a cache key for avoiding re-doing the work, you should be\n able to just:\n\n ./doc-diff --asciidoctor HEAD HEAD\n\n and actually build and compare what you want.\n\n - it sounds from \"make --always-make\" that our Makefile does not\n properly rebuild when we switch from asciidoc to asciidoctor. That\n might be nice to fix with a mechanism similar to the GIT-BUILD-FLAGS\n we use in the top-level Makefile.\n\n-Peff\n"},{"id":"365445","messageId":"20181216105123.GD13704@sigill.intra.peff.net","threadId":"50043","inReplyTo":"20181215112742.1475882-2-martin.agren@gmail.com","subject":"Re: [PATCH 1/4] git-column.txt: fix section header","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-12-16T10:51:24Z","receivedAt":"2018-12-16T10:51:27Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Dec 15, 2018 at 12:27:39PM +0100, Martin Ågren wrote:\n\n> We have too few dashes under \"Examples\", which causes Asciidoctor to not\n> pick it up as a section header, but to instead just render the dashes\n> literally. This also seems to confuse Asciidoctor about dashes in\n> general around here. It misinterprets the listing blocks in this\n> section, again rendering the dashes literally.\n> \n> Make sure we have as many dashes as we have characters in \"Examples\".\n> This fixes the section-issue and, somehow, makes the listing blocks\n> render correctly.\n\nYeah, the mis-matched title-and-dashes thing has bitten us several\ntimes. I think this one just post-dates the last round of fixing.\n\nThe \"somehow\" here is that the mismatched dashes appear to be the start\nof a code listing block, making the whole example section into one big\nlisting (which isn't properly closed, generating a warning).\n\nAnd that's why in the context:\n\n> EXAMPLES\n> -------\n> +--------\n> \n> Format data by columns:\n> ------------\n\nWe _don't_ need to match up the dashes for \"Format data...\". That is\nmeant to be a listing block (and arguably should use a shorter string of\ndashes to make that intent more obvious).\n\n-Peff\n"},{"id":"365446","messageId":"20181216105505.GE13704@sigill.intra.peff.net","threadId":"50043","inReplyTo":"20181215112742.1475882-3-martin.agren@gmail.com","subject":"Re: [PATCH 2/4] git-init.txt: do not nest open blocks","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-12-16T10:55:05Z","receivedAt":"2018-12-16T10:55:08Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Dec 15, 2018 at 12:27:40PM +0100, Martin Ågren wrote:\n\n> It appears we try to nest open blocks, but that does not work well with\n> Asciidoctor, which fails to indent the inner block. This causes the\n> inner block to be set as if it had nothing to do with `--shared`. Drop\n> the outer one. Asciidoc renders identically before and after this patch,\n> both man-page and html.\n\nHrm. I'm not sure how we're supposed to have a block-within-a-block in\nasciidoctor, and that may be something we want to fix in the long run.\nBut I agree this block around all of the options is not doing anything\nuseful, and the simplest solution here is just to get rid of it.\n\nIt dates all the way back to d145144c3b (Document git-init, 2007-01-11),\nso perhaps it did something useful in an ancient version of asciidoc.\n\n-Peff\n"},{"id":"365447","messageId":"20181216105601.GF13704@sigill.intra.peff.net","threadId":"50043","inReplyTo":"20181215112742.1475882-4-martin.agren@gmail.com","subject":"Re: [PATCH 3/4] rev-list-options.txt: do not nest open blocks","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-12-16T10:56:01Z","receivedAt":"2018-12-16T10:56:04Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Dec 15, 2018 at 12:27:41PM +0100, Martin Ågren wrote:\n\n> Similar to the previous commit, it appears we try to nest open blocks,\n> which does not work well with Asciidoctor. Drop the outer one. That\n> fixes the indentation similar to the previous patch, and makes us stop\n> rendering a literal '+' before \"Under --pretty=oneline ...\". Asciidoc\n> renders identically before and after this patch, both man-page and html.\n\nMakes sense. Arguably this could be squashed into the previous one,\nsince the rationale is completely the same (but I'm OK with it either\nway).\n\n-Peff\n"},{"id":"365448","messageId":"20181216105944.GG13704@sigill.intra.peff.net","threadId":"50043","inReplyTo":"20181215112742.1475882-5-martin.agren@gmail.com","subject":"Re: [PATCH 4/4] git-status.txt: render tables correctly under Asciidoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-12-16T10:59:45Z","receivedAt":"2018-12-16T10:59:48Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Dec 15, 2018 at 12:27:42PM +0100, Martin Ågren wrote:\n\n> Asciidoctor removes the indentation of each line in these tables, so the\n> last lines of each table have a completely broken alignment.\n> \n> Similar to 379805051d (\"Documentation: render revisions correctly under\n> Asciidoctor\", 2018-05-06), use an explicit literal block to indicate\n> that we want to keep the leading whitespace in the tables.\n> \n> Because this gives us some extra indentation, we can remove the one that\n> we have been carrying explicitly. That is, drop the first four spaces of\n> indentation on each line. With Asciidoc (8.6.10), this results in\n> identical rendering before and after this commit, both for git-status.1\n> and git-status.html.\n\nYep, this makes sense based on the prior art you cited.\n\nThe whole series looks good to me. Thanks for working on it!\n\n-Peff\n"},{"id":"365453","messageId":"CAN0heSrsZy-pKGu+x2KnNKCnhVtJm9eYJxYFVirxAe7JL6+39A@mail.gmail.com","threadId":"50043","inReplyTo":"20181216105123.GD13704@sigill.intra.peff.net","subject":"Re: [PATCH 1/4] git-column.txt: fix section header","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-12-16T14:27:50Z","receivedAt":"2018-12-16T14:28:04Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sun, 16 Dec 2018 at 11:51, Jeff King wrote:\n>\n> On Sat, Dec 15, 2018 at 12:27:39PM +0100, Martin Ågren wrote:\n>\n> > We have too few dashes under \"Examples\", which causes Asciidoctor to not\n> > pick it up as a section header, but to instead just render the dashes\n> > literally. This also seems to confuse Asciidoctor about dashes in\n> > general around here. It misinterprets the listing blocks in this\n> > section, again rendering the dashes literally.\n> >\n> > Make sure we have as many dashes as we have characters in \"Examples\".\n> > This fixes the section-issue and, somehow, makes the listing blocks\n> > render correctly.\n>\n> The \"somehow\" here is that the mismatched dashes appear to be the start\n> of a code listing block, making the whole example section into one big\n> listing (which isn't properly closed, generating a warning).\n\nOf course. Thanks for pointing it out. I now realize that when I wrote\n\"render the dashes literally\", I was wrong.\n\nThis should be improved in v2.\n\nMartin\n"},{"id":"365454","messageId":"cover.1544969984.git.martin.agren@gmail.com","threadId":"50043","inReplyTo":"20181216105944.GG13704@sigill.intra.peff.net","subject":"[PATCH v2 0/3] A few Asciidoctor-fixes","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-12-16T14:28:56Z","receivedAt":"2018-12-16T14:29:16Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"This series addresses a few instances where our documentation renders\nbadly in Asciidoctor, compared to Asciidoc. The changes made are exactly\nthe same as in v1 [1], but the first commit message is corrected, and\nthe two patches 2/4 and 3/4 are now just a single patch 2/3.\n\nThanks Peff for your comments on v1.\n\n[1] https://public-inbox.org/git/20181215112742.1475882-1-martin.agren@gmail.com/\n\nMartin Ågren (3):\n git-column.txt: fix section header\n Documentation: do not nest open blocks\n git-status.txt: render tables correctly under Asciidoctor\n\n Documentation/git-column.txt | 2 +-\n Documentation/git-init.txt | 4 -\n Documentation/git-status.txt | 162 +++++++++++++++--------------\n Documentation/rev-list-options.txt | 4 -\n 4 files changed, 86 insertions(+), 86 deletions(-)\n\n-- \n2.20.1\n\n"},{"id":"365455","messageId":"0177869f73d2c69b33862f60febc3988c22b1fa8.1544969984.git.martin.agren@gmail.com","threadId":"50043","inReplyTo":"cover.1544969984.git.martin.agren@gmail.com","subject":"[PATCH v2 1/3] git-column.txt: fix section header","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-12-16T14:28:57Z","receivedAt":"2018-12-16T14:29:26Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"We have too few dashes under \"Examples\", which causes Asciidoctor to not\npick it up as a section header. Instead, it thinks we are starting a\ncode listing block, which ends up containing the remainder of the\ndocument. The result is quite ugly.\n\nMake sure we have as many dashes as we have characters in \"Examples\".\nAsciidoc renders identically before and after this patch, both man-page\nand html.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-column.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-column.txt b/Documentation/git-column.txt\nindex 763afabb6d..f58e9c43e6 100644\n--- a/Documentation/git-column.txt\n+++ b/Documentation/git-column.txt\n@@ -47,7 +47,7 @@ OPTIONS\n \tThe number of spaces between columns. One space by default.\n \n EXAMPLES\n-------\n+--------\n \n Format data by columns:\n ------------\n-- \n2.20.1\n\n"},{"id":"365456","messageId":"c966c88d21d144160da4a8b4b4c97c541e970a78.1544969984.git.martin.agren@gmail.com","threadId":"50043","inReplyTo":"cover.1544969984.git.martin.agren@gmail.com","subject":"[PATCH v2 2/3] Documentation: do not nest open blocks","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-12-16T14:28:58Z","receivedAt":"2018-12-16T14:29:29Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"It appears we try to nest open blocks, but that does not work well with\nAsciidoctor, which fails to indent the inner blocks. As a result, they\ndo not visually seem to relate (as much) to the preceding paragraph as\nthey should. Drop the outer blocks to fix the rendering of the inner\nones. Asciidoc renders identically before and after this patch, both\nman-pages and html.\n\nThis also makes Asciidoctor stop rendering a literal '+' before \"Under\n--pretty=oneline ...\" in the manuals for git-log and git-rev-list.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-init.txt | 4 ----\n Documentation/rev-list-options.txt | 4 ----\n 2 files changed, 8 deletions(-)\n\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex 3c5a67fb96..057076ca38 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -38,8 +38,6 @@ the repository to another place if --separate-git-dir is given).\n OPTIONS\n -------\n \n---\n-\n -q::\n --quiet::\n \n@@ -111,8 +109,6 @@ into it.\n If you provide a 'directory', the command is run inside it. If this directory\n does not exist, it will be created.\n \n---\n-\n TEMPLATE DIRECTORY\n ------------------\n \ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex bab5f50b17..98b538bc77 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -13,8 +13,6 @@ has a line that matches ``), unless otherwise noted.\n Note that these are applied before commit\n ordering and formatting options, such as `--reverse`.\n \n---\n-\n -::\n -n ::\n --max-count=::\n@@ -308,8 +306,6 @@ ifdef::git-rev-list[]\n \t`
` text will be printed with each progress update.\n endif::git-rev-list[]\n \n---\n-\n History Simplification\n ~~~~~~~~~~~~~~~~~~~~~~\n \n-- \n2.20.1\n\n"},{"id":"365457","messageId":"2cca954957c5b9c750e6d2211b673997effe7d60.1544969984.git.martin.agren@gmail.com","threadId":"50043","inReplyTo":"cover.1544969984.git.martin.agren@gmail.com","subject":"[PATCH v2 3/3] git-status.txt: render tables correctly under Asciidoctor","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-12-16T14:28:59Z","receivedAt":"2018-12-16T14:29:33Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Asciidoctor removes the indentation of each line in these tables, so the\nlast lines of each table have a completely broken alignment.\n\nSimilar to 379805051d (\"Documentation: render revisions correctly under\nAsciidoctor\", 2018-05-06), use an explicit literal block to indicate\nthat we want to keep the leading whitespace in the tables.\n\nBecause this gives us some extra indentation, we can remove the one that\nwe have been carrying explicitly. That is, drop the first four spaces of\nindentation on each line. With Asciidoc (8.6.10), this results in\nidentical rendering before and after this commit, both for git-status.1\nand git-status.html.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-status.txt | 162 ++++++++++++++++++-----------------\n 1 file changed, 85 insertions(+), 77 deletions(-)\n\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex d9f422d560..861d821d7f 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -197,31 +197,33 @@ codes can be interpreted as follows:\n Ignored files are not listed, unless `--ignored` option is in effect,\n in which case `XY` are `!!`.\n \n- X Y Meaning\n- -------------------------------------------------\n-\t [AMD] not updated\n- M [ MD] updated in index\n- A [ MD] added to index\n- D deleted from index\n- R [ MD] renamed in index\n- C [ MD] copied in index\n- [MARC] index and work tree matches\n- [ MARC] M work tree changed since index\n- [ MARC] D deleted in work tree\n- [ D] R renamed in work tree\n- [ D] C copied in work tree\n- -------------------------------------------------\n- D D unmerged, both deleted\n- A U unmerged, added by us\n- U D unmerged, deleted by them\n- U A unmerged, added by them\n- D U unmerged, deleted by us\n- A A unmerged, both added\n- U U unmerged, both modified\n- -------------------------------------------------\n- ? ? untracked\n- ! ! ignored\n- -------------------------------------------------\n+....\n+X Y Meaning\n+-------------------------------------------------\n+\t [AMD] not updated\n+M [ MD] updated in index\n+A [ MD] added to index\n+D deleted from index\n+R [ MD] renamed in index\n+C [ MD] copied in index\n+[MARC] index and work tree matches\n+[ MARC] M work tree changed since index\n+[ MARC] D deleted in work tree\n+[ D] R renamed in work tree\n+[ D] C copied in work tree\n+-------------------------------------------------\n+D D unmerged, both deleted\n+A U unmerged, added by us\n+U D unmerged, deleted by them\n+U A unmerged, added by them\n+D U unmerged, deleted by us\n+A A unmerged, both added\n+U U unmerged, both modified\n+-------------------------------------------------\n+? ? untracked\n+! ! ignored\n+-------------------------------------------------\n+....\n \n Submodules have more state and instead report\n \t\tM the submodule has a different HEAD than\n@@ -281,14 +283,16 @@ don't recognize.\n If `--branch` is given, a series of header lines are printed with\n information about the current branch.\n \n- Line Notes\n- ------------------------------------------------------------\n- # branch.oid | (initial) Current commit.\n- # branch.head | (detached) Current branch.\n- # branch.upstream If upstream is set.\n- # branch.ab + - If upstream is set and\n-\t\t\t\t\t the commit is present.\n- ------------------------------------------------------------\n+....\n+Line Notes\n+------------------------------------------------------------\n+# branch.oid | (initial) Current commit.\n+# branch.head | (detached) Current branch.\n+# branch.upstream If upstream is set.\n+# branch.ab + - If upstream is set and\n+\t\t\t\t\t the commit is present.\n+------------------------------------------------------------\n+....\n \n ### Changed Tracked Entries\n \n@@ -306,56 +310,60 @@ Renamed or copied entries have the following format:\n \n 2 \n \n- Field Meaning\n- --------------------------------------------------------\n- A 2 character field containing the staged and\n-\t\tunstaged XY values described in the short format,\n-\t\twith unchanged indicated by a \".\" rather than\n-\t\ta space.\n- A 4 character field describing the submodule state.\n-\t\t\"N...\" when the entry is not a submodule.\n-\t\t\"S\" when the entry is a submodule.\n-\t\t is \"C\" if the commit changed; otherwise \".\".\n-\t\t is \"M\" if it has tracked changes; otherwise \".\".\n-\t\t is \"U\" if there are untracked changes; otherwise \".\".\n- The octal file mode in HEAD.\n- The octal file mode in the index.\n- The octal file mode in the worktree.\n- The object name in HEAD.\n- The object name in the index.\n- The rename or copy score (denoting the percentage\n-\t\tof similarity between the source and target of the\n-\t\tmove or copy). For example \"R100\" or \"C75\".\n- The pathname. In a renamed/copied entry, this\n-\t\tis the target path.\n- When the `-z` option is used, the 2 pathnames are separated\n-\t\twith a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)\n-\t\tbyte separates them.\n- The pathname in the commit at HEAD or in the index.\n-\t\tThis is only present in a renamed/copied entry, and\n-\t\ttells where the renamed/copied contents came from.\n- --------------------------------------------------------\n+....\n+Field Meaning\n+--------------------------------------------------------\n+ A 2 character field containing the staged and\n+\t unstaged XY values described in the short format,\n+\t with unchanged indicated by a \".\" rather than\n+\t a space.\n+ A 4 character field describing the submodule state.\n+\t \"N...\" when the entry is not a submodule.\n+\t \"S\" when the entry is a submodule.\n+\t is \"C\" if the commit changed; otherwise \".\".\n+\t is \"M\" if it has tracked changes; otherwise \".\".\n+\t is \"U\" if there are untracked changes; otherwise \".\".\n+ The octal file mode in HEAD.\n+ The octal file mode in the index.\n+ The octal file mode in the worktree.\n+ The object name in HEAD.\n+ The object name in the index.\n+ The rename or copy score (denoting the percentage\n+\t of similarity between the source and target of the\n+\t move or copy). For example \"R100\" or \"C75\".\n+ The pathname. In a renamed/copied entry, this\n+\t is the target path.\n+ When the `-z` option is used, the 2 pathnames are separated\n+\t with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)\n+\t byte separates them.\n+ The pathname in the commit at HEAD or in the index.\n+\t This is only present in a renamed/copied entry, and\n+\t tells where the renamed/copied contents came from.\n+--------------------------------------------------------\n+....\n \n Unmerged entries have the following format; the first character is\n a \"u\" to distinguish from ordinary changed entries.\n \n u

\n \n- Field Meaning\n- --------------------------------------------------------\n- A 2 character field describing the conflict type\n-\t\tas described in the short format.\n- A 4 character field describing the submodule state\n-\t\tas described above.\n- The octal file mode in stage 1.\n- The octal file mode in stage 2.\n- The octal file mode in stage 3.\n- The octal file mode in the worktree.\n-

The object name in stage 1.\n-

The object name in stage 2.\n-

The object name in stage 3.\n- The pathname.\n- --------------------------------------------------------\n+....\n+Field Meaning\n+--------------------------------------------------------\n+ A 2 character field describing the conflict type\n+\t as described in the short format.\n+ A 4 character field describing the submodule state\n+\t as described above.\n+ The octal file mode in stage 1.\n+ The octal file mode in stage 2.\n+ The octal file mode in stage 3.\n+ The octal file mode in the worktree.\n+

The object name in stage 1.\n+

The object name in stage 2.\n+

The object name in stage 3.\n+ The pathname.\n+--------------------------------------------------------\n+....\n \n ### Other Items\n \n-- \n2.20.1\n\n"},{"id":"365458","messageId":"CAN0heSrccWop+KRKFCTNHTB43XcAv+Q8X7p0hT1t2+rPjS1THA@mail.gmail.com","threadId":"50043","inReplyTo":"20181216104458.GC13704@sigill.intra.peff.net","subject":"Re: [PATCH 0/4] A few Asciidoctor-fixes","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-12-16T14:34:42Z","receivedAt":"2018-12-16T14:34:56Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sun, 16 Dec 2018 at 11:45, Jeff King wrote:\n>\n> On Sat, Dec 15, 2018 at 12:27:38PM +0100, Martin Ågren wrote:\n> I think the relevant bits from [1] are:\n>\n> * Use `make --always-make ... install-man` in doc-diff.\n> * ./doc-diff -f HEAD HEAD # note -f\n> * Add empty commit and tweak config.mak\n> * ./doc-diff HEAD^ HEAD # note no -f\n\nYes, that's it.\n\n> To make this easier, it would make sense to me to:\n>\n> - teach doc-diff a flag for marking one or both of the endpoints to be\n> built with asciidoctor versus asciidoc\n>\n> - mark the asciidoc/asciidoctor in the directory name. That name\n> serves as a cache key for avoiding re-doing the work, you should be\n> able to just:\n>\n> ./doc-diff --asciidoctor HEAD HEAD\n>\n> and actually build and compare what you want.\n>\n> - it sounds from \"make --always-make\" that our Makefile does not\n> properly rebuild when we switch from asciidoc to asciidoctor. That\n\nExactly.\n\n> might be nice to fix with a mechanism similar to the GIT-BUILD-FLAGS\n> we use in the top-level Makefile.\n\nAgreed on all three points. The last one would supposedly be useful on\nits own, beyond this doc-diff motivation.\n\nYour list seems complete to me in terms of \"how could we teach doc-diff\nto diff asciidoctor vs asciidoc?\". For the resulting diff to actually be\nuseful ;-) there are two more outstanding issues that I see:\n\n - Headers and footers. Asciidoc (driven by doc-diff) uses some\n boilerplate values which avoid timestamps and the like. Asciidoctor\n partly uses different values, partly interprets the ones given\n differently.\n\n - Asciidoctor introduces a space after linkgit:foo , e.g., before\n punctuation.\n\nBoth of these are problems in their own right, so they probably\nshouldn't be suppressed in the resulting diff. But as long as these\nissues remain, they produce a lot of noise which might hide more\ninteresting (IMHO) differences.\n\nMartin\n"},{"id":"365460","messageId":"20181216161720.GA1511@sigill.intra.peff.net","threadId":"50043","inReplyTo":"CAN0heSrccWop+KRKFCTNHTB43XcAv+Q8X7p0hT1t2+rPjS1THA@mail.gmail.com","subject":"Re: [PATCH 0/4] A few Asciidoctor-fixes","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-12-16T16:17:21Z","receivedAt":"2018-12-16T16:17:25Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Dec 16, 2018 at 03:34:42PM +0100, Martin Ågren wrote:\n\n> Your list seems complete to me in terms of \"how could we teach doc-diff\n> to diff asciidoctor vs asciidoc?\". For the resulting diff to actually be\n> useful ;-) there are two more outstanding issues that I see:\n> \n> - Headers and footers. Asciidoc (driven by doc-diff) uses some\n> boilerplate values which avoid timestamps and the like. Asciidoctor\n> partly uses different values, partly interprets the ones given\n> differently.\n> \n> - Asciidoctor introduces a space after linkgit:foo , e.g., before\n> punctuation.\n> \n> Both of these are problems in their own right, so they probably\n> shouldn't be suppressed in the resulting diff. But as long as these\n> issues remain, they produce a lot of noise which might hide more\n> interesting (IMHO) differences.\n\nIf there are a small number of distinct problems (that each have many\ninstances), I'm not opposed to having a mode to suppress them in the\nresulting diff, so we can see the other problems more clearly. Of\ncourse, just fixing them is even better. ;)\n\nThe first one sounds like it may be a candidate for suppressing (i.e.,\nit's not necessarily an actual problem).\n\n-Peff\n"},{"id":"365461","messageId":"20181216161919.GB1511@sigill.intra.peff.net","threadId":"50043","inReplyTo":"cover.1544969984.git.martin.agren@gmail.com","subject":"Re: [PATCH v2 0/3] A few Asciidoctor-fixes","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-12-16T16:19:19Z","receivedAt":"2018-12-16T16:19:22Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Dec 16, 2018 at 03:28:56PM +0100, Martin Ågren wrote:\n\n> This series addresses a few instances where our documentation renders\n> badly in Asciidoctor, compared to Asciidoc. The changes made are exactly\n> the same as in v1 [1], but the first commit message is corrected, and\n> the two patches 2/4 and 3/4 are now just a single patch 2/3.\n> \n> Thanks Peff for your comments on v1.\n\nThanks, this all looks quite sensible to me (I didn't hack up doc-diff\nas you did, but I did eyeball the before/after html from asciidoctor).\n\n-Peff\n"}]}