Von: David Carlisle [mailto:davidc(_at_)nag(_dot_)co(_dot_)uk]
well the original message showed that as one (of two)
possibilities and
the "small survey" refered to in the subject line was
apparently asking
if that was to be prefered (or not) over the alternative ReST markup.
yes true. personally i definitely prefer ReST but a pyxsldoc user suggested to
make the javadoc style the prefered style. He thinks that programmers are used
to comment in that style and reckons ReST would not be used therefor although
the technique is better.
I just wanted a few more opinions and the discussion definitely made me even
more convinced ReST is the way to go (if using XML comments in that way at all
;).
is very readable and quite "writable" as well. it is just a nice way
to write comments and it quite easy to process into XHTML
afterwards.
well it depends. It often seems easier to write plain text (or only
lightly marked up text) but the lessons of structured
documents over the
decades (latex, sgml, xml, ...) is that, on balance, markup is a good
thing and the more of it you get and the earlier it's added, then the
happier you will be in the long run.
i think ReST is more or less a kind of "light markup". It can be complex but
still is easy to write and read. and thats what i am interested in. i just
finished quite a big wcms project using xml and noticed that writers and
editors (not technical people) have problems writing XML of course, even basic
markup like <b>bold</b> is a problem. so something simpler like a wiki style
format is much better for that and therefor should also be better for more
technical minded people like xsl programmers.
side note: WYSIWYG seems an obvious best bet for editing text but it has the
problem of being not structured enough as you can write texts as if they *look*
structured but really are not. so a light markup somehow gives more of a
WYSIWYW (what you see is what you want) so to say...
You see, I don't just hang around
here for the fun of it, I actually believe in all this
structured markup
hype:-)
David
definitely.
chris