1. 1

I need a markup system to publish something like blog articles. The origin will be a unique file composed of text in two different languages (human languages), the destination will be two html files (one per human language.

What are you guys thoughts on:

  • ReStructuredText

  • asciidoc

  • others????



  2. 7

    Markdown is pretty much the go-to markup for text on the web these days.

    1. 3

      For X: I tend to use…

      • man pages: perl-pod or asciidoc or mdoc
      • blog posts (or site comments): markdown
      • technical documentation: ReST (sphinx) or asciidoc
      • books (no first hand experience): LeanPub uses a customized markdown; I heard O'Reilly uses asciidoc for O'Reilly Atlas
      1. 1

        Can you talk about some of the main reasons why you prefer ReST (sphinx) over markdown when writing technical documentation?

        1. 2

          ReST makes it easy to add admonitions, callout figures with captions, etc. Its strength comes from “directives”, and the ability to add/extend them.

          Sphinx builds on this extensible directives concept, and allows you to (relatively) easily cross reference other pages (inline markup :doc:), reference individual items (:ref:), and provides a means to reference pages by globbing for nice high level table of content pages. Sphinx also adds some other useful directives as well, and supports extensions which define their own directives.

          I would say that without Sphinx ReST is less appealing in its own right. If I weren’t using Sphinx, I likely wouldn’t want to actually use it. In fact, I wish there was a system like Sphinx that just used custom extensions to markdown, or even asciidoc, instead. I am not generally a fan of ReST itself.

      2. 2

        Pandoc is worth looking at; it gives you a hell of a lot of flexibility in both the input language and output format you use. It’s an incredibly powerful system that is throughly underused and unknown despite its maturity and features.

        1. 1

          This is possible with a bit of XML + XSLT (and stackoverflow)