{"thread":{"id":"16204","subject":"Fwd: Documentation/user-manual.txt, asciidoc and \"--\" escapes","startedAt":"2008-11-07T03:09:58Z","lastAt":"2008-11-15T12:07:53Z","messageCount":9,"participants":["Piotr Findeisen","Jonas Fonseca","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"95094","messageId":"ddb82bf60811061909m6f8a7b72o4b03ebcde8b9d188@mail.gmail.com","threadId":"16204","inReplyTo":"ddb82bf60811061904t5defc492m80cd1b759674eb6@mail.gmail.com","subject":"Fwd: Documentation/user-manual.txt, asciidoc and \"--\" escapes","fromName":"Piotr Findeisen","fromEmail":"piotr.findeisen@gmail.com","sentAt":"2008-11-07T03:09:58Z","receivedAt":"2008-11-07T03:09:58Z","isPatch":false,"sender":{"key":"piotr.findeisen@gmail.com","avatar":null},"body":"Hello!\n\nI've been reading\nhttp://www.kernel.org/pub/software/scm/git/docs/user-manual.html till\nlate night and found that \"--\" prefixing options names (like in \"git\ndiff --cached\") are replaced by asciidoc with a single unicode\ncharacter \"—\" which makes them unsuitable for pasting them to a\nterminal.\n\nI've cloned the git repository from\ngit://git.kernel.org/pub/scm/git/git.git, made some changes to\nDocumentation/user-manual.txt, tested the results and commited my work\nlocally.\nThe attached file is a result of running `git diff HEAD~1`.\n\nMy local log message:\n------------------\nasciidoc escaping of \"--\"\n\nAsciidoc replaces \"--\" with \"—\" when not in verbatim mode. This is\nsometimes unwanted -- especially when citing command line options like\n\"git diff --cached\". This commit includes proper quotes in user-manual.txt.\n------------------\n\nHope that's of any use.\n\nBest regards,\nPiotr\n\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 645d752..66d0cca 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -527,8 +527,8 @@ $ git reset --hard fb47ddb2db...\n then test, run \"bisect good\" or \"bisect bad\" as appropriate, and\n continue.\n \n-Instead of \"git bisect visualize\" and then \"git reset --hard\n-fb47ddb2db...\", you might just want to tell git that you want to skip\n+Instead of \"git bisect visualize\" and then \"+++git reset --hard\n+fb47ddb2db...+++\", you might just want to tell git that you want to skip\n the current commit:\n \n -------------------------------------------------\n@@ -660,7 +660,7 @@ You can also ask git log to show patches:\n $ git log -p\n -------------------------------------------------\n \n-See the \"--pretty\" option in the linkgit:git-log[1] man page for more\n+See the \"+++--pretty+++\" option in the linkgit:git-log[1] man page for more\n display options.\n \n Note that git log starts with the most recent commit and works\n@@ -900,7 +900,7 @@ $ gitk $( git show-ref --heads ) --not  $( git show-ref --tags )\n -------------------------------------------------\n \n (See linkgit:git-rev-parse[1] for explanations of commit-selecting\n-syntax such as `--not`.)\n+syntax such as `+++--not+++`.)\n \n [[making-a-release]]\n Creating a changelog and tarball for a software release\n@@ -1024,7 +1024,7 @@ at step 3, git maintains a snapshot of the tree's contents in a\n special staging area called \"the index.\"\n \n At the beginning, the content of the index will be identical to\n-that of the HEAD.  The command \"git diff --cached\", which shows\n+that of the HEAD.  The command \"+++git diff --cached+++\", which shows\n the difference between the HEAD and the index, should therefore\n produce no output at that point.\n \n@@ -1572,7 +1572,7 @@ Recovering lost changes\n Reflogs\n ^^^^^^^\n \n-Say you modify a branch with `linkgit:git-reset[1] --hard`, and then\n+Say you modify a branch with `linkgit:git-reset[1] +++--hard+++`, and then\n realize that the branch was the only reference you had to that point in\n history.\n \n@@ -1701,7 +1701,7 @@ $ git pull\n More generally, a branch that is created from a remote branch will pull\n by default from that branch.  See the descriptions of the\n branch.<name>.remote and branch.<name>.merge options in\n-linkgit:git-config[1], and the discussion of the `--track` option in\n+linkgit:git-config[1], and the discussion of the `+++--track+++` option in\n linkgit:git-checkout[1], to learn how to control these defaults.\n \n In addition to saving you keystrokes, \"git pull\" also helps you by\n@@ -1978,8 +1978,8 @@ error: failed to push to 'ssh://yourserver.com/~you/proj.git'\n \n This can happen, for example, if you:\n \n-\t- use `git-reset --hard` to remove already-published commits, or\n-\t- use `git-commit --amend` to replace already-published commits\n+\t- use `+++git-reset --hard+++` to remove already-published commits, or\n+\t- use `+++git-commit --amend+++` to replace already-published commits\n \t  (as in <<fixing-a-mistake-by-rewriting-history>>), or\n \t- use `git-rebase` to rebase any already-published commits (as\n \t  in <<using-git-rebase>>).\n@@ -2088,7 +2088,7 @@ linkgit:git-fetch[1] to keep them up-to-date; see\n \n Now create the branches in which you are going to work; these start out\n at the current tip of origin/master branch, and should be set up (using\n-the --track option to linkgit:git-branch[1]) to merge changes in from\n+the +++--track+++ option to linkgit:git-branch[1]) to merge changes in from\n Linus by default.\n \n -------------------------------------------------\n@@ -2468,7 +2468,7 @@ $ git rebase --continue\n \n and git will continue applying the rest of the patches.\n \n-At any point you may use the `--abort` option to abort this process and\n+At any point you may use the `+++--abort+++` option to abort this process and\n return mywork to the state it had before you started the rebase:\n \n -------------------------------------------------\n@@ -2539,7 +2539,7 @@ $ gitk origin..mywork &\n \n and browse through the list of patches in the mywork branch using gitk,\n applying them (possibly in a different order) to mywork-new using\n-cherry-pick, and possibly modifying them as you go using `commit --amend`.\n+cherry-pick, and possibly modifying them as you go using `+++commit --amend+++`.\n The linkgit:git-gui[1] command may also help as it allows you to\n individually select diff hunks for inclusion in the index (by\n right-clicking on the diff hunk and choosing \"Stage Hunk for Commit\").\n@@ -2897,7 +2897,7 @@ Commit Object\n ~~~~~~~~~~~~~\n \n The \"commit\" object links a physical state of a tree with a description\n-of how we got there and why.  Use the --pretty=raw option to\n+of how we got there and why.  Use the +++--pretty=raw+++ option to\n linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite\n commit:\n \n@@ -3700,16 +3700,16 @@ i.e. it will normally just update existing cache entries.\n \n To tell git that yes, you really do realize that certain files no\n longer exist, or that new files should be added, you\n-should use the `--remove` and `--add` flags respectively.\n+should use the `+++--remove+++` and `+++--add+++` flags respectively.\n \n-NOTE! A `--remove` flag does 'not' mean that subsequent filenames will\n+NOTE! A `+++--remove+++` flag does 'not' mean that subsequent filenames will\n necessarily be removed: if the files still exist in your directory\n structure, the index will be updated with their new status, not\n-removed. The only thing `--remove` means is that update-index will be\n+removed. The only thing `+++--remove+++` means is that update-index will be\n considering a removed file to be a valid thing, and if the file really\n does not exist any more, it will update the index accordingly.\n \n-As a special case, you can also do `git update-index --refresh`, which\n+As a special case, you can also do `+++git update-index --refresh+++`, which\n will refresh the \"stat\" information of each index to match the current\n stat information. It will 'not' update the object status itself, and\n it will only update the fields that are used to quickly test whether\n@@ -3956,7 +3956,7 @@ entries\" in it. Such an index tree can 'NOT' be written out to a tree\n object, and you will have to resolve any such merge clashes using\n other tools before you can write out the result.\n \n-You can examine such index state with `git ls-files --unmerged`\n+You can examine such index state with `+++git ls-files --unmerged+++`\n command.  An example:\n \n ------------------------------------------------\n@@ -3967,7 +3967,7 @@ $ git ls-files --unmerged\n 100644 cc44c73eb783565da5831b4d820c962954019b69 3\thello.c\n ------------------------------------------------\n \n-Each line of the `git ls-files --unmerged` output begins with\n+Each line of the `+++git ls-files --unmerged+++` output begins with\n the blob mode bits, blob SHA1, 'stage number', and the\n filename.  The 'stage number' is git's way to say which tree it\n came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`\n"},{"id":"95249","messageId":"ddb82bf60811090044l43eb4bb1ga5a16718a4176c29@mail.gmail.com","threadId":"16204","inReplyTo":"ddb82bf60811061909m6f8a7b72o4b03ebcde8b9d188@mail.gmail.com","subject":"Re: Documentation/user-manual.txt, asciidoc and \"--\" escapes","fromName":"Piotr Findeisen","fromEmail":"piotr.findeisen@gmail.com","sentAt":"2008-11-09T08:44:35Z","receivedAt":"2008-11-09T08:44:35Z","isPatch":false,"sender":{"key":"piotr.findeisen@gmail.com","avatar":null},"body":"Same thing done the right way.\n\nregards,\nP.\n\nOn Fri, Nov 7, 2008 at 04:09, Piotr Findeisen <piotr.findeisen@gmail.com> wrote:\n>\n> Hello!\n>\n> I've been reading\n> http://www.kernel.org/pub/software/scm/git/docs/user-manual.html till\n> late night and found that \"--\" prefixing options names (like in \"git\n> diff --cached\") are replaced by asciidoc with a single unicode\n> character \"—\" which makes them unsuitable for pasting them to a\n> terminal.\n>\n> I've cloned the git repository from\n> git://git.kernel.org/pub/scm/git/git.git, made some changes to\n> Documentation/user-manual.txt, tested the results and commited my work\n> locally.\n> The attached file is a result of running `git diff HEAD~1`.\n>\n> My local log message:\n> ------------------\n> asciidoc escaping of \"--\"\n>\n> Asciidoc replaces \"--\" with \"—\" when not in verbatim mode. This is\n> sometimes unwanted -- especially when citing command line options like\n> \"git diff --cached\". This commit includes proper quotes in user-manual.txt.\n> ------------------\n>\n> Hope that's of any use.\n>\n> Best regards,\n> Piotr\n\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 645d752..d200759 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -527,7 +527,7 @@ $ git reset --hard fb47ddb2db...\n then test, run \"bisect good\" or \"bisect bad\" as appropriate, and\n continue.\n \n-Instead of \"git bisect visualize\" and then \"git reset --hard\n+Instead of \"git bisect visualize\" and then \"git reset \\--hard\n fb47ddb2db...\", you might just want to tell git that you want to skip\n the current commit:\n \n@@ -900,7 +900,7 @@ $ gitk $( git show-ref --heads ) --not  $( git show-ref --tags )\n -------------------------------------------------\n \n (See linkgit:git-rev-parse[1] for explanations of commit-selecting\n-syntax such as `--not`.)\n+syntax such as `\\--not`.)\n \n [[making-a-release]]\n Creating a changelog and tarball for a software release\n@@ -1024,7 +1024,7 @@ at step 3, git maintains a snapshot of the tree's contents in a\n special staging area called \"the index.\"\n \n At the beginning, the content of the index will be identical to\n-that of the HEAD.  The command \"git diff --cached\", which shows\n+that of the HEAD.  The command \"git diff \\--cached\", which shows\n the difference between the HEAD and the index, should therefore\n produce no output at that point.\n \n@@ -1572,7 +1572,7 @@ Recovering lost changes\n Reflogs\n ^^^^^^^\n \n-Say you modify a branch with `linkgit:git-reset[1] --hard`, and then\n+Say you modify a branch with `linkgit:git-reset[1] \\--hard`, and then\n realize that the branch was the only reference you had to that point in\n history.\n \n@@ -1701,7 +1701,7 @@ $ git pull\n More generally, a branch that is created from a remote branch will pull\n by default from that branch.  See the descriptions of the\n branch.<name>.remote and branch.<name>.merge options in\n-linkgit:git-config[1], and the discussion of the `--track` option in\n+linkgit:git-config[1], and the discussion of the `\\--track` option in\n linkgit:git-checkout[1], to learn how to control these defaults.\n \n In addition to saving you keystrokes, \"git pull\" also helps you by\n@@ -1978,8 +1978,8 @@ error: failed to push to 'ssh://yourserver.com/~you/proj.git'\n \n This can happen, for example, if you:\n \n-\t- use `git-reset --hard` to remove already-published commits, or\n-\t- use `git-commit --amend` to replace already-published commits\n+\t- use `git-reset \\--hard` to remove already-published commits, or\n+\t- use `git-commit \\--amend` to replace already-published commits\n \t  (as in <<fixing-a-mistake-by-rewriting-history>>), or\n \t- use `git-rebase` to rebase any already-published commits (as\n \t  in <<using-git-rebase>>).\n@@ -2088,7 +2088,7 @@ linkgit:git-fetch[1] to keep them up-to-date; see\n \n Now create the branches in which you are going to work; these start out\n at the current tip of origin/master branch, and should be set up (using\n-the --track option to linkgit:git-branch[1]) to merge changes in from\n+the \\--track option to linkgit:git-branch[1]) to merge changes in from\n Linus by default.\n \n -------------------------------------------------\n@@ -2468,7 +2468,7 @@ $ git rebase --continue\n \n and git will continue applying the rest of the patches.\n \n-At any point you may use the `--abort` option to abort this process and\n+At any point you may use the `\\--abort` option to abort this process and\n return mywork to the state it had before you started the rebase:\n \n -------------------------------------------------\n@@ -2539,7 +2539,7 @@ $ gitk origin..mywork &\n \n and browse through the list of patches in the mywork branch using gitk,\n applying them (possibly in a different order) to mywork-new using\n-cherry-pick, and possibly modifying them as you go using `commit --amend`.\n+cherry-pick, and possibly modifying them as you go using `commit \\--amend`.\n The linkgit:git-gui[1] command may also help as it allows you to\n individually select diff hunks for inclusion in the index (by\n right-clicking on the diff hunk and choosing \"Stage Hunk for Commit\").\n@@ -2897,7 +2897,7 @@ Commit Object\n ~~~~~~~~~~~~~\n \n The \"commit\" object links a physical state of a tree with a description\n-of how we got there and why.  Use the --pretty=raw option to\n+of how we got there and why.  Use the \\--pretty=raw option to\n linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite\n commit:\n \n@@ -3700,16 +3700,16 @@ i.e. it will normally just update existing cache entries.\n \n To tell git that yes, you really do realize that certain files no\n longer exist, or that new files should be added, you\n-should use the `--remove` and `--add` flags respectively.\n+should use the `\\--remove` and `\\--add` flags respectively.\n \n-NOTE! A `--remove` flag does 'not' mean that subsequent filenames will\n+NOTE! A `\\--remove` flag does 'not' mean that subsequent filenames will\n necessarily be removed: if the files still exist in your directory\n structure, the index will be updated with their new status, not\n-removed. The only thing `--remove` means is that update-index will be\n+removed. The only thing `\\--remove` means is that update-index will be\n considering a removed file to be a valid thing, and if the file really\n does not exist any more, it will update the index accordingly.\n \n-As a special case, you can also do `git update-index --refresh`, which\n+As a special case, you can also do `git update-index \\--refresh`, which\n will refresh the \"stat\" information of each index to match the current\n stat information. It will 'not' update the object status itself, and\n it will only update the fields that are used to quickly test whether\n@@ -3956,7 +3956,7 @@ entries\" in it. Such an index tree can 'NOT' be written out to a tree\n object, and you will have to resolve any such merge clashes using\n other tools before you can write out the result.\n \n-You can examine such index state with `git ls-files --unmerged`\n+You can examine such index state with `git ls-files \\--unmerged`\n command.  An example:\n \n ------------------------------------------------\n@@ -3967,7 +3967,7 @@ $ git ls-files --unmerged\n 100644 cc44c73eb783565da5831b4d820c962954019b69 3\thello.c\n ------------------------------------------------\n \n-Each line of the `git ls-files --unmerged` output begins with\n+Each line of the `git ls-files \\--unmerged` output begins with\n the blob mode bits, blob SHA1, 'stage number', and the\n filename.  The 'stage number' is git's way to say which tree it\n came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`\n"},{"id":"95274","messageId":"2c6b72b30811091052k77200785j722c8aed2beb7684@mail.gmail.com","threadId":"16204","inReplyTo":"ddb82bf60811090044l43eb4bb1ga5a16718a4176c29@mail.gmail.com","subject":"Re: Documentation/user-manual.txt, asciidoc and \"--\" escapes","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2008-11-09T18:52:22Z","receivedAt":"2008-11-09T18:52:22Z","isPatch":false,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"> On Fri, Nov 7, 2008 at 04:09, Piotr Findeisen <piotr.findeisen@gmail.com> wrote:\n>> Hello!\n\nHello,\n\n>> The attached file is a result of running `git diff HEAD~1`.\n\nPlease read Documentation/SubmittingPatches for the preferred way to\ncontribute patches.\n\n>> Asciidoc replaces \"--\" with \"—\" when not in verbatim mode. This is\n>> sometimes unwanted -- especially when citing command line options like\n>> \"git diff --cached\". This commit includes proper quotes in user-manual.txt.\n\nNewer asciidoc versions have the following \"workaround\". Maybe adding\nsomething like this to Documentation/asciidoc.conf would be more\nfuture proof.\n\n# -- Spaced and unspaced em dashes (entity reference &mdash;)\n# But disallow unspaced in man pages because double-dash option name prefixes\n# are pervasive.\nifndef::doctype-manpage[]\n(^|[^-\\\\])--($|[^-])=\\1&#8212;\\2\nendif::doctype-manpage[]\nifdef::doctype-manpage[]\n(^|\\s*[^\\S\\\\])--($|\\s+)=\\1&#8212;\\2\nendif::doctype-manpage[]\n\\\\--(?!-)=--\n\n-- \nJonas Fonseca\n"},{"id":"95308","messageId":"ddb82bf60811092338m3aad8041w20de23f18aa7d56e@mail.gmail.com","threadId":"16204","inReplyTo":"2c6b72b30811091052k77200785j722c8aed2beb7684@mail.gmail.com","subject":"Re: Documentation/user-manual.txt, asciidoc and \"--\" escapes","fromName":"Piotr Findeisen","fromEmail":"piotr.findeisen@gmail.com","sentAt":"2008-11-10T07:38:24Z","receivedAt":"2008-11-10T07:38:24Z","isPatch":false,"sender":{"key":"piotr.findeisen@gmail.com","avatar":null},"body":"Hi!\n\n>>> The attached file is a result of running `git diff HEAD~1`.\n>\n> Please read Documentation/SubmittingPatches for the preferred way to\n> contribute patches.\n\nOk, I'll look there, when you tell me this patch is worth anything.\n\n\n>>> Asciidoc replaces \"--\" with \"—\" when not in verbatim mode. This is\n>>> sometimes unwanted -- especially when citing command line options like\n>>> \"git diff --cached\". This commit includes proper quotes in user-manual.txt.\n>\n> Newer asciidoc versions have the following \"workaround\". Maybe adding\n> something like this to Documentation/asciidoc.conf would be more\n> future proof.\n>\n> # -- Spaced and unspaced em dashes (entity reference &mdash;)\n> # But disallow unspaced in man pages because double-dash option name prefixes\n> # are pervasive.\n> ifndef::doctype-manpage[]\n> (^|[^-\\\\])--($|[^-])=\\1&#8212;\\2\n> endif::doctype-manpage[]\n> ifdef::doctype-manpage[]\n> (^|\\s*[^\\S\\\\])--($|\\s+)=\\1&#8212;\\2\n> endif::doctype-manpage[]\n> \\\\--(?!-)=--\n\nWell, this doesn't solve the problem -- I'm not talking about\nmanpages, the \"--\" where replaced with single \"—\" on the\nhttp://www.kernel.org/pub/software/scm/git/docs/user-manual.html page.\nYes, we can disable such a replacement in the config file, but take a\nlook at the sentence \"...how to fetch and study a project using\ngit—read these chapters...\". In this case \"--\" in the source file was\nreplaced with \"—\" and this is what we want.\n\nI noticed that all substitutions \"--\" -> \"—\", where \"—\" is a part of\nsentence punctuation, match \\w--\\w pattern (e.g. no spaces on both\nsides) and probably this is how it should be written in English. But\nbasing on this doesn't seem to me to be fool proof.\n\nBest regards,\nPiotr\n"},{"id":"95320","messageId":"20081110100757.GA12868@diku.dk","threadId":"16204","inReplyTo":"ddb82bf60811092338m3aad8041w20de23f18aa7d56e@mail.gmail.com","subject":"Re: Documentation/user-manual.txt, asciidoc and \"--\" escapes","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2008-11-10T10:07:58Z","receivedAt":"2008-11-10T10:07:58Z","isPatch":false,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"Piotr Findeisen <piotr.findeisen@gmail.com> wrote Mon, Nov 10, 2008:\n> >>> Asciidoc replaces \"--\" with \"—\" when not in verbatim mode. This is\n> >>> sometimes unwanted -- especially when citing command line options like\n> >>> \"git diff --cached\". This commit includes proper quotes in user-manual.txt.\n> >\n> > Newer asciidoc versions have the following \"workaround\". Maybe adding\n> > something like this to Documentation/asciidoc.conf would be more\n> > future proof.\n>\n> Well, this doesn't solve the problem -- I'm not talking about\n> manpages, the \"--\" where replaced with single \"—\" on the\n> http://www.kernel.org/pub/software/scm/git/docs/user-manual.html page.\n\nSorry I didn't read your mail carefully enough.\n\n> Yes, we can disable such a replacement in the config file, but take a\n> look at the sentence \"...how to fetch and study a project using\n> git—read these chapters...\". In this case \"--\" in the source file was\n> replaced with \"—\" and this is what we want.\n\nTrue.\n\n> I noticed that all substitutions \"--\" -> \"—\", where \"—\" is a part of\n> sentence punctuation, match \\w--\\w pattern (e.g. no spaces on both\n> sides) and probably this is how it should be written in English. But\n> basing on this doesn't seem to me to be fool proof.\n\nSo another option is to disable all substitution of \"--\" and just use\nthe \"—\" character when it is explicitly needed. The documentation is\nusing UTF-8 after all. This would also fix the usage of \"--\" in the\nmanpages, e.g.\n\n\tYou've now initialized the working directory--you may notice ...\n\nin gittutorial(7). On my setup, with \"--\" replaced with \"—\", I get the\nfollowing nroff code:\n\n\tYou've now initialized the working directory\\(emyou may notice\n\t...\n\n-- \nJonas Fonseca\n"},{"id":"95323","messageId":"ddb82bf60811100214j4246cf25yc1263c2ae8cd10fc@mail.gmail.com","threadId":"16204","inReplyTo":"20081110100757.GA12868@diku.dk","subject":"Re: Documentation/user-manual.txt, asciidoc and \"--\" escapes","fromName":"Piotr Findeisen","fromEmail":"piotr.findeisen@gmail.com","sentAt":"2008-11-10T10:14:43Z","receivedAt":"2008-11-10T10:14:43Z","isPatch":false,"sender":{"key":"piotr.findeisen@gmail.com","avatar":null},"body":">\n>> I noticed that all substitutions \"--\" -> \"—\", where \"—\" is a part of\n>> sentence punctuation, match \\w--\\w pattern (e.g. no spaces on both\n>> sides) and probably this is how it should be written in English. But\n>> basing on this doesn't seem to me to be fool proof.\n>\n> So another option is to disable all substitution of \"--\" and just use\n> the \"—\" character when it is explicitly needed. The documentation is\n> using UTF-8 after all. This would also fix the usage of \"--\" in the\n> manpages, e.g.\n>\n>        You've now initialized the working directory--you may notice ...\n>\n> in gittutorial(7). On my setup, with \"--\" replaced with \"—\", I get the\n> following nroff code:\n\nOn my machine, make gittutorial.7 produces manpage that displays \"--\"\nin this place :)\n\n>\n>        You've now initialized the working directory\\(emyou may notice\n\nAnyway, this may be a good idea to use unambiguous \"—\" (though people\nwriting docs may be used to using \"--\" as a punctuation). I can run\nthrough the Documentation replacing \"\\w--\\w\" with m-dash, if you want.\n\nRegards,\nPiotr\n"},{"id":"95510","messageId":"20081112000445.GB17662@diku.dk","threadId":"16204","inReplyTo":"ddb82bf60811100214j4246cf25yc1263c2ae8cd10fc@mail.gmail.com","subject":"Re: Documentation/user-manual.txt, asciidoc and \"--\" escapes","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2008-11-12T00:04:45Z","receivedAt":"2008-11-12T00:04:45Z","isPatch":false,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"Piotr Findeisen <piotr.findeisen@gmail.com> wrote Mon, Nov 10, 2008:\n> > This would also fix the usage of \"--\" in the manpages, e.g.\n> >\n> >        You've now initialized the working directory--you may notice ...\n> >\n> > in gittutorial(7). On my setup, with \"--\" replaced with \"—\", I get the\n> > following nroff code:\n> \n> On my machine, make gittutorial.7 produces manpage that displays \"--\"\n> in this place :)\n\nAt least you don't loose anything compared to the current behavior. ;)\n\n> >        You've now initialized the working directory\\(emyou may notice\n> \n> Anyway, this may be a good idea to use unambiguous \"—\" (though people\n> writing docs may be used to using \"--\" as a punctuation). I can run\n> through the Documentation replacing \"\\w--\\w\" with m-dash, if you want.\n\nI would like to see such a patch.\n\n-- \nJonas Fonseca\n"},{"id":"95781","messageId":"ddb82bf60811140502y60987761g55fc959a3e246afe@mail.gmail.com","threadId":"16204","inReplyTo":"20081112000445.GB17662@diku.dk","subject":"Re: Documentation/user-manual.txt, asciidoc and \"--\" escapes","fromName":"Piotr Findeisen","fromEmail":"piotr.findeisen@gmail.com","sentAt":"2008-11-14T13:02:59Z","receivedAt":"2008-11-14T13:02:59Z","isPatch":false,"sender":{"key":"piotr.findeisen@gmail.com","avatar":null},"body":"I've investigated it a little.\nIt seems that this newet version of asciidoc (I'm running 8.2.2) has\nthe global asciidoc.conf file (placed in /etc/asciidoc/asciidoc.conf\non my computer) containing the previously cited section:\n\n    # -- Spaced and unspaced em dashes (entity reference &mdash;)\n    # But disallow unspaced in man pages because double-dash option\nname prefixes\n    # are pervasive.\n    ifndef::doctype-manpage[]\n    (^|[^-\\\\])--($|[^-])=\\1&#8212;\\2\n    endif::doctype-manpage[]\n    ifdef::doctype-manpage[]\n    (^|\\s*[^\\S\\\\])--($|\\s+)=\\1&#8212;\\2\n    endif::doctype-manpage[]\n    \\\\--(?!-)=--\n\nThose replacements are run *before* any replacements defined in\nuser-provided files are taken into consideration. You can disable them\nonly by disabling all replacements, I think.\n\nSo the only thing we can do about automatic conversion \"--\" to \"—\" is putting\n    [replacements]\n    &8212;=--\nin Documentation/asciidoc.conf file or similar. (8212 = x2014,\n\"\\u2014\" = \"—\"). This way the unwanted replacement is reverted.\n\nHowever, this forbids literal \"&8212;\" in the source .txt files and\nthere is no way to enable it. This seems only little probable that\nanyone would want to write \"&8212;\" until someone writes \"writing\nDocumentation guide\" where she would state that \"&8212;\" is\nprohibited.\n\nIf this is good solution and we want to replace punctuation \"--\" with\nunicode \"—\", I will do this.\nHowever, this seems a bit messy -- fighting against asciidoc instead\nof using it as it's designed to be used. IMHO, it's better to\nexplicitly escape non-punctuation \"--\" with \"\\\" and write punctuation\n\"--\" with spaces on both sides. Please note, writing literal \"—\" isn't\nso simple -- there is no such key on the keyboard :)\n\nBest regards,\nPiotr\n\n\n\nOn Wed, Nov 12, 2008 at 01:04, Jonas Fonseca <fonseca@diku.dk> wrote:\n> Piotr Findeisen <piotr.findeisen@gmail.com> wrote Mon, Nov 10, 2008:\n>> > This would also fix the usage of \"--\" in the manpages, e.g.\n>> >\n>> >        You've now initialized the working directory--you may notice ...\n>> >\n>> > in gittutorial(7). On my setup, with \"--\" replaced with \"—\", I get the\n>> > following nroff code:\n>>\n>> On my machine, make gittutorial.7 produces manpage that displays \"--\"\n>> in this place :)\n>\n> At least you don't loose anything compared to the current behavior. ;)\n>\n>> >        You've now initialized the working directory\\(emyou may notice\n>>\n>> Anyway, this may be a good idea to use unambiguous \"—\" (though people\n>> writing docs may be used to using \"--\" as a punctuation). I can run\n>> through the Documentation replacing \"\\w--\\w\" with m-dash, if you want.\n>\n> I would like to see such a patch.\n>\n> --\n> Jonas Fonseca\n>\n"},{"id":"95873","messageId":"7vzlk15h0m.fsf@gitster.siamese.dyndns.org","threadId":"16204","inReplyTo":"ddb82bf60811140502y60987761g55fc959a3e246afe@mail.gmail.com","subject":"Re: Documentation/user-manual.txt, asciidoc and \"--\" escapes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-11-15T12:07:53Z","receivedAt":"2008-11-15T12:07:53Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Piotr Findeisen\" <piotr.findeisen@gmail.com> writes:\n\n> However, this seems a bit messy -- fighting against asciidoc instead\n> of using it as it's designed to be used. IMHO, it's better to\n> explicitly escape non-punctuation \"--\" with \"\\\" and write punctuation\n> \"--\" with spaces on both sides.\n\nThanks for digging.  I agree with that.\n"}]}