launchpad-dev team mailing list archive

[Karl Fogel <karl.fogel@xxxxxxxxxxxxx>]

Barry Warsaw wrote in http://tinyurl.com/n7y27f:
> Thanks to our fantastic IS department, you can now use
> reStructuredText markup in our dev and help wikis.  I highly encourage
> you to use reST format instead of moin, as we're standardizing on
> Python's own de-facto standard of reST markup.

This is actually a big change, and we should think about it carefully.
Some questions (terseness does not mean I'm hostile to the change):

  1) Is reST objectively better than moin syntax in some way?  Worse?
     In other words, are there any functional differences?  (E.g., can
     we do named anchors in reST too?)

  2) Or are they really the same, it's just that we're just
     standardizing on reST?...

  3) ...if "yes" to (2), *where* are we standardizing on it?  Because
     most of the dev wiki and help wiki are in moin syntax right now. :-)

  4) Is there an automated moin->reST converter anywhere?  (I couldn't
     find one; I could only find reSt->foo.)

  5) Does idiomatic use of reST imply that our URLs would look
     different than they currently do (i.e., instead of CamelCase,
     we'd Use%20Spaces or Perhaps_Underscores or something else?)

  6) Is the fact that Python/Docutils uses reST the only thing that
     makes it better than, say, markdown or any of the zillion other
     similar systems?

We should make a decision and stick to it.  If people are going to be
sked to learn Yet Another Syntax, we should Really Mean It, and have
good reasons for meaning it.

We don't want a situation where people are just "strongly encouraged" to
use reST instead of moin, such that some people take the encouragement
while others stick with what they know, with the result that we have a
wiki with two syntaxes, and you never know what you're going to get when
you go to edit a page.  That outcome would be far, far worse than using
either syntax consistently.  But it's what we will get, unless we make a
decision, convert all our pages to that decision, and stick to it.

Just because Launchpad is written in Python doesn't necessarily mean our
wiki should use the same syntax as much Python documentation.  If
Launchpad were written in C, we wouldn't write our documentation in
nroff/troff.  (Okay, maybe that's unfair, but you see my point...)

So: why are we doing this, and do we Really Mean It?

-Karl