Revert "Documentation: Fix ssh://[user@]host.xz URL"

PATCH New Alp Toker 3 participants 12 messages Jun 15, 2016 Documentation

lore

Share & tools

lore

Alp Toker

author

2016-06-15 22:42 UTC #0 lore raw

PATCH 1/1 Revert "Documentation: Fix ssh://[user@]host.xz URL"

This reverts commit 8d5e26848d0ddd5063f078b0c34c6c48b68d0d94.

The patch did not eliminate warnings caused by bad asciidoc markup. Nor did it correct the generated output, which remains unchanged.

Signed-off-by Alp Toker <[email protected]>

---
 Documentation/urls.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

Documentation/urls.txt +3 -3

index 93378d2..9abec80 100644
@@ -10,9 +10,9 @@ to name the remote repository:
 - https://host.xz/path/to/repo.git/
 - git://host.xz/path/to/repo.git/
 - git://host.xz/~user/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/~user/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/~/path/to/repo.git
+- ssh://[user@]host.xz/path/to/repo.git/
+- ssh://[user@]host.xz/~user/path/to/repo.git/
+- ssh://[user@]host.xz/~/path/to/repo.git
 ===============================================================
 
 SSH Is the default transport protocol and also supports an

Signature · 1 line

1.4.1.g28ec

Alp Toker

author

2016-06-15 22:42 UTC #1 lore raw

PATCH 1/1 Documentation: Fix ssh:// URLs in generated documentation

Commit c3f17061be95de3498449a548e93883aebff23d6 was causing warnings during doc generation due to bad asciidoc markup.

This resulted in "ssh://[user@]host.xz/path/to/repo.git/" being rendered as "host.xz/path/to/repo.git/" in the man pages and html output.

This patch converts sections listing URL formats to verbatim.

Signed-off-by Alp Toker <[email protected]>

---
 Documentation/urls.txt |   30 ++++++++++++------------------
 1 files changed, 12 insertions(+), 18 deletions(-)

Documentation/urls.txt +12 ~~-18~~

index 9abec80..a071915 100644
@@ -4,33 +4,27 @@ GIT URLS[[URLS]]
 One of the following notations can be used
 to name the remote repository:
 
-===============================================================
-- rsync://host.xz/path/to/repo.git/
-- http://host.xz/path/to/repo.git/
-- https://host.xz/path/to/repo.git/
-- git://host.xz/path/to/repo.git/
-- git://host.xz/~user/path/to/repo.git/
-- ssh://[user@]host.xz/path/to/repo.git/
-- ssh://[user@]host.xz/~user/path/to/repo.git/
-- ssh://[user@]host.xz/~/path/to/repo.git
-===============================================================
+	rsync://host.xz/path/to/repo.git/
+	http://host.xz/path/to/repo.git/
+	https://host.xz/path/to/repo.git/
+	git://host.xz/path/to/repo.git/
+	git://host.xz/~user/path/to/repo.git/
+	ssh://[user@]host.xz/path/to/repo.git/
+	ssh://[user@]host.xz/~user/path/to/repo.git/
+	ssh://[user@]host.xz/~/path/to/repo.git
 
 SSH Is the default transport protocol and also supports an
 scp-like syntax.  Both syntaxes support username expansion,
 as does the native git protocol. The following three are
 identical to the last three above, respectively:
 
-===============================================================
-- host.xz:/path/to/repo.git/
-- host.xz:~user/path/to/repo.git/
-- host.xz:path/to/repo.git
-===============================================================
+	host.xz:/path/to/repo.git/
+	host.xz:~user/path/to/repo.git/
+	host.xz:path/to/repo.git
 
 To sync with a local directory, use:
 
-===============================================================
-- /path/to/repo.git/
-===============================================================
+	/path/to/repo.git/
 
 REMOTES
 -------

Signature · 1 line

1.4.1.g28ec

Alp Toker

author

2016-06-15 22:42 UTC #2 lore raw

