Asciidoc vs markdown: miniidoc

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

Asciidoc vs markdown: miniidoc

Emmanuel Bernard
I ranted about Asciidoc syntax being way too complicated for what I really want especially compared to Markdown. So as expected Dan asked me to lay out my reasons.
I'll try and do in (or part of it) here but generally my main concern is that in Asciidoc, there are often 2 or more ways to do things which leads to a harder syntax to remember and inconsistencies between authors in documents. If somehow, asciidoctor could encourage (with a flag) a subset of the asciidoctor syntax miniidoc, that would probably fix my issues (assuming people go for it :)

* _for underlined_ (no 'underlined')
* `monospace` (no +monospace+)
* Still trying to grok what a (un)constraint quote is
* super script / subscript might need a more generic syntax to not use specific characters [superscript]#Underline text#
* The + char at the end of a line to do a break feels dangerous to me. I like the double space that Markdown uses as it's easier to read.
* Get rid of two lines titles as you need to remember the magic character to mark the section level
* Get rid of NOTE: and enforce [NOTE]
* How many block types and associated special char repetition does it take to delimit a block (comment, passthrough, listing, literal, sidebar, ...) WTF! One way to declare block plus some [literal] thingy seems clearer for everyone - that's open blocks afaiu. And generally less types of blocks would be better but I partially understand why there are several ones
* I never really found the niche for labeled lists and Q&A special formatting compared to using the general syntax
* one way to do anchor, one way to do xref the [[id,xreflabel]] and the xref:id[caption] seems the most natural
* pass, +++, $$ etc are way over my head at the moment.

Don't get me wrong, there are lots of things I like in ascii doc (doc reference, ids, block titles, callouts etc) but the main advantage of Markdown was that you got in in 5 mins for 80% of your use cases. And if not the doc is three screens long. a miniidoc might find a sweet spot.
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

asotobu
I am going to give my opinion on some of Emmanuel points inline:

Emmanuel Bernard wrote
I ranted about Asciidoc syntax being way too complicated for what I really want especially compared to Markdown. So as expected Dan asked me to lay out my reasons.
I'll try and do in (or part of it) here but generally my main concern is that in Asciidoc, there are often 2 or more ways to do things which leads to a harder syntax to remember and inconsistencies between authors in documents. If somehow, asciidoctor could encourage (with a flag) a subset of the asciidoctor syntax miniidoc, that would probably fix my issues (assuming people go for it :)

* _for underlined_ (no 'underlined')

I agree that having two ways to do things could be hard to remember, but also it is on AsciiDoc original specs, so I think that removing one of them could be a disaster for some people who are using it. Maybe in Asciidoctor guide we can encourage people to use only one, or only name one.

* `monospace` (no +monospace+)

