Documentation: don't link to example mail addresses
PATCH 1/1 Documentation: don't link to example mail addresses
Mail 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 quoting example mail addresses with "$$", preventing Asciidoc from processing them.
In the case of mailmap.txt, render the address monospaced so that it matches the block examples surrounding that paragraph.
---
I can't see any other uses of the "$$" quote in the documentation, so it's probably worth noting that I've tested this with Asciidoc 8.6.8, although I can't see anything in the changelog to indicate that Asciidoc's treatment of it has changed recently.
Documentation/git-fast-import.txt | 2 +- Documentation/git-tag.txt | 2 +- Documentation/mailmap.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-)
Documentation/git-fast-import.txt +1 -1
@@ -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 -(``[email protected]''). `LT` and `GT` are the literal less-than (\x3c) +(``[email protected]$$''). `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
Documentation/git-tag.txt +1 -1
@@ -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 <[email protected]>") to +committer identity (of the form "Your Name $$<[email protected]>$$") to find a key. If you want to use a different default key, you can specify it in the repository configuration as follows:
Documentation/mailmap.txt +1 -1
@@ -46,7 +46,7 @@ Jane Doe <jane@desktop.(none)> Joe R. Developer <[email protected]> ------------ -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
Signature · 1 line
1.8.0
Quoted 9 lines · John Keeping
Mail 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
Thanks, this is definitely worth fixing.
Quoted 5 lines
Fix this by quoting example mail addresses with "$$", preventing Asciidoc from processing them.
In the case of mailmap.txt, render the address monospaced so that it matches the block examples surrounding that paragraph.
I think I'd just render them monospace everywhere. We are very inconsistent about which form of quotes we use in the documentation (I think because most of the developers read the source directly and not the rendered asciidoc). And then we don't have to worry about the "$$" construct (and IMHO it makes the source much more readable, and marking the address as a literal looks good in the output, too).
-Peff
Quoted 19 lines · Jeff King
Quoted 9 lines · John Keeping
Mail 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@laptopThanks, this is definitely worth fixing.
Quoted 5 lines
Fix this by quoting example mail addresses with "$$", preventing Asciidoc from processing them.
In the case of mailmap.txt, render the address monospaced so that it matches the block examples surrounding that paragraph.
Quoted 6 lines
I think I'd just render them monospace everywhere. We are very inconsistent about which form of quotes we use in the documentation (I think because most of the developers read the source directly and not the rendered asciidoc). And then we don't have to worry about the "$$" construct (and IMHO it makes the source much more readable, and marking the address as a literal looks good in the output, too).
I agree that the source is more readable as monospaced, but I think we need to keep the quotes around the text in git-tag(1) and probably git-fast-import(1) so that it is differentiated from the surrounding text in the man page output.
I just tried this and got strange results. Taking the example in git-tag(1):
...of the form ``Your Name <[email protected]>''
I tried this to preserve the quotes and make the entire quoted text monospaced (I don't think we want to have just the email address monospaced):
...of the form ```Your Name <[email protected]>`''
which had the desired effect - smart quotes and everything inside rendered monospaced - BUT the email address is hyperlinked!
Switching the smart Asciidoc double quotes (``...'') for "normal" double quotes ("...") produces the desired result, but IMHO doesn't look quite as good (on the other hand it looks like there are many more use of "..." than ``...'' in the Git documentation).
[While searching, the only other example I could find is in git-commit(1) where A U Thor <[email protected]> is rendered monospaced without quotes, but I think this hurts readability in the man page output - expect a follow-up patch if we resolve this in the direction of having quotes and monospaced text.]
At this point I've exhausted my Asciidoc knowledge and I'm not entirely happy with any of these options. Suggestions?
John
Quoted 11 lines · John Keeping
Quoted 6 lines
I think I'd just render them monospace everywhere. We are very inconsistent about which form of quotes we use in the documentation (I think because most of the developers read the source directly and not the rendered asciidoc). And then we don't have to worry about the "$$" construct (and IMHO it makes the source much more readable, and marking the address as a literal looks good in the output, too).
I agree that the source is more readable as monospaced, but I think we need to keep the quotes around the text in git-tag(1) and probably git-fast-import(1) so that it is differentiated from the surrounding text in the man page output.
Hmm, good point. I use MAN_BOLD_LITERAL, which serves that purpose, but I guess not everyone does (and it is not the default; I wonder if it should be). But if MAN_BOLD_LITERAL is not in use, then `` literals have zero typographical impact in the manpages.
So maybe we do need to do something else. I was just hoping we could get away with something more readable in the source.
By my reading of the asciidoc user guide, the mechanism that is hurting us is that mailto is an inline macro, and that foo@bar automatically triggers that inline macro. Furthermore, the right way to suppress expansion of macros is with a backslash escape. Doing this:
Documentation/git-fast-import.txt +1 -1
@@ -427,7 +427,7 @@ Here `<name>` is the person's display name (for example Here `<name>` is the person's display name (for example ``Com M Itter'') and `<email>` is the person's email address -(``[email protected]''). `LT` and `GT` are the literal less-than (\x3c) +(``\[email protected]''). `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
seems to produce the output we want. 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.
-Peff
PATCH v2 1/1 Documentation: don't link to example mail addresses
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.
---
Quoted 2 lines · Jeff King
Furthermore, the right way to suppress
expansion of macros is with a backslash escape.
[snipped an example]
Quoted 5 lines
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(-)
Documentation/git-fast-import.txt +1 -1
@@ -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 -(``[email protected]''). `LT` and `GT` are the literal less-than (\x3c) +(``\[email protected]''). `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
Documentation/git-tag.txt +1 -1
@@ -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 <[email protected]>") to +committer identity (of the form "Your Name <\[email protected]>") to find a key. If you want to use a different default key, you can specify it in the repository configuration as follows:
Documentation/mailmap.txt +1 -1
@@ -46,7 +46,7 @@ Jane Doe <jane@desktop.(none)> Joe R. Developer <[email protected]> ------------ -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
Signature · 1 line
1.8.0.2
Quoted 23 lines · John Keeping
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@laptopFix 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 <[email protected]>Signed-off-by John Keeping <[email protected]>---
Quoted 2 lines · Jeff King
Furthermore, the right way to suppress
expansion of macros is with a backslash escape.
Quoted 8 lines
[snipped an example]
Quoted 3 lines
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.
The patch looks reasonable to me, too. We were bitten by relying on the description in AsciiDoc documentation (which shows the state of their latest software) before; between the constructs that work, it is safer to use the older, more vanilla and more common one.
Thanks.
Documentation/git-fast-import.txt they made it. · line 430
Quoted 10 lines · John Keeping
Documentation/git-fast-import.txt +1
-1@@ -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 -(``[email protected]''). `LT` and `GT` are the literal less-than (\x3c) +(``\[email protected]''). `LT` and `GT` are the literal less-than (\x3c)
I seem to be getting
(<tt>\[email protected]''). LT</tt> and <tt>GT</tt> are the literal less-than (\x3c)
out of this part in the resulting HTML output, which is probably not what you wanted to see.
I have a feeling that it might be a better solution to stop using these pretty quotes. It's not like we use them a lot and a quick scanning of "git grep '``'" output seems to tell me that many of them should be monospace output, and the rest (mostly references to section headers) can be "Section".
Quoted 4 lines · Junio C Hamano
I seem to be getting
(<tt>
\[email protected]'').LT</tt> and <tt>GT</tt> are the literal less-than (\x3c)
Quoted 8 lines
out of this part in the resulting HTML output, which is probably not what you wanted to see.
I have a feeling that it might be a better solution to stop using these pretty quotes. It's not like we use them a lot and a quick scanning of "git grep '``'" output seems to tell me that many of them should be
monospace output, and the rest (mostly references to section headers) can be "Section".
Typographically speaking, I would also be just as happy to use regular double-quotes throughout. But here's an example where they also caused a problem (which was fixed by moving to smart-quotes in f34e9ed):
http://thread.gmane.org/gmane.comp.version-control.git/163067
-Peff
Quoted 15 lines · Jeff King
Quoted 4 lines · Junio C Hamano
I seem to be getting
(<tt>
\[email protected]'').LT</tt> and <tt>GT</tt> are the literal less-than (\x3c)Quoted 8 lines
out of this part in the resulting HTML output, which is probably not what you wanted to see.
I have a feeling that it might be a better solution to stop using these pretty quotes. It's not like we use them a lot and a quick scanning of "git grep '``'" output seems to tell me that many of them should be
monospace output, and the rest (mostly references to section headers) can be "Section".
Quoted 5 lines
Typographically speaking, I would also be just as happy to use regular double-quotes throughout. But here's an example where they also caused a problem (which was fixed by moving to smart-quotes in f34e9ed):
http://thread.gmane.org/gmane.comp.version-control.git/163067
I agree with the typography argument.
Many monospaced fonts used in the windows where the programmers view the source of the docmentation, a 'normal' single quote does not slant by the same amount to the opposite quote, so ``a pair does not balance'' visually in the source. And the whole point of writing documentation in AsciiDoc is to keep the source readable. The use of pretty quote throws discards that primary benefit of choosing AsciiDoc in the first place.
Quoted 6 lines · Jeff King
I think I'd just render them monospace everywhere. We are very inconsistent about which form of quotes we use in the documentation (I think because most of the developers read the source directly and not the rendered asciidoc). And then we don't have to worry about the "$$" construct (and IMHO it makes the source much more readable, and marking the address as a literal looks good in the output, too).
Agreed---thanks for spotting, John, and thanks for showing the overall direction, Peff.
Quoted 4 lines · John Keeping
I can't see any other uses of the "$$" quote in the documentation, so it's probably worth noting that I've tested this with Asciidoc 8.6.8, although I can't see anything in the changelog to indicate that Asciidoc's treatment of it has changed recently.
Thanks.
Quoted 10 lines
Documentation/git-fast-import.txt | 2 +- Documentation/git-tag.txt | 2 +- Documentation/mailmap.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-)Documentation/git-fast-import.txt +0
-0
Documentation/git-fast-import.txt they made it. · line 433
Quoted 8 lines
Documentation/git-fast-import.txt +1
-1@@ -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 -(``[email protected]''). `LT` and `GT` are the literal less-than (\x3c) +(``[email protected]$$''). `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
AsciiDoc 8.5.2 gives this:
asciidoc: WARNING: git-fast-import.txt: line 434: nested inline passthrough
Also in git-fast-import.1, there is this line:
... person\(cqs display name (for example Com M Itter\(aq\(aq) and <ema...
(notice two leftover `s); not that this is a new issue with this patch.
Which is puzzling, because the next input line formats better:
... email address (\(lqcm@example\&.com\(rq)\&. ...
Other two hunks for git-tag and mailmap seem to give us a better results.
Quoted 15 lines · Junio C Hamano
Documentation/git-fast-import.txt they made it. · line 433
Quoted 7 lines · John Keeping
Here
<name>is the person's display name (for example ``Com M Itter'') and<email>is the person's email addressDocumentation/git-fast-import.txt +1
-1-(``[email protected]''). `LT` and `GT` are the literal less-than (\x3c) +(``[email protected]$$''). `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 sequenceAsciiDoc 8.5.2 gives this:
asciidoc: WARNING: git-fast-import.txt: line 434: nested inline passthrough
Also in git-fast-import.1, there is this line:
Quoted 7 lines
... person\(cqs display name (for example
Com M Itter\(aq\(aq) and<ema...(notice two leftover `s); not that this is a new issue with this patch.
Which is puzzling, because the next input line formats better:
... email address (\(lqcm@example\&.com\(rq)\&. ...
I wonder if you're hitting this bug, which is listed as fixed in AsciiDoc 8.6.0 [1]:
FIXED: Sometimes multiple double quoted text elements in the same paragraph were mistakenly seen as starting with an inline literal.
As you said in your other message, it may be better to avoid using the pretty quotes, although I don't think just changing them to monospace output is sufficient as monospace output is not distinguished in the default man page output. IMHO that's necessary for any examples that contain whitespace. Perhaps a patch series turning MAN_BOLD_LITERAL on by default and then changing these examples to monospace output?
John
[1] http://www.methods.co.nz/asciidoc/CHANGELOG.html#_version_8_6_0_2010_08_16