PATCH 1/1 Documentation: Minor capitalization typofix

This ended up appearing in several man pages by inclusion.

Signed-off-by Alp Toker <[email protected]>

---
 Documentation/urls.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

Documentation/urls.txt +1 -1

index a071915..2b5a7f8 100644
@@ -13,7 +13,7 @@ to name the remote repository:
 	ssh://[user@]host.xz/~user/path/to/repo.git/
 	ssh://[user@]host.xz/~/path/to/repo.git
 
-SSH Is the default transport protocol and also supports an
+SSH is the default transport protocol and also supports an
 scp-like syntax.  Both syntaxes support username expansion,
 as does the native git protocol. The following three are
 identical to the last three above, respectively:

Signature · 1 line

1.4.1.g28ec

Junio C Hamano

2016-06-15 22:42 UTC #3 lore raw

Re: [PATCH] Documentation: Fix ssh:// URLs in generated documentation

In reply to Alp Toker

Quoted 2 lines · Alp Toker

Commit c3f17061be95de3498449a548e93883aebff23d6 was causing warnings during doc generation due to bad asciidoc markup.

It seems that the '+++' quoting does not seem to work with older asciidoc.

However, I just noticed that what the text talks about is wrong to begin with (not your fault):

Quoted 7 lines

(quoted diff) +7 -0

+	rsync://host.xz/path/to/repo.git/
+	http://host.xz/path/to/repo.git/
+	https://host.xz/path/to/repo.git/
+	git://host.xz/path/to/repo.git/
+	git://host.xz/~user/path/to/repo.git/
+	ssh://[user@]host.xz/path/to/repo.git/
+	ssh://[user@]host.xz/~user/path/to/repo.git/

Review

Quoted 10 lines

(quoted diff) +4 -0

+	ssh://[user@]host.xz/~/path/to/repo.git
 
 SSH Is the default transport protocol and also supports an
 scp-like syntax.  Both syntaxes support username expansion,
 as does the native git protocol. The following three are
 identical to the last three above, respectively:
 
+	host.xz:/path/to/repo.git/
+	host.xz:~user/path/to/repo.git/
+	host.xz:path/to/repo.git

So how about something like this instead, until people have up to date asciidoc?

Documentation/urls.txt +8 -4

index 93378d2..a5519e5 100644
@@ -10,12 +10,12 @@ to name the remote repository:
 - https://host.xz/path/to/repo.git/
 - git://host.xz/path/to/repo.git/
 - git://host.xz/~user/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/~user/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/~/path/to/repo.git
+- ssh://host.xz/path/to/repo.git/
+- ssh://host.xz/~user/path/to/repo.git/
+- ssh://host.xz/~/path/to/repo.git
 ===============================================================
 
-SSH Is the default transport protocol and also supports an
+SSH is the default transport protocol and also supports an
 scp-like syntax.  Both syntaxes support username expansion,
 as does the native git protocol. The following three are
 identical to the last three above, respectively:

@@ -26,6 +26,10 @@ identical to the last three above, respe
 - host.xz:path/to/repo.git
 ===============================================================
 
+In addition, you can specify the name of the user to log in as
+by saying `ssh://[email protected]/\...` and `[email protected]:\...` for
+the SSH protocol.
+
 To sync with a local directory, use:
 
 ===============================================================

Jonas Fonseca

2016-06-15 22:42 UTC #4 lore raw

PATCH 1/1 urls.txt: Use substitution to escape square brackets

In reply to Alp Toker

This changes "[user@]" to use {startsb} and {endsb} to insert [ and ], similar to how {caret} is used in git-rev-parse.txt.

Signed-off-by Jonas Fonseca <[email protected]>

---

Alternate "fix".

---

Documentation/asciidoc.conf +2 -0

index 7ce7151..41754d5 100644
@@ -9,6 +9,8 @@ # the command.
 
 [attributes]
 caret=^