Same as before, but I think it would be better the + symbol than the ` symbol. I don't know what's happen with other keyboard mappings, but in case of the Spanish one, the + symbol is generated by only pushing one time the (+ key) but for the ` character you should push twice the (` key), so I think that (of course because I am in Spain) would be more comfortable.

* Still trying to grok what a (un)constraint quote is
* super script / subscript might need a more generic syntax to not use specific characters [superscript]#Underline text#

I like the use of ^ and ~ I think that the use of ^ as upper is quite extended in math world.

* The + char at the end of a line to do a break feels dangerous to me. I like the double space that Markdown uses as it's easier to read.

* Get rid of two lines titles as you need to remember the magic character to mark the section level

* Get rid of NOTE: and enforce [NOTE]

For me it is more readable and maybe easy to understand/remember the AsciiDoc form rather than using brackets. Maybe we should put brackets everywhere, or no where, but not mixing both syntax. In my case I prefer to not put brackets because it is less markable and more "natural".

* How many block types and associated special char repetition does it take to delimit a block (comment, passthrough, listing, literal, sidebar, ...) WTF! One way to declare block plus some [literal] thingy seems clearer for everyone - that's open blocks afaiu. And generally less types of blocks would be better but I partially understand why there are several ones
* I never really found the niche for labeled lists and Q&A special formatting compared to using the general syntax
* one way to do anchor, one way to do xref the [[id,xreflabel]] and the xref:id[caption] seems the most natural
* pass, +++, $$ etc are way over my head at the moment.

Don't get me wrong, there are lots of things I like in ascii doc (doc reference, ids, block titles, callouts etc) but the main advantage of Markdown was that you got in in 5 mins for 80% of your use cases. And if not the doc is three screens long. a miniidoc might find a sweet spot.
I totally agree that having two ways the do the same can be a  bit confusing, but instead of restrict both forms, maybe we could do pedagogy and with time, second forms would become deprecated.

Alex.
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

Emmanuel Bernard
On Tue 2013-06-04  6:24, asotobu [via Asciidoctor :: Discussion] wrote:

>
>
> I am going to give my opinion on some of Emmanuel points inline:
>
>
> Emmanuel Bernard wrote
> > I ranted about Asciidoc syntax being way too complicated for what I really
> > want especially compared to Markdown. So as expected Dan asked me to lay
> > out my reasons.
> > I'll try and do in (or part of it) here but generally my main concern is
> > that in Asciidoc, there are often 2 or more ways to do things which leads
> > to a harder syntax to remember and inconsistencies between authors in
> > documents. If somehow, asciidoctor could encourage (with a flag) a subset
> > of the asciidoctor syntax miniidoc, that would probably fix my issues
> > (assuming people go for it :)
> >
> > * _for underlined_ (no 'underlined')
> >
> > I agree that having two ways to do things could be hard to remember, but
> > also it is on AsciiDoc original specs, so I think that removing one of
> > them could be a disaster for some people who are using it. Maybe in
> > Asciidoctor guide we can encourage people to use only one, or only name
> > one.
> >
> > * `monospace` (no +monospace+)
> >
> > Same as before, but I think it would be better the + symbol than the `
> > symbol. I don't know what's happen with other keyboard mappings, but in
> > case of the Spanish one, the + symbol is generated by only pushing one
> > time the (+ key) but for the ` character you should push twice the (`
> > key), so I think that (of course because I am in Spain) would be more
> > comfortable.
> >
> > * Still trying to grok what a (un)constraint quote is
> > * super script / subscript might need a more generic syntax to not use
> > specific characters [superscript]#Underline text#
> >
> > I like the use of ^ and ~ I think that the use of ^ as upper is quite
> > extended in math world.
> >
> > * The + char at the end of a line to do a break feels dangerous to me. I
> > like the double space that Markdown uses as it's easier to read.
> >
> > * Get rid of two lines titles as you need to remember the magic character
> > to mark the section level
> >
> > * Get rid of NOTE: and enforce [NOTE]
> >
> > For me it is more readable and maybe easy to understand/remember the
> > AsciiDoc form rather than using brackets. Maybe we should put brackets
> > everywhere, or no where, but not mixing both syntax. In my case I prefer
> > to not put brackets because it is less markable and more "natural".
> >
> > * How many block types and associated special char repetition does it take
> > to delimit a block (comment, passthrough, listing, literal, sidebar, ...)
> > WTF! One way to declare block plus some [literal] thingy seems clearer for
> > everyone - that's open blocks afaiu. And generally less types of blocks
> > would be better but I partially understand why there are several ones
> > * I never really found the niche for labeled lists and Q&A special
> > formatting compared to using the general syntax
> > * one way to do anchor, one way to do xref the [[id,xreflabel]] and the
> > xref:id[caption] seems the most natural
> > * pass, +++, $$ etc are way over my head at the moment.
> >
> > Don't get me wrong, there are lots of things I like in ascii doc (doc
> > reference, ids, block titles, callouts etc) but the main advantage of
> > Markdown was that you got in in 5 mins for 80% of your use cases. And if
> > not the doc is three screens long. a miniidoc might find a sweet spot.
>
> I totally agree that having two ways the do the same can be a  bit
> confusing, but instead of restrict both forms, maybe we could do pedagogy
> and with time, second forms would become deprecated.

My personal experience is that soft approaches like that take for ever
because there is always a vocal minority somewhere that has been
ignoring warnings and raise hell when you ask if it's ok to remove the
10 year old deprecated option :)
That's part of the reason why a subset of asciidoc is cleaner I think.
But that's just an idea thrown at the wall to see if it sticks.

Emmanuel
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

asotobu
I am sure that in this field you have got much more experience than me :D
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

mojavelinux
Administrator
In reply to this post by Emmanuel Bernard
Emmanuel,

