[TYPO3-doc] Experiences with ReSTructured Text

[Martin Bless]

Hello everybody,
hi Sebastian,

you really make my day! The ReStructuredText method is such a cool
thing.Whenever I have a choice I take Python as my favorite
programming language. The Python people tend to create complete
solutions of superior quality. ReST ist such a thing. I think it
offers whatever can be done within the approach of "normal text markup
while keeping it human readable".

To keep it short - here are some thoughts. Just in my brains order:

* normal, plain typewriter text /is/ the easiest way of writing
WYSIWYG. It is /intended/ to be read. With the additional option of
converting it into something fancy of course ...

* I've been using ReST already years ago. As usual in the Python world
it's stable. I'm sure that texts I write that way today will work the
same in hundred years.

* Does it handle special characters like chevrons and so on? Well, it
does. It takes characters representing Unicode as input. To be more
precise: ReST doesn't know a way to NOT handle such characters. All
you have to do is to provide a text file as input. Fill in whatever
characters (=symbols) you want to while sticking to Unicode. Thus the
most common file format will be UTF-8. No matter what linebreaks
you're using.

* In the Python world ReST has proven to work - for large scale
documentation work with many contributors. You probably know this is
impressive:
   http://docs.python.org/

But let's go here for now so we won't get lost:
   http://docs.python.org/documenting/style.html

Do you notice the link to the left of the page: "This Page -> Show
Source":
   http://docs.python.org/_sources/documenting/style.txt

I find this plain text version is very good readable. And always being
able to inspect the source is very instructive und encouraging to me.


* The ReST rules to markup plain text are a solid base to build on.
And a lot of people do. Wonna have some fun? Have a look at
"rest2web". It' some additional code to build a website. And all
content is written as text with ReST markup. Go ahead and download!:
   http://www.voidspace.org.uk/python/rest2web/


* Here's a guy that /is/ working on a WYSIWYG editor. I doubt that its
stable and advanced enough. And it may be to difficult to install on
some systems. But it shows what's possible. And, not to forget, Python
offers ways to create self contained executables für Linux, Mac,
Windows.

http://blog.enthought.com/enthought-tool-suite/a-renewed-restructured-text-editor/

* It is probably much easer to set up a website that offers some
online services like: Paste your ReST text as input and get your PDF
or HTML version back. "pandoc" is an example. And it offers an even
more interesting feature: Paste some HTML code and get your ReST back!
Alright, you'll have to do some manual processing afterwards. But I
tried with part of a page from typo3.org and it works!:
   http://johnmacfarlane.net/pandoc/try


Ok, I hope you can stand my enthusiasm. Over ...

Martin

-- 
http://mbless.de