+startsb=&#91; # [
+endsb=&#93;   # ]
 
 ifdef::backend-docbook[]
 [gitlink-inlinemacro]

Documentation/urls.txt +3 -3

index 93378d2..2950ac9 100644
@@ -10,9 +10,9 @@ to name the remote repository:
 - https://host.xz/path/to/repo.git/
 - git://host.xz/path/to/repo.git/
 - git://host.xz/~user/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/~user/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/~/path/to/repo.git
+- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/
+- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/
+- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git
 ===============================================================
 
 SSH Is the default transport protocol and also supports an

Signature · 1 line

Jonas Fonseca

Junio C Hamano

2016-06-15 22:42 UTC #5 lore raw

PATCH 1/1 urls.txt: Use substitution to escape square brackets

Alp is right -- the comments in [attributes] section after the definition do appear in the output, even with asciidoc 7.1.2, so here is a replacement proposal from me.

The one by Alp is an easy work-around, but I do not want to worry about potential, unintended, breakages that might be caused by changing delimited blocks to literal paragraphs (and it changes the resulting rendering from the original).

-- >8 --
From: Jonas Fonseca <[email protected]>

This changes "[user@]" to use {startsb} and {endsb} to insert [ and ], similar to how {caret} is used in git-rev-parse.txt.

[jc: Removed a well-intentioned comment that broke the final
formatting from the original patch. While we are at it, updated the paragraph that claims to be equivalent to the section that was updated earlier without making matching changes.]

Signed-off-by Jonas Fonseca <[email protected]>

Signed-off-by Junio C Hamano <[email protected]>

---
 Documentation/asciidoc.conf |    2 ++
 Documentation/urls.txt      |   17 +++++++++--------
 2 files changed, 11 insertions(+), 8 deletions(-)

Documentation/asciidoc.conf +2 -0

index 7ce7151..8196d78 100644
@@ -9,6 +9,8 @@ # the command.
 
 [attributes]
 caret=^
+startsb=&#91;
+endsb=&#93;
 
 ifdef::backend-docbook[]
 [gitlink-inlinemacro]

Documentation/urls.txt +9 -8

index 9d2ad46..26ecba5 100644
@@ -10,20 +10,21 @@ to name the remote repository:
 - https://host.xz/path/to/repo.git/
 - git://host.xz/path/to/repo.git/
 - git://host.xz/~user/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/~user/path/to/repo.git/
-- ssh://+++[user@+++]host.xz/~/path/to/repo.git
+- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/
+- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/
+- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git
 ===============================================================
 
-SSH Is the default transport protocol and also supports an
-scp-like syntax.  Both syntaxes support username expansion,
+SSH is the default transport protocol.  You can optionally specify
+which user to log-in as, and an alternate, scp-like syntax is also
+supported.  Both syntaxes support username expansion,
 as does the native git protocol. The following three are
 identical to the last three above, respectively:
 
 ===============================================================
-- host.xz:/path/to/repo.git/
-- host.xz:~user/path/to/repo.git/
-- host.xz:path/to/repo.git
+- {startsb}user@{endsb}host.xz:/path/to/repo.git/
+- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/
+- {startsb}user@{endsb}host.xz:path/to/repo.git
 ===============================================================
 
 To sync with a local directory, use:

Signature · 1 line

1.4.1.g28ec

Jonas Fonseca

2016-06-15 22:42 UTC #6 lore raw

PATCH 1/1 Make asciidoc related rules depend on asciidoc.conf

Any rule running asciidoc, whether using -f asciidoc.conf or not, will read asciidoc.conf. Make such rules depend on asciidoc.conf.

Signed-off-by Jonas Fonseca <[email protected]>

---

Junio C Hamano <[email protected]> wrote Fri, Jul 14, 2006:

Quoted 3 lines

Alp is right -- the comments in [attributes] section after the definition do appear in the output, even with asciidoc 7.1.2, so here is a replacement proposal from me.

