Adjustments to markdown docs in order to get a better pandoc conversion.

[ahjohannessen]

Just for review, not intended to be merged in at this point.

I have done some minor adjustments wrt. backticks and minor format issues that caused a bit of trouble in the conversion.

Doing a

pandoc -f markdown_github+raw_html README.md -o index.rst

is more or less doing a perfect transformation - getting warnings about not using local images, but that is not a biggie to solve. I need to add some table css to the sphinx theme to get a similar setup as the on github.

[krasserm]

Is there no way to keep the code formatting? For example, using [<code>Message</code>](...) or <code>[Message](...)</code> instead of [Message](...)? I'd really like to keep the code formatting for class/trait names.

[ahjohannessen]

Yep, it looks better using code formatting. I will take a stab at it later and see if there is a way.

[ahjohannessen]

@krasserm I have investigated this and tried various ways to keep the formatting. Currently, it seems not possible to do a straight conversion that handles the embedded code formatting due to:

• http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible
• http://stackoverflow.com/questions/4743845/format-text-in-a-link-in-restructuredtext

It is possible to achieve the same effect wrt code formatting in rst as stated in the SO thread. It seems that we only have issues with formatting links, the other stuff is all good, akka docs like.

[krasserm]

@ahjohannessen thanks for your investigations. Looks like we should seriously consider switching to rst soon. Some thoughts:

• Switching to rst would also allow TOC creation out of the box (which is a bit trickier with markdown)
• We must preserve existing anchors to section titles (automatically generated by github for markdown documents) because many external links already exist. Not sure if github generates the same anchors for rst files. However, we need these anchors in the generated HTML too.
• During the next days I plan to make some major additions/changes to the user guide describing my work on branch wip-8-snapshots. I want to make these changes in markdown, merge to master and then we can start switching to rst. Otherwise, availability of snapshotting features would be deferred by documentation concerns.
• At the moment we're using inline style markdown links. Are they automatically converted to reference style links in rst during conversion or are they inlined as well? If they are inlined as well, do you think it's better to first create reference style links in markdown or later in the rst document?

I'm meanwhile fine with switching to rst. What about you @ddevore?

[ironfish]

@krasserm I'm good w/ rst.

[ahjohannessen]

@krasserm Are you about to finish off Snapshotting and related user guide changes?

• Anchors are preserved, as far as I can tell - I just tested it.
• Inline style links are transformed as is -
• Images are converted to reference style links at the bottom in the rst doc and used with |RefName|, e.g.:

|Legend| 

.. |Legend| image:: https://raw.github.com/eligosource/eventsourced/master/doc/images/legend.png

[krasserm]

@ahjohannessen I don't plan any additions to the user guide during the next couple of days.