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

From: Alp Toker <[email-masked]>
Date: Sat, 15 Jul 2006 00:57:04 +0100

Junio C Hamano wrote:
> Alp Toker <[email-masked]> 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 ;-)