Am using the same setup as Alp (AsciiDoc 7.0.2 on Ubuntu Dapper), so I was a bit curious that I could not see that. So I guess I compiled the docs first and later decided to add the comments which then didn't cause a recompilation.

I don't know if there should be a dependency on asciidoc.conf in every rule calling asciidoc. Could be annoying if you are only making a minor change.

---

Documentation/Makefile +5 -5

index cc83610..ce6c6cf 100644
@@ -76,18 +76,18 @@ README: ../README
 clean:
 	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep README
 
-%.html : %.txt
+%.html : %.txt asciidoc.conf
 	asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<
 
 %.1 %.7 : %.xml
 	xmlto -m callouts.xsl man $<
 
-%.xml : %.txt
+%.xml : %.txt asciidoc.conf
 	asciidoc -b docbook -d manpage -f asciidoc.conf $<
 
 git.html: git.txt README
 
-glossary.html : glossary.txt sort_glossary.pl
+glossary.html : glossary.txt sort_glossary.pl asciidoc.conf
 	cat $< | \
 	perl sort_glossary.pl | \
 	asciidoc -b xhtml11 - > glossary.html

@@ -97,12 +97,12 @@ howto-index.txt: howto-index.sh $(wildca
 	sh ./howto-index.sh $(wildcard howto/*.txt) >$@+
 	mv $@+ $@
 
-$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
+$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt asciidoc.conf
 	asciidoc -b xhtml11 $*.txt
 
 WEBDOC_DEST = /pub/software/scm/git/docs
 
-$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
+$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt asciidoc.conf
 	rm -f $@+ $@
 	sed -e '1,/^$$/d' $? | asciidoc -b xhtml11 - >$@+
 	mv $@+ $@

Signature · 1 line

Jonas Fonseca

Alp Toker

author

2016-06-15 22:42 UTC #7 lore raw

Re: [PATCH] urls.txt: Use substitution to escape square brackets

In reply to Junio C Hamano

Quoted 15 lines · Junio C Hamano

Alp is right -- the comments in [attributes] section after the definition do appear in the output, even with asciidoc 7.1.2, so here is a replacement proposal from me.
The one by Alp is an easy work-around, but I do not want to worry about potential, unintended, breakages that might be caused by changing delimited blocks to literal paragraphs (and it changes the resulting rendering from the original).
-- >8 --
From: Jonas Fonseca <[email protected]>
This changes "[user@]" to use {startsb} and {endsb} to insert [ and ], similar to how {caret} is used in git-rev-parse.txt.

Quoted 8 lines

[jc: Removed a well-intentioned comment that broke the final
formatting from the original patch. While we are at it, updated the paragraph that claims to be equivalent to the section that was updated earlier without making matching changes.]
Signed-off-by Jonas Fonseca <[email protected]>
Signed-off-by Junio C Hamano <[email protected]>

Signed-off-by Alp Toker <[email protected]>

Junio C Hamano

2016-06-15 22:42 UTC #8 lore raw

Re: [PATCH] urls.txt: Use substitution to escape square brackets

In reply to Jonas Fonseca

Quoted 4 lines · Jonas Fonseca

This changes "[user@]" to use {startsb} and {endsb} to insert [ and ], similar to how {caret} is used in git-rev-parse.txt.
Signed-off-by Jonas Fonseca <[email protected]>

Looks nicer. Alp? Does this work with your version of asciidoc?

Alp Toker

author

2016-06-15 22:42 UTC #9 lore raw

Re: [PATCH] urls.txt: Use substitution to escape square brackets

Quoted 9 lines · Junio C Hamano

Quoted 4 lines · Jonas Fonseca
This changes "[user@]" to use {startsb} and {endsb} to insert [ and ], similar to how {caret} is used in git-rev-parse.txt.
Signed-off-by Jonas Fonseca <[email protected]>
Looks nicer. Alp? Does this work with your version of asciidoc?

I'm using asciidoc 7.0.2, which came with Ubuntu Dapper.

The man page output now looks like this:

       ·  ssh://[ # [user@] # ]host.xz/path/to/repo.git/
       ·  ssh://[ # [user@] # ]host.xz/~user/path/to/repo.git/
       ·  ssh://[ # [user@] # ]host.xz/~/path/to/repo.git

Still not correct.

Out of the three patches,

(at) "ssh://[user@]host.xz/path/to/repo.git/" (jc) "ssh://+++[user@+++]host.xz/path/to/repo.git/" (jf) "ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/"

I'd say (at) is still most readable, not requiring +++ markup (jc) or hacks to asciidoc.conf (jf). And it's the only fix that's compatible with older versions.

That's unless I've missed out on some detail that makes (at) unworkable.
If it's the dozen or so modified lines that are a problem, we can work
on a wdiff merge strategy or something in the time we save looking for the asciidoc escape sequence that works for everyone. Junio?

Junio C Hamano

2016-06-15 22:42 UTC #10 lore raw

Re: [PATCH] urls.txt: Use substitution to escape square brackets

Quoted 5 lines · Alp Toker

Quoted 3 lines · Junio C Hamano
Looks nicer. Alp? Does this work with your version of asciidoc?

Quoted 7 lines

I'm using asciidoc 7.0.2, which came with Ubuntu Dapper.
The man page output now looks like this:
       ·  ssh://[ # [user@] # ]host.xz/path/to/repo.git/
       ·  ssh://[ # [user@] # ]host.xz/~user/path/to/repo.git/
       ·  ssh://[ # [user@] # ]host.xz/~/path/to/repo.git

I got a bit inventive and removed the comments after #, which were in Jonas's version, when I tried it out. Maybe doing the same might help you, since I suspect the above '#' are coming from the comment part.

Quoted 8 lines

Out of the three patches,
(at) "ssh://[user@]host.xz/path/to/repo.git/" (jc) "ssh://+++[user@+++]host.xz/path/to/repo.git/" (jf) "ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/"
I'd say (at) is still most readable, not requiring +++ markup (jc) or hacks to asciidoc.conf (jf).

I do not think defining [attribute] is a hack; it is a documented feature.

Alp Toker

author

2016-06-15 22:42 UTC #11 lore raw

Re: [PATCH] urls.txt: Use substitution to escape square brackets

Quoted 9 lines · Junio C Hamano

Quoted 7 lines · Alp Toker
Quoted 2 lines · Junio C Hamano
Looks nicer. Alp? Does this work with your version of asciidoc?
I'm using asciidoc 7.0.2, which came with Ubuntu Dapper.
The man page output now looks like this:

Quoted 8 lines

Quoted 3 lines
       ·  ssh://[ # [user@] # ]host.xz/path/to/repo.git/
       ·  ssh://[ # [user@] # ]host.xz/~user/path/to/repo.git/
       ·  ssh://[ # [user@] # ]host.xz/~/path/to/repo.git
I got a bit inventive and removed the comments after #, which were in Jonas's version, when I tried it out. Maybe doing the same might help you, since I suspect the above '#' are coming from the comment part.

No. Removing the comments doesn't help -- the output remains broken.

Quoted 11 lines

Quoted 8 lines
Out of the three patches,
(at) "ssh://[user@]host.xz/path/to/repo.git/" (jc) "ssh://+++[user@+++]host.xz/path/to/repo.git/" (jf) "ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/"
I'd say (at) is still most readable, not requiring +++ markup (jc) or hacks to asciidoc.conf (jf).
I do not think defining [attribute] is a hack; it is a documented feature.

"You write an AsciiDoc document the same way you would write a normal text document, there are no markup tags or weird format notations."

asciidoc solves this problem by design and without markup, with the prescribed syntax being to indent and quote the text verbatim, just as it was meant to be read.

Why try to fit a square peg in a round hole by defining attributes? It's a good indicator that there's a hack going down when three competent programmers can't escape a square bracket after three attempts spanning
two days ;-)