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
PURCHASE STYLUS STUDIO ONLINE TODAY!
Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced!
Download The World's Best XML IDE!
Accelerate XML development with our award-winning XML IDE - Download a free trial today!
Subscribe in XML format