[Zope-CMF] Suggestion - Modular Documentation

[Dieter Maurer]

seb bacon writes:
 > * Chris Withers <chrisw@nipltd.com> [010705 09:12]:
 > > StructedText, why? I gotta agree with Jon, why come up with another form of
 > > markup language when you have to translate it from there into another one
 > > anyway?!
 > 
 > Well, there's not much in it, but here's my reasoning:
 > 
 > 1) You can read stx straight from the filesystem as plain text , which
 >    is nice for developers
You can do that with HTML, too.

Okay, not the one produced by MS Word, but HTML can be very
readable.

 > 2) You don't have to translate it - it happens for you :-P
I am not always happy with the outcome.

At least with the old StructuredText (I do not yet know
StructuredText-NG), it was quite difficult to get something
like:

	def foo(a, b='text'):

right. The quoting rules have not been as clear as that of HTML.

More difficulties:

  *  relative URL's

  *  the inclusion of "<"

     I once made a comment to one of the Wiki's.
     I used lots of "<", because I thought it were text
     not HTML.
     I was horrified when I saw the result - an unreadable comment.

 > 3) There's supposedly the promise of being able to output it as ps,
 >    pdf, etc.
That's true for HTML, too, isn't it?

 > 4) We'd have to come up with a standard for which tags to use if we
 >    went with html, whereas stx enforces a decision for you.
Aren't the HTML tags not as straight forward as the StructuredText
indentation rules?


Dieter