Thank you for taking the time to share this feedback! It's tremendously useful for understanding how AsciiDoc suits writers and to help shape the future of AsciiDoc.

You'll be happy to know that many of the points you raised touch on areas of the AsciiDoc syntax that bother me as well. I have always planned to address those bothers.

I'll go through each of your points to give you and idea of how I propose we address them.

On Tue, Jun 4, 2013 at 1:50 AM, Emmanuel Bernard wrote:

* Still trying to grok what a (un)constraint quote is 

Very simple. Constrained means "around a word". Unconstrained means "anywhere". (I'll add that wording to the reference guide).

The difference offers two levels of aggressiveness w/ matching. One of the main complaints in Markdown (see Tom's comment in this gist: https://github.com/mojombo/github-flavored-markdown/issues/1) is that the formatting characters match in places they shouldn't. AsciiDoc requires you to be explicit when you are formatting in the middle of a word (e.g., **B**old instead of *B*old).

* _for underlined_ (no 'underlined') 

I think you mean "for italic". I agree having both options is a mistake. I think the single quote form is inappropriate and should be deprecated. Three reasons:

1. Using single quotes for italic is not what people expect (and could format text meant to be in single quotes)
2. The single quote doesn't have an unconstrained equivalent, so you have to switch to the underscores anyway
3. Underscore is consistent w/ Markdown

I can add a deprecation warning for the single quote form in Asciidoctor.
 
* `monospace` (no +monospace+)

There is actually an important distinction here. The plus form simply wraps the text in monospaced (code) font. The backticks prevent the text from being formatted in any way (called a passthrough). Thus, you can write `{no-such-attribute}` and it would appear as <code>{no-such-attribute}</code> instead of causing the line to be dropped because of a missing attribute.

The mistake I see here is that the two forms should have been reversed. Two reasons:

1. Markdown and other languages have popularized the use of backtick for inline monospace text, so that should be default choice in AsciiDoc
2. Pluses are used elsewhere in AsciiDoc to mark passthroughs (++++ for passthrough blocks and +++ for inline passthroughs w/o formatting), so that convention should be carried out

I'm thinking about introducing a flag in Asciidoctor that allows you to reverse these forms. It would also necessitate introducing a double backtick for unconstrained monospace formatting (e.g., ``Int``s) and probably dropping the double plus (or requiring double plus and dropping the single plus)

This is the most breaking change, so it's going to be the most controversial.
 
* super script / subscript might need a more generic syntax to not use specific characters [superscript]#Underline text#

I think the problem here is that superscript and subscript only have unconstrained forms (matches anywhere). This has been causing me some problems lately as well and I'm strongly considering making ^ and ~ constrained quotes and introducing ^^ and ~~ for unconstrained (or just not having them in favor of other approaches).

(As for the URL problem you had, I don't think people should be making URLs that include ^ and ~. Nexus is being stupid).
 
* The + char at the end of a line to do a break feels dangerous to me. I like the double space that Markdown uses as it's easier to read.

I like AsciiDoc's approach *because* its visible. How can you see a double space at the end of a line?

There is a secondary issue here, which is whether line breaks should be preserved in the output. GitHub believes they should be. I'm not in that camp. But there is a feature in Asciidoctor to toggle this behavior for a region of the document.

:hardbreaks:

Roses are red,
violets are blue.

:hardbreaks!:

I'm planning on adding this as an attribute for a paragraph as well, meaning:

[options="hardbreaks"]
Roses are red,
violets are blue.

(or something similar, like [literatim]) <- means letter by letter
 
* Get rid of two lines titles as you need to remember the magic character to mark the section level

I *absolutely* agree. You'll notice we don't even mention it in the documentation on asciidoctor.org. I'm happy to add a deprecation warning when they are used. I'll make this the first change I introduce :)
 
* Get rid of NOTE: and enforce [NOTE]

I disagree. I much prefer the inline version, which I always use unless I need to include block content. Less characters and lines is better, IMHO).

NOTE: This is how I format my notes.

feels more natural than

[NOTE]
This is how I format my notes.
 
* How many block types and associated special char repetition does it take to delimit a block (comment, passthrough, listing, literal, sidebar, ...) WTF! One way to declare block plus some [literal] thingy seems clearer for everyone - that's open blocks afaiu. And generally less types of blocks would be better but I partially understand why there are several ones

This really comes down to a legacy issue. Open blocks were introduced later in the development of the AsciiDoc syntax. In general, I agree, open blocks should be used whenever possible (with the exception of block comments, which are natural for developers). There are three reasons for using the dedicated delimiters:

1. Syntax highlighters recognize them, whereas they don't recognized [literal] over an open block
2. GitHub rendering doesn't honor the block style on open blocks until they upgrade Asciidoctor (they are currently on 0.1.0); we are playing it conservative until then
3. Open blocks cannot be nested, whereas blocks w/ dedicated delimiters can (either because the delimiters of the two blocks differ or by varying the length). It's useful in a pinch.
 
* I never really found the niche for labeled lists and Q&A special formatting compared to using the general syntax

Like many other people, I think labeled lists are incredibly useful (a major missing feature from Markdown). As to whether you need the specialized style (e.g., [qanda], [glossary], etc), I'd say "only for publications", such as books). These styles are critical for that domain. But outside of that domain, keep it simple.
 
* one way to do anchor, one way to do xref the [[id,xreflabel]] and the xref:id[caption] seems the most natural

I agree. Again, Asciidoctor can advocate for the preferred syntax in these cases and throw deprecation when the alternatives are used. Personally, I like [[id,xreflabel]] and <<id,xreflabel>> as they have a complementary form.
 
* pass, +++, $$ etc are way over my head at the moment.

Then you need not worry about them :) We can also do a better job of documenting them on asciidoctor.org, so I'll take that as the action item here.
 

