Write differences between AsciiDoc and Markdown documentation #34

Closed
graphitefriction opened this Issue Apr 26, 2013 · 20 comments

Comments

Projects
None yet
6 participants
@graphitefriction
Member

graphitefriction commented Apr 26, 2013

How do the two syntaxes differ?
Partners with the Asciidoctor and AsciiDoc differences
May go under The Basics category

@lordofthejars

This comment has been minimized.

Show comment
Hide comment
@lordofthejars

lordofthejars Apr 29, 2013

Member

Also may be useful for people why they should choose AsciiDoc format instead of Markdown. I think that Markdown is widely extended, and maybe people need some solid arguments for changing to AsciiDoc.

Member

lordofthejars commented Apr 29, 2013

Also may be useful for people why they should choose AsciiDoc format instead of Markdown. I think that Markdown is widely extended, and maybe people need some solid arguments for changing to AsciiDoc.

@graphitefriction

This comment has been minimized.

Show comment
Hide comment
@graphitefriction

This comment has been minimized.

Show comment
Hide comment
@graphitefriction

graphitefriction Jun 4, 2013

Member

Notes for document per conversation with @mojavelinux

Part 1 - The case for AsciiDoc vs Markdown or what does each provide and why is AsciiDoc more compelling.
Part 2 - Side by side comparison of AsciiDoc and Markdown syntax, what equals what, what doesn't map

Resources:
Markdown index on Wikipedia
Jekyll documentation's Markdown examples
Discussion on Asciidoctor list: http://discuss.asciidoctor.org/Asciidoc-vs-markdown-miniidoc-td269.html

Member

graphitefriction commented Jun 4, 2013

Notes for document per conversation with @mojavelinux

Part 1 - The case for AsciiDoc vs Markdown or what does each provide and why is AsciiDoc more compelling.
Part 2 - Side by side comparison of AsciiDoc and Markdown syntax, what equals what, what doesn't map

Resources:
Markdown index on Wikipedia
Jekyll documentation's Markdown examples
Discussion on Asciidoctor list: http://discuss.asciidoctor.org/Asciidoc-vs-markdown-miniidoc-td269.html

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jun 6, 2013

Member

On the mailinglist, snowolfe proposed an abstract that could give this guide a strong direction:

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.

Member

mojavelinux commented Jun 6, 2013

On the mailinglist, snowolfe proposed an abstract that could give this guide a strong direction:

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.

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jun 26, 2013

Member

I like some of the points in this blog entry about why Markdown isn't the best choice (though I don't like the conclusion the author draws that reStructuredText or Creole is the solution).

http://www.wilfred.me.uk/blog/2012/07/30/why-markdown-is-not-my-favourite-language/

Member

mojavelinux commented Jun 26, 2013

I like some of the points in this blog entry about why Markdown isn't the best choice (though I don't like the conclusion the author draws that reStructuredText or Creole is the solution).

http://www.wilfred.me.uk/blog/2012/07/30/why-markdown-is-not-my-favourite-language/

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jun 26, 2013

Member

I've posted an assessment of AsciiDoc vs Markdown in the comments of the following issue as a rebuttal to the statement that AsciiDoc is too complex for simple documents. I think this is the best foundation material so far for this document.

awestruct/web-editor#12 (comment)

Member

mojavelinux commented Jun 26, 2013

I've posted an assessment of AsciiDoc vs Markdown in the comments of the following issue as a rebuttal to the statement that AsciiDoc is too complex for simple documents. I think this is the best foundation material so far for this document.

awestruct/web-editor#12 (comment)

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jun 26, 2013

Member

I've created a gist that does some side-by-side comparison of the GitHub-flavored Markdown syntax and the AsciiDoc syntax based on examples in the GitHub-flavored Markdown reference.

https://gist.github.com/mojavelinux/5870367

Member

mojavelinux commented Jun 26, 2013

I've created a gist that does some side-by-side comparison of the GitHub-flavored Markdown syntax and the AsciiDoc syntax based on examples in the GitHub-flavored Markdown reference.

https://gist.github.com/mojavelinux/5870367

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jun 26, 2013

Member

Some points about the semantic benefits of AsciiDoc over Markdown:

https://twitter.com/bphogan/status/323307796667977728

Member

mojavelinux commented Jun 26, 2013

Some points about the semantic benefits of AsciiDoc over Markdown:

https://twitter.com/bphogan/status/323307796667977728

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jun 26, 2013

Member

Feedback from various people about why AsciiDoc is a good choice. Intended primarily for reference and perhaps a few ideas.

https://groups.google.com/forum/#!topic/asciidoc/yAxV21MGbw4

Member

mojavelinux commented Jun 26, 2013

