fix #34 and #435

[ghost]

A first draft (mostly using Dan’s own writings on a github issue) so that the section isn’t fully empty.
Please comment =D

[mojavelinux]

Let's use the modern syntax only, so drop the +literal+ one.

[mojavelinux]

A fantastic start! I added some inline comments.

The next question to ask is, what's missing? I think it's fine to merge before it's perfect, but it's an important step for identifying the next action.

[mojavelinux]

I'd like to include a statement for the intro similar to the one proposed in #34.

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.

It's important to understand that AsciiDoc was born out of DocBook. That gives people confidence that it isn't just shooting in the dark rather than just trying to patch needs like Markdown.

We could use less words, though.

[mojavelinux]

I think there are a few missing comparisons that are covered in the following page:

https://github.com/graphitefriction/oscon-2013-docs-workshop/blob/master/convert-markdown-to-asciidoc.adoc

I also think we should link back to issue #34 for people who want to dive deeper. Even though the issue will be closed by this PR, it still holds some detail that isn't appropriate for adding to the user manual.

Say something like:

You can find more links to more discussions about the differences between AsciiDoc and Markdown in the comments of issue #34.

[ghost]

I implemented some fixes following your comments. As for what is missing, maybe some notes on tool availability?

[mojavelinux]

Thanks!

I think the discussion of tooling is out of scope. The focus of this section is really on the syntax, IMO.

[ghost]

You are right 😄

[ghost]

I added two more asciidoc only features: split source and custom css classes

[ghost]

@mojavelinux What do you think of this link by Scott Chacon? I believe it’s a beautiful proof of asciidoc’s value from a well-known actual technical writer; IMO, we should link to it; where?

[mojavelinux]

See #530.

[ghost]

Aah, I missed it 😄

[mojavelinux]

Thanks!!

Merged as 116a0ee with additional revisions in b95aa27.