Don't get me wrong, there are lots of things I like in ascii doc (doc reference, ids, block titles, callouts etc) but the main advantage of Markdown was that you got in in 5 mins for 80% of your use cases. And if not the doc is three screens long. a miniidoc might find a sweet spot.
 
... generally my main concern is that in Asciidoc, there are often 2 or more ways to do things which leads to a harder syntax to remember and inconsistencies between authors in documents. If somehow, asciidoctor could encourage (with a flag) a subset of the asciidoctor syntax miniidoc, that would probably fix my issues (assuming people go for it :)

The solution here is not "minidoc", but rather an AsciiDoc spec (standard AsciiDoc). Markdown went through this and it paid off. I think its time for AsciiDoc to do it. To kick it off, I'm going to create a page on the wiki where we can begin to itemize the preferred syntax for a spec.

Understand that the goal of the Asciidoctor project is not to simply advocate for the AsciiDoc syntax as is, but to advance it, both in Asciidoctor and upstream. I want AsciiDoc to be pure joy for writers. I'm not happy until you're happy. Part of advancing a syntax is deprecation, so I'm certainly open to it.

The main reason for all of the fragmentation in Markdown (GitHub-flavored Markdown, pandoc Markdown, PHP Markdown Extra, MultiMarkdown, etc.) is a result of the creator believing that Markdown should not be changed. Change will happen. Software must evolve and adapt.

Thanks again!!

-Dan

--
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

mojavelinux
Administrator
In reply to this post by Emmanuel Bernard
Here's the wiki page to track these recommendations:


I'll also create issues in Asciidoctor to add the deprecation warnings. I'll be sure to add a flag that disables the deprecation messages as well :) Something like :deprecations: (warn|enforce|none).

-Dan


On Tue, Jun 4, 2013 at 1:05 PM, Dan Allen <[hidden email]> wrote:
Emmanuel,

Thank you for taking the time to share this feedback! It's tremendously useful for understanding how AsciiDoc suits writers and to help shape the future of AsciiDoc.

You'll be happy to know that many of the points you raised touch on areas of the AsciiDoc syntax that bother me as well. I have always planned to address those bothers.

I'll go through each of your points to give you and idea of how I propose we address them.

On Tue, Jun 4, 2013 at 1:50 AM, Emmanuel Bernard wrote:

* Still trying to grok what a (un)constraint quote is 

