AW: AW: AW: AW: commenting and documenting XSLT (small

> Von: David Carlisle [mailto:davidc@xxxxxxxxx]
>
> 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