launchpad-dev team mailing list archive

[Gavin Panella <gavin.panella@xxxxxxxxxxxxx>]

A while back I became exasperated at Moin's broken syntax and/or
parser, and then I rediscovered Moin's support for reST (which Barry
brought up last a couple of years ago, iirc).

I think reST takes a bit of getting used to, but once you're there
it's much easier to construct documents that don't inadvertently look
like roadkill. The source documents are also *much* easier to read and
work with, especially if you're familiar with M-q (aka fill-paragraph)
in Emacs or equivalent, something which is dangerous to use with
Moin's default syntax.

The page which caused me so much pain until I switched to reST:
  https://dev.launchpad.net/PolicyAndProcess/BugImportHowto

The source text is much easier to read and comprehend:
  https://dev.launchpad.net/PolicyAndProcess/BugImportHowto?action=raw

To have your page interpreted as reST just put "#format rst" on the
first line. Or go to https://dev.launchpad.net/GavinPanella and use
the "New reST page" form. This opens a brand new, unsaved, page with
the following useful content:

  #format rst

  ===========================
    Arg! Moin Syntax Sucks!
  ===========================

  Use `reST`_ instead. This template makes it one tiny bit easier. The
  `quick reference`_ may also come in handy.

  .. _reST: http://docutils.sourceforge.net/rst.html
  .. _quick reference:
http://docutils.sourceforge.net/docs/user/rst/quickref.html

  Simply start your page with the line::

    #format rst

  or derive from this template.

Many of you, possibly all, already know reST, so this is just a
reminder that we can use it on the dev wiki. There might well be a
burst of wiki activity during the Epic next week, so try it.

Some other reasons to use reST:

- There is good tool support for reST, rst2html and rst2pdf for
  example.

- You can write your wiki pages offline and use rst2html or rst2pdf to
  render them (or rst2odt, or rst2latex, or rst2man, ...). This is
  probably easier than running Moin.

- Another tool, Sphinx, uses reST source; see the doc/ directory in
  the Launchpad tree, and http://launchpad.readthedocs.org/. Use one
  syntax to do both wiki content and in-tree documentation.