Very simple. Constrained means "around a word". Unconstrained means "anywhere". (I'll add that wording to the reference guide).

The difference offers two levels of aggressiveness w/ matching. One of the main complaints in Markdown (see Tom's comment in this gist: https://github.com/mojombo/github-flavored-markdown/issues/1) is that the formatting characters match in places they shouldn't. AsciiDoc requires you to be explicit when you are formatting in the middle of a word (e.g., **B**old instead of *B*old).

* _for underlined_ (no 'underlined') 

I think you mean "for italic". I agree having both options is a mistake. I think the single quote form is inappropriate and should be deprecated. Three reasons:

1. Using single quotes for italic is not what people expect (and could format text meant to be in single quotes)
2. The single quote doesn't have an unconstrained equivalent, so you have to switch to the underscores anyway
3. Underscore is consistent w/ Markdown

I can add a deprecation warning for the single quote form in Asciidoctor.
 
* `monospace` (no +monospace+)

There is actually an important distinction here. The plus form simply wraps the text in monospaced (code) font. The backticks prevent the text from being formatted in any way (called a passthrough). Thus, you can write `{no-such-attribute}` and it would appear as <code>{no-such-attribute}</code> instead of causing the line to be dropped because of a missing attribute.

The mistake I see here is that the two forms should have been reversed. Two reasons:

1. Markdown and other languages have popularized the use of backtick for inline monospace text, so that should be default choice in AsciiDoc
2. Pluses are used elsewhere in AsciiDoc to mark passthroughs (++++ for passthrough blocks and +++ for inline passthroughs w/o formatting), so that convention should be carried out

I'm thinking about introducing a flag in Asciidoctor that allows you to reverse these forms. It would also necessitate introducing a double backtick for unconstrained monospace formatting (e.g., ``Int``s) and probably dropping the double plus (or requiring double plus and dropping the single plus)

This is the most breaking change, so it's going to be the most controversial.
 
* super script / subscript might need a more generic syntax to not use specific characters [superscript]#Underline text#

I think the problem here is that superscript and subscript only have unconstrained forms (matches anywhere). This has been causing me some problems lately as well and I'm strongly considering making ^ and ~ constrained quotes and introducing ^^ and ~~ for unconstrained (or just not having them in favor of other approaches).

(As for the URL problem you had, I don't think people should be making URLs that include ^ and ~. Nexus is being stupid).
 
* The + char at the end of a line to do a break feels dangerous to me. I like the double space that Markdown uses as it's easier to read.

I like AsciiDoc's approach *because* its visible. How can you see a double space at the end of a line?

There is a secondary issue here, which is whether line breaks should be preserved in the output. GitHub believes they should be. I'm not in that camp. But there is a feature in Asciidoctor to toggle this behavior for a region of the document.

:hardbreaks:

Roses are red,
violets are blue.

:hardbreaks!:

I'm planning on adding this as an attribute for a paragraph as well, meaning:

[options="hardbreaks"]
Roses are red,
violets are blue.

(or something similar, like [literatim]) <- means letter by letter
 
* Get rid of two lines titles as you need to remember the magic character to mark the section level

I *absolutely* agree. You'll notice we don't even mention it in the documentation on asciidoctor.org. I'm happy to add a deprecation warning when they are used. I'll make this the first change I introduce :)
 
* Get rid of NOTE: and enforce [NOTE]

I disagree. I much prefer the inline version, which I always use unless I need to include block content. Less characters and lines is better, IMHO).

NOTE: This is how I format my notes.

feels more natural than

[NOTE]
This is how I format my notes.
 
* How many block types and associated special char repetition does it take to delimit a block (comment, passthrough, listing, literal, sidebar, ...) WTF! One way to declare block plus some [literal] thingy seems clearer for everyone - that's open blocks afaiu. And generally less types of blocks would be better but I partially understand why there are several ones

This really comes down to a legacy issue. Open blocks were introduced later in the development of the AsciiDoc syntax. In general, I agree, open blocks should be used whenever possible (with the exception of block comments, which are natural for developers). There are three reasons for using the dedicated delimiters:

1. Syntax highlighters recognize them, whereas they don't recognized [literal] over an open block
2. GitHub rendering doesn't honor the block style on open blocks until they upgrade Asciidoctor (they are currently on 0.1.0); we are playing it conservative until then
3. Open blocks cannot be nested, whereas blocks w/ dedicated delimiters can (either because the delimiters of the two blocks differ or by varying the length). It's useful in a pinch.
 
* I never really found the niche for labeled lists and Q&A special formatting compared to using the general syntax

Like many other people, I think labeled lists are incredibly useful (a major missing feature from Markdown). As to whether you need the specialized style (e.g., [qanda], [glossary], etc), I'd say "only for publications", such as books). These styles are critical for that domain. But outside of that domain, keep it simple.
 
* one way to do anchor, one way to do xref the [[id,xreflabel]] and the xref:id[caption] seems the most natural

I agree. Again, Asciidoctor can advocate for the preferred syntax in these cases and throw deprecation when the alternatives are used. Personally, I like [[id,xreflabel]] and <<id,xreflabel>> as they have a complementary form.
 
* pass, +++, $$ etc are way over my head at the moment.

Then you need not worry about them :) We can also do a better job of documenting them on asciidoctor.org, so I'll take that as the action item here.
 

