Ondra Žižka wrote:
> I may have rare PoV, but IMO being aligned with makros doesn't make it a
> good syntax.
We all have different points of view, that's the challenge of finding a
universal syntax for writing. That said, I stand by my point that following
the macro syntax for links makes it easier to teach.
Using the link:{...} approach adds additional effort to thing that should
> be trivial - linking. 95 % of links in normal docs just need a label and
> URL.
Perhaps you are misunderstanding the syntax (or my responses misled you).
The link: prefix is only needed when you are linking to a relative
document. AsciiDoc recognizes inline links with an option label just fine.
All of the following are valid links:
* http://asciidoc.org
* http://asciidoc.org[]
* http://asciidoc.org[AsciiDoc]
Most of the time, you'll use the last one.
Not having it as easy as possible demotivates people from linking, making
> documentation worse.
I agree. Most people I've talked to about AsciiDoc have told me that
linking is easy. If they told me otherwise, then I wouldn't be defending it.
I suggest to add support for alternative link syntax, which put the text in
> front, and the human unreadable URL to the back.
I see the URL as the most significant part of the content, and thus it
should be first. Also, when designing APIs, optional parts should always
come last to make the ordering parallel. As you can see in the progression
above, we are abiding by this convention.
Lex Trotman wrote:
> I don't agree with Dan about the order (who cares if it matches the HTML
> tag order, I'm trying to not know about the HTML :)
>
I didn't mean to suggest we had to align with the HTML tag order. I was
simply stating that people who type HTML are used to this order, so it's
arguably second nature to a lot of people.
I agree that no suitable alternative has been proposed.
I don't like the Markdown syntax because it requires two sets of brackets
(square and round). People aren't going to easily remember which comes
first and which comes last. The hardest thing in the AsciiDoc syntax is to
remember that the square brackets go after the target. This is reinforced
by looking at all the other macros and seeing that the square brackets come
at the end...so it's a very strong reinforcement.
-Dan
--
Dan Allen | http://google.com/profiles/dan.j.allen
--
You received this message because you are subscribed to the Google Groups
"asciidoc" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/asciidoc.
For more options, visit https://groups.google.com/d/optout.
