[PATCH v2] Documentation: don't link to example mail addresses
- From
John Keeping <john@keeping.me.uk>
- Date
- Dec 16, 2012, 14:00 UTC
- Message-ID
- <20121216140029.GE2725@river.lan>
- In-Reply-To
- <20121216120405.GA14320@sigill.intra.peff.net>
Email addresses in documentation are converted into mailto: hyperlinks in the HTML output and footnotes in man pages. This isn't desirable for cases where the address is used as an example and is not valid.
Particularly annoying is the example "jane@laptop.(none)" which appears in git-shortlog(1) as "jane@laptop[1].(none)", with note 1 saying:
1. jane@laptop mailto:jane@laptop
Fix this by escaping these email addresses with a leading backslash, to prevent Asciidoc expanding them as inline macros.
In the case of mailmap.txt, render the address monospaced so that it matches the block examples surrounding that paragraph.
Helped-by: Jeff King <peff@peff.net> Signed-off-by: John Keeping <john@keeping.me.uk> ---
On Sun, Dec 16, 2012 at 07:04:05AM -0500, Jeff King wrote:
> Furthermore, the right way to suppress > expansion of macros is with a backslash escape.
[snipped an example]
> I think it's a little less ugly > than the "$$" quoting, but not by much. No clue if one is accepted by > more asciidoc versions or not.
>From a quick reading of the Asciidoc changelog, I think backslash
escaping should be supported just as well as "$$" quoting, which leaves the minimal patch looking like this.
Documentation/git-fast-import.txt | 2 +- Documentation/git-tag.txt | 2 +- Documentation/mailmap.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index d1844ea..68bca1a 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -427,7 +427,7 @@ they made it. Here `<name>` is the person's display name (for example ``Com M Itter'') and `<email>` is the person's email address -(``cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) +(``\cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) and greater-than (\x3e) symbols. These are required to delimit the email address from the other fields in the line. Note that `<name>` and `<email>` are free-form and may contain any sequence diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 247534e..2f1c0c3 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -129,7 +129,7 @@ This option is only applicable when listing tags without annotation lines. CONFIGURATION ------------- By default, 'git tag' in sign-with-default mode (-s) will use your -committer identity (of the form "Your Name <your@email.address>") to +committer identity (of the form "Your Name <\your@email.address>") to find a key. If you want to use a different default key, you can specify it in the repository configuration as follows: diff --git a/Documentation/mailmap.txt b/Documentation/mailmap.txt index 288f04e..dd89fca 100644 --- a/Documentation/mailmap.txt +++ b/Documentation/mailmap.txt @@ -46,7 +46,7 @@ Jane Doe <jane@desktop.(none)> Joe R. Developer <joe@example.com> ------------ -Note how there is no need for an entry for <jane@laptop.(none)>, because the +Note how there is no need for an entry for `<jane@laptop.(none)>`, because the real name of that author is already correct. Example 2: Your repository contains commits from the following
-- 1.8.0.2