Don't get me wrong, there are lots of things I like in ascii doc (doc reference, ids, block titles, callouts etc) but the main advantage of Markdown was that you got in in 5 mins for 80% of your use cases. And if not the doc is three screens long. a miniidoc might find a sweet spot.
 
... generally my main concern is that in Asciidoc, there are often 2 or more ways to do things which leads to a harder syntax to remember and inconsistencies between authors in documents. If somehow, asciidoctor could encourage (with a flag) a subset of the asciidoctor syntax miniidoc, that would probably fix my issues (assuming people go for it :)

The solution here is not "minidoc", but rather an AsciiDoc spec (standard AsciiDoc). Markdown went through this and it paid off. I think its time for AsciiDoc to do it. To kick it off, I'm going to create a page on the wiki where we can begin to itemize the preferred syntax for a spec.

Understand that the goal of the Asciidoctor project is not to simply advocate for the AsciiDoc syntax as is, but to advance it, both in Asciidoctor and upstream. I want AsciiDoc to be pure joy for writers. I'm not happy until you're happy. Part of advancing a syntax is deprecation, so I'm certainly open to it.

The main reason for all of the fragmentation in Markdown (GitHub-flavored Markdown, pandoc Markdown, PHP Markdown Extra, MultiMarkdown, etc.) is a result of the creator believing that Markdown should not be changed. Change will happen. Software must evolve and adapt.

Thanks again!!

-Dan

--



--
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

mojavelinux
Administrator
In reply to this post by Emmanuel Bernard
I think we can take a phased approach here. One way is to start issuing deprecations by default, or even enforce by default. At the same time, we can give the writer the option to control the deprecations (warn, enforce or allow).

I'm not going to play the game that the "Java stewards" play of leaving deprecated syntax in indefinitely. You get a few cycles to make adjustments and then you either change or just use an old version.

-Dan


On Tue, Jun 4, 2013 at 7:40 AM, Emmanuel Bernard [via Asciidoctor :: Discussion] <[hidden email]> wrote:
On Tue 2013-06-04  6:24, asotobu [via Asciidoctor :: Discussion] wrote:

