{"thread":{"id":"39310","subject":"[PATCH] doc: fix unmatched code fences","startedAt":"2015-05-12T17:23:20Z","lastAt":"2015-05-17T18:34:19Z","messageCount":37,"participants":["Jean-Noel Avila","Junio C Hamano","Jeff King","Johannes Schindelin","John Keeping","brian m. carlson","David Turner"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"261056","messageId":"1431451400-1447-1-git-send-email-jn.avila@free.fr","threadId":"39310","inReplyTo":null,"subject":"[PATCH] doc: fix unmatched code fences","fromName":"Jean-Noel Avila","fromEmail":"jn.avila@free.fr","sentAt":"2015-05-12T17:23:20Z","receivedAt":"2015-05-12T17:23:20Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"This mismatch upsets the renderer on git-scm.com.\n\nSigned-off-by: Jean-Noel Avila \n---\n Documentation/gitcore-tutorial.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt\nindex 8475c07..36e9ab3 100644\n--- a/Documentation/gitcore-tutorial.txt\n+++ b/Documentation/gitcore-tutorial.txt\n@@ -259,7 +259,7 @@ index 557db03..263414f 100644\n @@ -1 +1,2 @@\n Hello World\n +It's a new day for git\n-----\n+------------\n \n i.e. the diff of the change we caused by adding another line to `hello`.\n \n-- \n2.4.0.rc2\n"},{"id":"261065","messageId":"xmqqfv71zlaz.fsf@gitster.dls.corp.google.com","threadId":"39310","inReplyTo":"1431451400-1447-1-git-send-email-jn.avila@free.fr","subject":"Re: [PATCH] doc: fix unmatched code fences","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-12T18:45:56Z","receivedAt":"2015-05-12T18:45:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noel Avila writes:\n\n> This mismatch upsets the renderer on git-scm.com.\n\nThanks.\n\nI do not think this is the first time AsciiDoc(or) rendering glitch\nwas reported. GitHub folks, can you guys think of an automated way\nto spot these? Relying on site visitors to eyeball and hoping them\nto report is not an ideal approach.\n\n>\n> Signed-off-by: Jean-Noel Avila \n> ---\n> Documentation/gitcore-tutorial.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt\n> index 8475c07..36e9ab3 100644\n> --- a/Documentation/gitcore-tutorial.txt\n> +++ b/Documentation/gitcore-tutorial.txt\n> @@ -259,7 +259,7 @@ index 557db03..263414f 100644\n> @@ -1 +1,2 @@\n> Hello World\n> +It's a new day for git\n> -----\n> +------------\n> \n> i.e. the diff of the change we caused by adding another line to `hello`.\n"},{"id":"261113","messageId":"20150513021556.GA4160@peff.net","threadId":"39310","inReplyTo":"xmqqfv71zlaz.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: fix unmatched code fences","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-05-13T02:15:56Z","receivedAt":"2015-05-13T02:15:56Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 12, 2015 at 11:45:56AM -0700, Junio C Hamano wrote:\n\n> Jean-Noel Avila writes:\n> \n> > This mismatch upsets the renderer on git-scm.com.\n> \n> Thanks.\n> \n> I do not think this is the first time AsciiDoc(or) rendering glitch\n> was reported. GitHub folks, can you guys think of an automated way\n> to spot these? Relying on site visitors to eyeball and hoping them\n> to report is not an ideal approach.\n\nHere's a patch to fix the remaining cases of this particular problem, at\nleast.\n\nYou can build with asciidoctor on the command-line. I don't know if it\nwould be feasible to diff the asciidoc and asciidoctor output to look\nfor gratuitous differences (or if the output is so different due to\ntrivial stuff that the diff is unreadable).\n\n-- >8 --\nSubject: doc: fix unmatched code fences in git-stripspace\n\nThe asciidoctor renderer is more picky than classic asciidoc,\nand insists that the start and end of a code fence be the\nsame size.\n\nFound with this hacky perl script:\n\n foreach my $fn (@ARGV) {\n open(my $fh, '<', $fn);\n my ($fence, $fence_lineno, $prev);\n while (<$fh>) {\n chomp;\n if (/^----+$/) {\n if ($fence_lineno) {\n if ($_ ne $fence) {\n print \"$fn:$fence_lineno:mismatched fence: \",\n length($fence), \" != \", length($_), \"\\n\";\n }\n $fence_lineno = undef;\n }\n\t # hacky check to avoid title-underlining\n elsif ($prev eq '' || $prev eq '+') {\n $fence = $_;\n $fence_lineno = $.;\n }\n }\n $prev = $_;\n }\n }\n\nSigned-off-by: Jeff King \n---\nWith this patch and the one from Jean-Noel, the script above finds only\none hit, which is a false positive. It's at git-commit.txt:233, and it\nlooks like:\n\n It is a rough equivalent for:\n ------\n $ git reset --soft HEAD^\n $ ... do something else to come up with the right tree ...\n $ git commit -c ORIG_HEAD\n\n ------\n\nI have no idea how asciidoc knows that this is a code block and not a\ntitle called \"It is a rough...\". So probably in addition to this false\npositive, we may be missing some other cases. Doing it right would\nprobably involve just reusing asciidoc's parser.\n\n Documentation/git-stripspace.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt\nindex 6c6e989..60328d5 100644\n--- a/Documentation/git-stripspace.txt\n+++ b/Documentation/git-stripspace.txt\n@@ -49,7 +49,7 @@ EXAMPLES\n \n Given the following noisy input with '$' indicating the end of a line:\n \n---------\n+---------\n |A brief introduction $\n | $\n |$\n@@ -65,7 +65,7 @@ Given the following noisy input with '$' indicating the end of a line:\n \n Use 'git stripspace' with no arguments to obtain:\n \n---------\n+---------\n |A brief introduction$\n |$\n |A new paragraph$\n@@ -79,7 +79,7 @@ Use 'git stripspace' with no arguments to obtain:\n \n Use 'git stripspace --strip-comments' to obtain:\n \n---------\n+---------\n |A brief introduction$\n |$\n |A new paragraph$\n-- \n2.4.0.192.g5f8138b\n"},{"id":"261114","messageId":"xmqqk2wdcfbb.fsf@gitster.dls.corp.google.com","threadId":"39310","inReplyTo":"20150513021556.GA4160@peff.net","subject":"Re: [PATCH] doc: fix unmatched code fences","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-13T03:43:52Z","receivedAt":"2015-05-13T03:43:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> With this patch and the one from Jean-Noel, the script above finds only\n> one hit, which is a false positive. It's at git-commit.txt:233, and it\n> looks like:\n>\n> It is a rough equivalent for:\n> ------\n> $ git reset --soft HEAD^\n> $ ... do something else to come up with the right tree ...\n> $ git commit -c ORIG_HEAD\n>\n> ------\n>\n> I have no idea how asciidoc knows that this is a code block and not a\n> title called \"It is a rough...\".\n\nIt obviously is not a title underline as the lengths are vastly\ndifferent. It would be an interesing exercise to make both of them\nlonger, but I suspect giving an extra blank line there may not hurt.\n\nThanks, will queue.\n"},{"id":"261115","messageId":"20150513034553.GA25025@peff.net","threadId":"39310","inReplyTo":"xmqqk2wdcfbb.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: fix unmatched code fences","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-05-13T03:45:53Z","receivedAt":"2015-05-13T03:45:53Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 12, 2015 at 08:43:52PM -0700, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> > With this patch and the one from Jean-Noel, the script above finds only\n> > one hit, which is a false positive. It's at git-commit.txt:233, and it\n> > looks like:\n> >\n> > It is a rough equivalent for:\n> > ------\n> > $ git reset --soft HEAD^\n> > $ ... do something else to come up with the right tree ...\n> > $ git commit -c ORIG_HEAD\n> >\n> > ------\n> >\n> > I have no idea how asciidoc knows that this is a code block and not a\n> > title called \"It is a rough...\".\n> \n> It obviously is not a title underline as the lengths are vastly\n> different.\n\nYes, but Python Asciidoc allows the lengths to differ. So clearly it\nuses some kind of heuristic, or this is some context in the parser that\ndisambiguates the case.\n\n-Peff\n"},{"id":"261118","messageId":"xmqq8uctcd1u.fsf@gitster.dls.corp.google.com","threadId":"39310","inReplyTo":"20150513034553.GA25025@peff.net","subject":"Re: [PATCH] doc: fix unmatched code fences","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-13T04:32:45Z","receivedAt":"2015-05-13T04:32:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n>> It obviously is not a title underline as the lengths are vastly\n>> different.\n>\n> Yes, but Python Asciidoc allows the lengths to differ.\n\nHmmm, I thought the title underline was a bit more strict. I do\nrecall having to fix manual pages for many commands, but we do not\nadd new commands these days anymore, so perhaps things have changed\nsince then.\n\n> So clearly it\n> uses some kind of heuristic, or this is some context in the parser that\n> disambiguates the case.\n\nPerhaps.\n\nThanks.\n"},{"id":"261119","messageId":"20150513043609.GA6038@peff.net","threadId":"39310","inReplyTo":"xmqq8uctcd1u.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: fix unmatched code fences","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-05-13T04:36:09Z","receivedAt":"2015-05-13T04:36:09Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 12, 2015 at 09:32:45PM -0700, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> >> It obviously is not a title underline as the lengths are vastly\n> >> different.\n> >\n> > Yes, but Python Asciidoc allows the lengths to differ.\n> \n> Hmmm, I thought the title underline was a bit more strict. I do\n> recall having to fix manual pages for many commands, but we do not\n> add new commands these days anymore, so perhaps things have changed\n> since then.\n\nI think it is loose in AsciiDoc and strict in AsciiDoctor, so we have\nbeen slowly making sure they are all consistent. And we missed one,\nwhich will be in the series I'll send in a moment. :)\n\nI suspect the potential ambiguity is one of the reasons that AsciiDoctor\nwent with the stricter rule.\n\n-Peff\n"},{"id":"261121","messageId":"20150513045650.GA6070@peff.net","threadId":"39310","inReplyTo":"20150513021556.GA4160@peff.net","subject":"[PATCH 0/8] asciidoc fixups","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-05-13T04:56:51Z","receivedAt":"2015-05-13T04:56:51Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 12, 2015 at 10:15:56PM -0400, Jeff King wrote:\n\n> You can build with asciidoctor on the command-line. I don't know if it\n> would be feasible to diff the asciidoc and asciidoctor output to look\n> for gratuitous differences (or if the output is so different due to\n> trivial stuff that the diff is unreadable).\n\nSo...it kind of works. I had to do unspeakable things with sed, and even\nthen ended up with an 18,000-line \"--color-words\" diff.\n\nBelow are some fixes. The early ones are actual bugs in our sources. The\nlatter ones are changes we could do to make asciidoctor happier. Each\npatch is independent, so we can take or leave whatever we want.\n\nAfter this series, the remaining problems are:\n\n - asciidoctor does not render {litdd}, which is our invention; locally\n this may be because I did not have the right incantation, but it is\n also broken on git-scm.com. I think the right fix is to define that\n attribute for the site renderer (so not a bug in our sources, and\n not an asciidoctor bug)\n\n - in the '[verse]' section of the SYNOPSIS of each man page, AsciiDoc\n renders 'git add' in the usual way (with emphasis). Whereas\n AsciiDoctor renders it normally, with the literal quotes included.\n\n In the same [verse] section, AsciiDoctor does not convert literal\n \"...\" into a fancy ellipsis. So perhaps it treats [verse] as a\n section in which markup is not expanded? This may be related to the\n [verseblock] stuff we have in our config file.\n\n - We use \"{attr? foo}\" to display \"foo\" only when \"attr\" is set.\n AsciiDoctor does not seem to understand this and renders the whole\n string.\n\n - Lots of places where we backslash-escape some syntax for AsciiDoc\n ends up rendered by AsciiDoctor with the backslashes included. In\n some cases the quoting is unnecessary and we can drop it (see\n patches 6 and 7 below). But in others it really is necessary, and\n AsciiDoc generates bad output without the backslashes. The major\n ones are \"--\" surrounded by spaces (which becomes an emdash), and\n things like @\\{HEAD}, which needs quoted to tell AsciiDoc that HEAD\n isn't an attribute.\n\n I'm not sure of the solution (is AsciiDoctor just broken, or\n is there some other syntax we could use that would work in both\n places, or what?).\n\nHere are the patches. They do not include the code-fence fixes from\nJean-Noel and myself that were already posted, but could easily go on\ntop.\n\n [1/8]: doc: fix misrendering due to `single quote'\n [2/8]: doc: fix unquoted use of \"{type}\"\n [3/8]: doc: fix hanging \"+\"-continuation\n [4/8]: doc: fix length of underlined section-title\n [5/8]: doc/add: reformat `--edit` option\n [6/8]: doc: convert \\--option to --option\n [7/8]: doc: drop backslash quoting of some curly braces\n [8/8]: doc: put example URLs inside literal backticks\n\n-Peff\n"},{"id":"261122","messageId":"20150513045754.GA6821@peff.net","threadId":"39310","inReplyTo":"20150513045650.GA6070@peff.net","subject":"[PATCH 1/8] doc: fix misrendering due to `single quote'","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-05-13T04:57:54Z","receivedAt":"2015-05-13T04:57:54Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"AsciiDoc misparses some text that contains a `literal`\nword followed by a fancy `single quote' word, and treats\neverything from the start of the literal to the end of the\nquote as a single-quoted phrase.\n\nWe can work around this by switching the latter to be a\nliteral, as well. In the first case, this is perhaps what\nwas intended anyway, as it makes us consistent with the the\nearlier literals in the same paragraph. In the second, the\noutput is arguably better, as we will format our commit\nreferences as blocks.\n\nSigned-off-by: Jeff King \n---\n Documentation/diff-generate-patch.txt | 2 +-\n Documentation/git-rebase.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex 843a20b..bcf54da 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -77,7 +77,7 @@ combined diff format\n Any diff-generating command can take the `-c` or `--cc` option to\n produce a 'combined diff' when showing a merge. This is the default\n format when showing merges with linkgit:git-diff[1] or\n-linkgit:git-show[1]. Note also that you can give the `-m' option to any\n+linkgit:git-show[1]. Note also that you can give the `-m` option to any\n of these commands to force generation of diffs with individual parents\n of a merge.\n \ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex 47984e8..1d01baa 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -80,7 +80,7 @@ remain the checked-out branch.\n If the upstream branch already contains a change you have made (e.g.,\n because you mailed a patch which was applied upstream), then that commit\n will be skipped. For example, running `git rebase master` on the\n-following history (in which A' and A introduce the same set of changes,\n+following history (in which `A'` and `A` introduce the same set of changes,\n but have different committer information):\n \n ------------\n-- \n2.4.0.192.g5f8138b\n"},{"id":"261123","messageId":"20150513045805.GB6821@peff.net","threadId":"39310","inReplyTo":"20150513045650.GA6070@peff.net","subject":"[PATCH 2/8] doc: fix unquoted use of \"{type}\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-05-13T04:58:06Z","receivedAt":"2015-05-13T04:58:06Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"Curly braces open an \"attribute\" in AsciiDoc; if there's no\nsuch attribute, strange things may happen. In this case, the\nunquoted \"{type}\" causes AsciiDoc to omit an entire line of\ntext from the output. We can fix it by putting the whole\nphrase inside literal backticks (which also lets us get rid\nof ugly backslash escaping).\n\nSigned-off-by: Jeff King \n---\n Documentation/git-rev-parse.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex 97fc703..52e6826 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -102,7 +102,7 @@ eval \"set -- $(git rev-parse --sq --prefix \"$prefix\" \"$@\")\"\n +\n If you want to make sure that the output actually names an object in\n your object database and/or can be used as a specific type of object\n-you require, you can add \"\\^{type}\" peeling operator to the parameter.\n+you require, you can add the `^{type}` peeling operator to the parameter.\n For example, `git rev-parse \"$VAR^{commit}\"` will make sure `$VAR`\n names an existing object that is a commit-ish (i.e. a commit, or an\n annotated tag that points at a commit). To make sure that `$VAR`\n-- \n2.4.0.192.g5f8138b\n"},{"id":"261124","messageId":"20150513045816.GC6821@peff.net","threadId":"39310","inReplyTo":"20150513045650.GA6070@peff.net","subject":"[PATCH 3/8] doc: fix hanging \"+\"-continuation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-05-13T04:58:16Z","receivedAt":"2015-05-13T04:58:16Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"In list content that wants to continue to a second\nparagraph, the \"+\" continuation and subsequent paragraph\nneed to be left-aligned. Otherwise AsciiDoc seems to insert\nonly a linebreak.\n\nSigned-off-by: Jeff King \n---\n Documentation/git-svn.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex 39e9a18..1377008 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -279,9 +279,9 @@ first have already been pushed into SVN.\n \tAsk the user to confirm that a patch set should actually be sent to SVN.\n \tFor each patch, one may answer \"yes\" (accept this patch), \"no\" (discard this\n \tpatch), \"all\" (accept all patches), or \"quit\".\n-\t+\n-\t'git svn dcommit' returns immediately if answer is \"no\" or \"quit\", without\n-\tcommitting anything to SVN.\n++\n+'git svn dcommit' returns immediately if answer is \"no\" or \"quit\", without\n+committing anything to SVN.\n \n 'branch'::\n \tCreate a branch in the SVN repository.\n-- \n2.4.0.192.g5f8138b\n"},{"id":"261125","messageId":"20150513045828.GD6821@peff.net","threadId":"39310","inReplyTo":"20150513045650.GA6070@peff.net","subject":"[PATCH 4/8] doc: fix length of underlined section-title","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-05-13T04:58:29Z","receivedAt":"2015-05-13T04:58:29Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"In AsciiDoc, it is OK to say:\n\n this is my title\n -------------------------\n\nbut AsciiDoctor is more strict. Let's match the underline to\nthe title (which also makes the source prettier to read).\nThe output from AsciiDoc is the same either way.\n\nSigned-off-by: Jeff King \n---\n Documentation/git-fast-import.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex 690fed3..bf7fbd4 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -600,7 +600,7 @@ be removed from the branch.\n See `filemodify` above for a detailed description of ``.\n \n `filecopy`\n-^^^^^^^^^^^^\n+^^^^^^^^^^\n Recursively copies an existing file or subdirectory to a different\n location within the branch. The existing file or directory must\n exist. If the destination exists it will be completely replaced\n-- \n2.4.0.192.g5f8138b\n"},{"id":"261126","messageId":"20150513045851.GE6821@peff.net","threadId":"39310","inReplyTo":"20150513045650.GA6070@peff.net","subject":"[PATCH 5/8] doc/add: reformat `--edit` option","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-05-13T04:58:51Z","receivedAt":"2015-05-13T04:58:51Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"All of the other options in the list put short and long as\ntwo separate headings.\n\nWe can also drop the backslashing of `--`. It isn't used\nelsewhere and is unnecessary for modern asciidoc (plus it\nconfuses asciidoctor).\n\nSigned-off-by: Jeff King \n---\n Documentation/git-add.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex f2eb907..fe5282f 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -93,7 +93,8 @@ This effectively runs `add --interactive`, but bypasses the\n initial command menu and directly jumps to the `patch` subcommand.\n See ``Interactive mode'' for details.\n \n--e, \\--edit::\n+-e::\n+--edit::\n \tOpen the diff vs. the index in an editor and let the user\n \tedit it. After the editor was closed, adjust the hunk headers\n \tand apply the patch to the index.\n-- \n2.4.0.192.g5f8138b\n"},{"id":"261127","messageId":"20150513050137.GF6821@peff.net","threadId":"39310","inReplyTo":"20150513045650.GA6070@peff.net","subject":"[PATCH 6/8] doc: convert \\--option to --option","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-05-13T05:01:38Z","receivedAt":"2015-05-13T05:01:38Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"Older versions of AsciiDoc would convert the \"--\" in\n\"--option\" into an emdash. According to 565e135\n(Documentation: quote double-dash for AsciiDoc, 2011-06-29),\nthis is fixed in AsciiDoc 8.3.0. According to bf17126, we\ndon't support anything older than 8.4.1 anyway, so we no\nlonger need to worry about quoting.\n\nEven though this does not change the output at all, there\nare a few good reasons to drop the quoting:\n\n 1. It makes the source prettier to read.\n\n 2. We don't quote consistently, which may be confusing when\n reading the source.\n\n 3. Asciidoctor does not like the quoting, and renders a\n literal backslash.\n\nSigned-off-by: Jeff King \n---\nSo this is the first of the more questionable patches, simply because we\nare appeasing Asciidoctor, but not fixing the root problem (i.e., there\nare still lots of places where the backslash quoting is messed up, like\nHEAD@\\{yesterday}). So I suspect we need to figure that problem out, and\nthen the asciidoctor issues will just go away. However, I think this may\nbe worth doing just to prettify the source.\n\n Documentation/config.txt | 10 ++--\n Documentation/git-fast-export.txt | 6 +--\n Documentation/git-fast-import.txt | 28 +++++------\n Documentation/git-fetch-pack.txt | 2 +-\n Documentation/git-pack-objects.txt | 2 +-\n Documentation/git-push.txt | 4 +-\n Documentation/git-rev-list.txt | 96 +++++++++++++++++++-------------------\n Documentation/git-rev-parse.txt | 2 +-\n Documentation/git-send-pack.txt | 2 +-\n Documentation/git-show.txt | 2 +-\n Documentation/gitdiffcore.txt | 6 +--\n 11 files changed, 80 insertions(+), 80 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 948b8b0..e5d2ace 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -2279,18 +2279,18 @@ remote..skipFetchAll::\n \n remote..receivepack::\n \tThe default program to execute on the remote side when pushing. See\n-\toption \\--receive-pack of linkgit:git-push[1].\n+\toption --receive-pack of linkgit:git-push[1].\n \n remote..uploadpack::\n \tThe default program to execute on the remote side when fetching. See\n-\toption \\--upload-pack of linkgit:git-fetch-pack[1].\n+\toption --upload-pack of linkgit:git-fetch-pack[1].\n \n remote..tagOpt::\n-\tSetting this value to \\--no-tags disables automatic tag following when\n-\tfetching from remote . Setting it to \\--tags will fetch every\n+\tSetting this value to --no-tags disables automatic tag following when\n+\tfetching from remote . Setting it to --tags will fetch every\n \ttag from remote , even if they are not reachable from remote\n \tbranch heads. Passing these flags directly to linkgit:git-fetch[1] can\n-\toverride this setting. See options \\--tags and \\--no-tags of\n+\toverride this setting. See options --tags and --no-tags of\n \tlinkgit:git-fetch[1].\n \n remote..vcs::\ndiff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\nindex 929e496..ed57c68 100644\n--- a/Documentation/git-fast-export.txt\n+++ b/Documentation/git-fast-export.txt\n@@ -67,17 +67,17 @@ produced incorrect results if you gave these options.\n \thave been completed, or to save the marks table across\n \tincremental runs. As is only opened and truncated\n \tat completion, the same path can also be safely given to\n-\t\\--import-marks.\n+\t--import-marks.\n \tThe file will not be written if no new object has been\n \tmarked/exported.\n \n --import-marks=::\n \tBefore processing any input, load the marks specified in\n \t. The input file must exist, must be readable, and\n-\tmust use the same format as produced by \\--export-marks.\n+\tmust use the same format as produced by --export-marks.\n +\n Any commits that have already been marked will not be exported again.\n-If the backend uses a similar \\--import-marks file, this allows for\n+If the backend uses a similar --import-marks file, this allows for\n incremental bidirectional exporting of the repository by keeping the\n marks the same across runs.\n \ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex bf7fbd4..fd32895 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -42,13 +42,13 @@ OPTIONS\n --quiet::\n \tDisable all non-fatal output, making fast-import silent when it\n \tis successful. This option disables the output shown by\n-\t\\--stats.\n+\t--stats.\n \n --stats::\n \tDisplay some basic statistics about the objects fast-import has\n \tcreated, the packfiles they were stored into, and the\n \tmemory used by fast-import during this run. Showing this output\n-\tis currently the default, but can be disabled with \\--quiet.\n+\tis currently the default, but can be disabled with --quiet.\n \n Options for Frontends\n ~~~~~~~~~~~~~~~~~~~~~\n@@ -81,12 +81,12 @@ Locations of Marks Files\n \thave been completed, or to save the marks table across\n \tincremental runs. As is only opened and truncated\n \tat checkpoint (or completion) the same path can also be\n-\tsafely given to \\--import-marks.\n+\tsafely given to --import-marks.\n \n --import-marks=::\n \tBefore processing any input, load the marks specified in\n \t. The input file must exist, must be readable, and\n-\tmust use the same format as produced by \\--export-marks.\n+\tmust use the same format as produced by --export-marks.\n \tMultiple options may be supplied to import more than one\n \tset of marks. If a mark is defined to different values,\n \tthe last file wins.\n@@ -179,8 +179,8 @@ fast-forward update, fast-import will skip updating that ref and instead\n prints a warning message. fast-import will always attempt to update all\n branch refs, and does not stop on the first failure.\n \n-Branch updates can be forced with \\--force, but it's recommended that\n-this only be used on an otherwise quiet repository. Using \\--force\n+Branch updates can be forced with --force, but it's recommended that\n+this only be used on an otherwise quiet repository. Using --force\n is not necessary for an initial import into an empty repository.\n \n \n@@ -231,11 +231,11 @@ Date Formats\n ~~~~~~~~~~~~\n The following date formats are supported. A frontend should select\n the format it will use for this import by passing the format name\n-in the \\--date-format= command-line option.\n+in the --date-format= command-line option.\n \n `raw`::\n \tThis is the Git native format and is `