launchpad-dev team mailing list archive

[Barry Warsaw <barry@xxxxxxxxxxxxx>]

On Sep 12, 2009, at 12:54 AM, Karl Fogel wrote:

> 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):

Note that several months ago, we decided to convert all of our  
doctests from moin to rest.  We do this opportunistically so we still  
have a mix of pages, but there's a standing rs= approval for moin- 
>rest conversion.

>  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?)

I haven't done a feature-by-feature comparison, but I believe they are  
at least functionally equivalent.  Meaning, anything you can do in  
moin you should be able to do in rest.

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

I think rest has several advantages over moin.  There are more Python  
tools that understand rest (e.g. Sphinx), IMO rest is more readable in  
its raw plain text format, our doctests are standardized on rest (so a  
LP developer should already know it).

>  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. :-)

Right, but until this week there was no other option.  We now have the  
right software installed to enable rest syntax for wiki pages.

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

I'm not aware of one, but I think we can take the same opportunistic  
conversion approach with wiki pages that we already take with doctests.

>  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?)

We can still use CamelCase wikinames.  You have to be explicit about  
them (which I actually like), e.g. `FooBar`_

>  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?

I agree that there are way too many wiki formats in the world. ;)  I  
personally really like Confluence's format.  I'm not saying rest is  
better or worse, but I do think it makes sense to align all of our  
documentation formats to one style.

> 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.

I wouldn't disagree with that!  All new doctests should be in rest.   
If/when we write in-tree documentation for processing in Sphinx, we'll  
use rest.  Our docstrings should be rest.  It only makes sense to me  
that our wiki should be rest too.

> 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.

I don't know if we can disable moin syntax.  If it makes sense to make  
a stronger pronouncement about the wiki syntax, that's fine with me too.

> 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...)

You wanna standardize on LaTeX? :)

OTOH, it seems to me that moin is the outlier here, so let me turn the  
question around. Why should we use a different format for the wiki  
than all our other documentation?

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

See above, and yes!
-Barry

Attachment: PGP.sig
Description: This is a digitally signed message part