>
>
> I am going to give my opinion on some of Emmanuel points inline:
>
>
> Emmanuel Bernard wrote
> > I ranted about Asciidoc syntax being way too complicated for what I really
> > want especially compared to Markdown. So as expected Dan asked me to lay
> > out my reasons.
> > I'll try and do in (or part of it) here but generally my main concern is
> > that in Asciidoc, there are often 2 or more ways to do things which leads
> > to a harder syntax to remember and inconsistencies between authors in
> > documents. If somehow, asciidoctor could encourage (with a flag) a subset
> > of the asciidoctor syntax miniidoc, that would probably fix my issues
> > (assuming people go for it :)
> >
> > * _for underlined_ (no 'underlined')
> >
> > I agree that having two ways to do things could be hard to remember, but
> > also it is on AsciiDoc original specs, so I think that removing one of
> > them could be a disaster for some people who are using it. Maybe in
> > Asciidoctor guide we can encourage people to use only one, or only name
> > one.
> >
> > * `monospace` (no +monospace+)
> >
> > Same as before, but I think it would be better the + symbol than the `
> > symbol. I don't know what's happen with other keyboard mappings, but in
> > case of the Spanish one, the + symbol is generated by only pushing one
> > time the (+ key) but for the ` character you should push twice the (`
> > key), so I think that (of course because I am in Spain) would be more
> > comfortable.
> >
> > * Still trying to grok what a (un)constraint quote is
> > * super script / subscript might need a more generic syntax to not use
> > specific characters [superscript]#Underline text#
> >
> > I like the use of ^ and ~ I think that the use of ^ as upper is quite
> > extended in math world.
> >
> > * The + char at the end of a line to do a break feels dangerous to me. I
> > like the double space that Markdown uses as it's easier to read.
> >
> > * Get rid of two lines titles as you need to remember the magic character
> > to mark the section level
> >
> > * Get rid of NOTE: and enforce [NOTE]
> >
> > For me it is more readable and maybe easy to understand/remember the
> > AsciiDoc form rather than using brackets. Maybe we should put brackets
> > everywhere, or no where, but not mixing both syntax. In my case I prefer
> > to not put brackets because it is less markable and more "natural".
> >
> > * How many block types and associated special char repetition does it take
> > to delimit a block (comment, passthrough, listing, literal, sidebar, ...)
> > WTF! One way to declare block plus some [literal] thingy seems clearer for
> > everyone - that's open blocks afaiu. And generally less types of blocks
> > would be better but I partially understand why there are several ones
> > * I never really found the niche for labeled lists and Q&A special
> > formatting compared to using the general syntax
> > * one way to do anchor, one way to do xref the [[id,xreflabel]] and the
> > xref:id[caption] seems the most natural
> > * pass, +++, $$ etc are way over my head at the moment.
> >
> > Don't get me wrong, there are lots of things I like in ascii doc (doc
> > reference, ids, block titles, callouts etc) but the main advantage of
> > Markdown was that you got in in 5 mins for 80% of your use cases. And if
> > not the doc is three screens long. a miniidoc might find a sweet spot.
>
> I totally agree that having two ways the do the same can be a  bit
> confusing, but instead of restrict both forms, maybe we could do pedagogy
> and with time, second forms would become deprecated.
My personal experience is that soft approaches like that take for ever
because there is always a vocal minority somewhere that has been
ignoring warnings and raise hell when you ask if it's ok to remove the
10 year old deprecated option :)
That's part of the reason why a subset of asciidoc is cleaner I think.
But that's just an idea thrown at the wall to see if it sticks.

Emmanuel



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Asciidoc-vs-markdown-miniidoc-tp269p273.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

mojavelinux
Administrator
In reply to this post by Emmanuel Bernard

On Tue, Jun 4, 2013 at 1:50 AM, Emmanuel Bernard [via Asciidoctor :: Discussion] <[hidden email]> wrote:
but the main advantage of Markdown was that you got in in 5 mins for 80% of your use cases.

There is something I wanted to mention regarding the myth that the Markdown syntax is simple.

URLs:

Markdown: [Asciidoctor](http://asciidoctor.org)
AsciiDoc: http://asciidoctor.org[Asciidoctor]

Markdown requires more symbols, and remembering the order and which symbols to use for the URL and text confuses the hell out of me. AsciiDoc is a clear winner here, IMO.

Formatted text:

Markdown: **Bold text**
AsciiDoc: *Bold text*

AsciiDoc wins with less characters. As a bonus, AsciiDoc actually addresses the issue of formatting in the middle of a word vs formatting a whole phrase.

Admonitions:

Markdown: <div class="note warning"><h5>Warning</h5><p>Be aware of these messages if you wish to avoid certain death.</p></div>
AsciiDoc: WARNING: Be aware of these messages if you wish to avoid certain death.

Oops, Markdown has no support and thus ties you to HTML!

Labeled lists:

Markdown: <dl><dt>Term</dt><dd>Definition</dd></dl> (or use a non-standard Markdown
AsciiDoc: Term:: Definition

Include files:

Markdown: nope
AsciiDoc: yep

Literal text:

Markdown: 4 leading spaces
AsciiDoc: 1 leading space, a styled paragraph or a delimited block

Markdown requires more banging on the spacebar.

Block quotes:

Markdown: > in front of every line
AsciiDoc: [quote] above paragraph or a delimited block

Markdown requires you to do a lot of fixing.

In the end, what I'm saying is that the Markdown syntax really isn't less complicated than the AsciiDoc syntax. That's why I choose AsciiDoc and I think it's the right investment.

-Dan
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

snowolfe
In reply to this post by mojavelinux
I absolutely agree, we need to put a more formal specification in place, and allow for evolution of that specification.

Regarding the difference between AsciiDoc and markdown - One VERY significant difference between the two styles is that markdown is primarily about embedding style/formatting in to the text, with one primary use case - richly formatted HTML, whereas, AsciiDoc is about embedding metadata with the text such that the text becomes reusable in a range of use cases, not just HTML output.

I think it is important to remember that AsciiDoc was initially designed to be a plain text subset of DocBook metadata, and I think that is still a primary use case for AsciiDoc. However, it should also be simple enough to be a "better" version of markdown (and I would argue it already is), thereby fulfilling the the re-usability of the written text. In that regard, there maybe a good argument for a minidoc that focuses on showing markdown users how to do the same "formatting" in AsciiDoc, but it should emphasise that AsciiDoc has much more to offer.
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

mojavelinux
Administrator
On Thu, Jun 6, 2013 at 12:27 AM, snowolfe [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I absolutely agree, we need to put a more formal specification in place, and allow for evolution of that specification.

Indeed. I am hoping that I will be given the opportunity in the near future to dedicate time to being part of a specification working group.
 

Regarding the difference between AsciiDoc and markdown - One VERY significant difference between the two styles is that markdown is primarily about embedding style/formatting in to the text, with one primary use case - richly formatted HTML, whereas, AsciiDoc is about embedding metadata with the text such that the text becomes reusable in a range of use cases, not just HTML output.

Very well stated.
 


I think it is important to remember that AsciiDoc was initially designed to be a plain text subset of DocBook metadata, and I think that is still a primary use case for AsciiDoc. However, it should also be simple enough to be a "better" version of markdown (and I would argue it already is), thereby fulfilling the the re-usability of the written text. In that regard, there maybe a good argument for a minidoc that focuses on showing markdown users how to do the same "formatting" in AsciiDoc, but it should emphasise that AsciiDoc has much more to offer.

Indeed. This could serve well as an abstract for the AsciiDoc vs Markdown tutorial that's on the roadmap for asciidoctor.org. Thus, the focus on the document is not narrowly focused on why AsciiDoc is superior, but rather to enable authors and content creators who are familiar with Markdown to be even more successful w/ AsciiDoc.

Thanks for sharing!

-Dan

--
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

mojavelinux
Administrator
In reply to this post by snowolfe
The topic of underline titles came up on the AsciiDoc list and Stuart Rackham (creator of AsciiDoc) chimed in with support for deprecating them:

I hugely prefer single line titles, double lined have lots of problems:
multi-byte character set alignment; have to remember to edit underline
after editing title; have to type more. To late to take them out now
though :-( I've made a note to downplay them in the manual.

In a follow-up post he downplayed this point because Lex (a frequent contributor to the list) poignantly defended their use. I still disagree with Lex and will move forward with the deprecation warnings in Asciidoctor.

Just wanted to share :)

-Dan
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

Emmanuel Bernard
On Mon 2013-06-10  2:00, mojavelinux [via Asciidoctor :: Discussion] wrote:

>
>
> The topic of underline titles came up on the AsciiDoc list and Stuart
> Rackham (creator of AsciiDoc) chimed in with support for deprecating them:
>
> I hugely prefer single line titles, double lined have lots of problems:
> > multi-byte character set alignment; have to remember to edit underline
> > after editing title; have to type more. To late to take them out now
> > though :-( I've made a note to downplay them in the manual.
>
>
> In a follow-up post he downplayed this point because Lex (a frequent
> contributor to the list) poignantly defended their use. I still disagree
> with Lex and will move forward with the deprecation warnings in Asciidoctor.
>
> Just wanted to share :)
>

Damn, we will have to bring Superman to fight Lex ;)
But it's not illogical for each solution to have proponents. The
deprecation will have to be opinionated. But as we discussed, the key
thing is one way to do one thing to keep things simple.

Emmanuel
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc vs markdown: miniidoc

victor
In reply to this post by mojavelinux
Hi Dan,

with respect to using `+` sign as syntax for line break: why not use `\n` ? This one is already known by many in computer world, and nobody will object anything to `+` being a mathematical sign.

Victor