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

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

[Alp Toker]

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 <alp@atoker.com>
---
 Documentation/urls.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 93378d2..9abec80 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -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
-- 
1.4.1.g28ec

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

[Alp Toker]

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 <alp@atoker.com>
---
 Documentation/urls.txt |   30 ++++++++++++------------------
 1 files changed, 12 insertions(+), 18 deletions(-)

diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 9abec80..a071915 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -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
 -------
-- 
1.4.1.g28ec

[PATCH] Documentation: Minor capitalization typofix

[Alp Toker]

This ended up appearing in several man pages by inclusion.

Signed-off-by: Alp Toker <alp@atoker.com>
---
 Documentation/urls.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index a071915..2b5a7f8 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -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:
-- 
1.4.1.g28ec

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

[Junio C Hamano]

Alp Toker <alp@atoker.com> writes:

> 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):

> +	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

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

diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 93378d2..a5519e5 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -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://user@host.xz/\...` and `user@host.xz:\...` for
+the SSH protocol.
+
 To sync with a local directory, use:
 
 ===============================================================

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

[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 <fonseca@diku.dk>

---

Alternate "fix".

---

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 7ce7151..41754d5 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -9,6 +9,8 @@ # the command.
 
 [attributes]
 caret=^
+startsb=&#91; # [
+endsb=&#93;   # ]
 
 ifdef::backend-docbook[]
 [gitlink-inlinemacro]
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 93378d2..2950ac9 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -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

-- 
Jonas Fonseca

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

[Junio C Hamano]

Jonas Fonseca <fonseca@diku.dk> writes:

> 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 <fonseca@diku.dk>

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

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

[Alp Toker]

Junio C Hamano wrote:
> Jonas Fonseca <fonseca@diku.dk> writes:
> 
>> 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 <fonseca@diku.dk>
> 
> 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?

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

[Junio C Hamano]

Alp Toker <alp@atoker.com> writes:

> Junio C Hamano wrote:
>>
>> 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

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.

> 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.

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

[Alp Toker]

Junio C Hamano wrote:
> Alp Toker <alp@atoker.com> writes:
> 
>> Junio C Hamano wrote:
>>> 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
> 
> 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.

>> 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 ;-)

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

[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 <fonseca@diku.dk>

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 <fonseca@diku.dk>
Signed-off-by: Junio C Hamano <junkio@cox.net>
---
 Documentation/asciidoc.conf |    2 ++
 Documentation/urls.txt      |   17 +++++++++--------
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 7ce7151..8196d78 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -9,6 +9,8 @@ # the command.
 
 [attributes]
 caret=^
+startsb=&#91;
+endsb=&#93;
 
 ifdef::backend-docbook[]
 [gitlink-inlinemacro]
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 9d2ad46..26ecba5 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -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:
-- 
1.4.1.g28ec

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

[Alp Toker]

Junio C Hamano wrote:
> 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 <fonseca@diku.dk>
> 
> 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 <fonseca@diku.dk>
> Signed-off-by: Junio C Hamano <junkio@cox.net>

Signed-off-by: Alp Toker <alp@atoker.com>

[PATCH] Make asciidoc related rules depend on asciidoc.conf

[Jonas Fonseca]

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 <fonseca@diku.dk>
---

Junio C Hamano <junkio@cox.net> wrote Fri, Jul 14, 2006:
> 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.

---

diff --git a/Documentation/Makefile b/Documentation/Makefile
index cc83610..ce6c6cf 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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 $@+ $@
-- 
Jonas Fonseca