Re: [Launchpad-dev] Using reStructured Text instead of moin syntax in the wiki?

Barry Warsaw Sun, 13 Sep 2009 16:37:52 -0700

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

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

_______________________________________________
Mailing list: https://launchpad.net/~launchpad-dev
Post to     : [email protected]
Unsubscribe : https://launchpad.net/~launchpad-dev
More help   : https://help.launchpad.net/ListHelp

Re: [Launchpad-dev] Using reStructured Text instead of moin syntax in the wiki?

Reply via email to