.. include:: /include/substitutions.txt
.. include:: /include/external_links.txt
.. include:: /include/custom_roles.txt
************************
Comparison with Markdown
************************


Advantages
**********

- The flexibility of complex lists with sub-lists is not even approached by Markdown.

- The flexibility of tables is not even approached by Markdown.

- Cross-references between files is supported.  Sphinx adds capabilities to reST that
  make it even easier.

- Complex paragraphs are easy and intuitive and not well supported by Markdown.


Disadvantages
*************

- The ability to nest bold, italic and underlined text is not built in.  It can,
  however, be implemented via custom text roles.

  The workaround for this is fairly simple:

  custom.css:

  .. code-block:: css

    /*-------------------------------------------------------------------------
     * Custom Roles:  workarounds for reStructuredText parser shortcomings.
     * These use `custom_roles.txt` to set up roles using these class names.
     *
     * To use them in `.rst` files:
     * ----------------------------
     * 1.  .. include::  <doc_root>/include/custom_roles.txt
     * 2.  Use with custom roles like this:
     *         :bi:`text`
     *         :ib:`text`
     *         :u:`text`
     *         :ub:`text`
     *         :bu:`text`
     *         :ui:`text`
     *         :iu:`text`
     *         :ubi:`text`
     *         :uib:`text`
     *         :bui:`text`
     *         :iub:`text`
     *         :biu:`text`
     *         :ibu:`text`
     *
     * The above combinations were done so you don't have to remember
     * whether 'i', 'b' or 'u' comes first when they are combined.
     *-------------------------------------------------------------------------*/
    span.bi {
      font-weight: bold;
      font-style: italic;
    }
    span.ul {
      text-decoration: underline;
    }
    span.bu {
      text-decoration: underline;
      font-weight: bold;
    }
    span.iu {
      text-decoration: underline;
      font-style: italic;
    }
    span.ubi {
      text-decoration: underline;
      font-weight: bold;
      font-style: italic;
    }

  Then in a ``<doc_root>/include/custom_roles.txt`` file you include where needed
  using ``.. include:: /include/custom_roles.txt`` (or in every document if you wish
  to ensure these custom roles are always available):

  .. code-block:: text

    .. ========================================================================
    .. Workarounds for reStructuredText parser shortcomings.
    .. These use `custom.css` to set up styling using these class names.
    .. ========================================================================
    .. role:: bolditalic
        :class: bi
    .. role:: bi
        :class: bi
    .. role:: ib
        :class: bi
    .. role:: underlined
        :class: ul
    .. role:: u
        :class: ul
    .. role:: ul
        :class: ul
    .. role:: ub
        :class: bu
    .. role:: bu
        :class: bu
    .. role:: ui
        :class: iu
    .. role:: iu
        :class: iu
    .. role:: ubi
        :class: ubi
    .. role:: uib
        :class: ubi
    .. role:: bui
        :class: ubi
    .. role:: iub
        :class: ubi
    .. role:: biu
        :class: ubi
    .. role:: ibu
        :class: ubi