Feedback from various people about why AsciiDoc is a good choice. Intended primarily for reference and perhaps a few ideas.

https://groups.google.com/forum/#!topic/asciidoc/yAxV21MGbw4

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jun 26, 2013

Member

I am fully aware of the fragmentation in Markdown and I do not want to let
that happen with AsciiDoc. One of the main reasons it happened with Markdown
is due to an unwillingness by the original authors to change Markdown in
anyway. The AsciiDoc community is much more open to evolving the language,
so we should be able to move forward together.
-- Dan Allen

Member

mojavelinux commented Jun 26, 2013

I am fully aware of the fragmentation in Markdown and I do not want to let
that happen with AsciiDoc. One of the main reasons it happened with Markdown
is due to an unwillingness by the original authors to change Markdown in
anyway. The AsciiDoc community is much more open to evolving the language,
so we should be able to move forward together.
-- Dan Allen

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jun 26, 2013

Member

Some notes about Markdown standardization (which, from most accounts, doesn't seem to be going well).

http://tychoish.com/rhizome/markdown-standardization/
http://www.2ality.com/2012/10/future-of-markdown.html

Interesting to note that when Markdown is criticized, people tend to say that they use pandoc to work around problems or satisfy the requirements. Thus, pandoc is an interesting "competitor" to AsciiDoc, though could also be a seen as an important player in the ecosystem since it can bring documents to AsciiDoc.

Member

mojavelinux commented Jun 26, 2013

Some notes about Markdown standardization (which, from most accounts, doesn't seem to be going well).

http://tychoish.com/rhizome/markdown-standardization/
http://www.2ality.com/2012/10/future-of-markdown.html

Interesting to note that when Markdown is criticized, people tend to say that they use pandoc to work around problems or satisfy the requirements. Thus, pandoc is an interesting "competitor" to AsciiDoc, though could also be a seen as an important player in the ecosystem since it can bring documents to AsciiDoc.

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jun 26, 2013

Member

For reference, and interesting comparison between Markdown and reStructuredText (likely a lot of the same arguments about scope and semantics).

https://gist.github.com/dupuy/1855764

Member

mojavelinux commented Jun 26, 2013

For reference, and interesting comparison between Markdown and reStructuredText (likely a lot of the same arguments about scope and semantics).

https://gist.github.com/dupuy/1855764

@aheusingfeld

This comment has been minimized.

Show comment
Hide comment
@aheusingfeld

aheusingfeld Feb 16, 2014

Contributor

Hi all, is there already a more comprehensive "document" on this topic e.g. to convince stakeholders and/ or customers? :)

Contributor

aheusingfeld commented Feb 16, 2014

Hi all, is there already a more comprehensive "document" on this topic e.g. to convince stakeholders and/ or customers? :)

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Sep 16, 2014

Member

Not yet. But I'll link a couple more resources:

(not all positive, but we take feedback of all kinds!)

Member

mojavelinux commented Sep 16, 2014

Not yet. But I'll link a couple more resources:

(not all positive, but we take feedback of all kinds!)

@jaredmorgs

This comment has been minimized.

Show comment
Hide comment
@jaredmorgs

jaredmorgs Jan 22, 2016

Member

This issue has been open for about three years now. I wonder what we need to do to wrap up this issue.

Perhaps we need to take what we have and look at incorporating it into the #435 issue.

Member

jaredmorgs commented Jan 22, 2016

This issue has been open for about three years now. I wonder what we need to do to wrap up this issue.

Perhaps we need to take what we have and look at incorporating it into the #435 issue.

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Jan 25, 2016

Member

This issue and #435 are basically the same issue. This issue has actually served as a useful landing page in the interim for consolidating the discussions pertaining to the differences. The next step is to summarize that information.

Given the popularity of Markdown and, therefore, the likeliness someone is migrating from it, I'd say this is an important section / resource.

Member

mojavelinux commented Jan 25, 2016

This issue and #435 are basically the same issue. This issue has actually served as a useful landing page in the interim for consolidating the discussions pertaining to the differences. The next step is to summarize that information.

Given the popularity of Markdown and, therefore, the likeliness someone is migrating from it, I'd say this is an important section / resource.

@mojavelinux

This comment has been minimized.

Show comment
Hide comment
@mojavelinux

mojavelinux Mar 30, 2016

Member

The first draft is in thanks to @andya9!

Member

mojavelinux commented Mar 30, 2016

The first draft is in thanks to @andya9!

@mojavelinux mojavelinux assigned ghost Mar 30, 2016

@IbnSaeed

This comment has been minimized.

Show comment
Hide comment
@IbnSaeed

IbnSaeed Aug 6, 2016

where is the first draft ?

IbnSaeed commented Aug 6, 2016

where is the first draft ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment