#2 add a wiki "markup" parser
When writing documentation, it can sometimes be very convenient to be able to write things in "<b>bold</b>" or "<i>italic</i>", make lists with "<ul><li>" etc.
This is just being discussed on the mailing list, and Thomas says that the output should change all characters into their respective HTML entities. This would mean that such code as I wrote above is written as-is, and displayed, instead of being printed. I think that is the correct way to handle it, getting rid of those strange "@<" and "@>" constructs.
But on the other hand, I do think that some documentation formatting is needed. But this again is impossible to produce in - for example - latex output, because there this is completely different. So the real solution to this is to add a (very) limited HTML parser, that can recognise only the basic tags:
<b>, <i>, <ul>, <li>
and maybe something along the lines of pseudo-html:
<red>, <green>, <blue>, <#1278EF> for colours
all along their respective closing tags (closing tag for colour would be </#> then).
This parser would have to have a generic interface so that each output generator would be able to provide the correct translation. I think error checking should be kept rather low, it is the developer's responsibility to feed this something sane (ie, if the output breaks, don't bother in the program).
Logged In: YES
user_id=32619
Maybe this would be far better:
http://phpwiki.sourceforge.net/phpwiki/TextFormattingRules
Logged In: YES
user_id=32619
I am now that we have a wiki ourselves convinced that wiki
formatting is the way to go (well, at least similar to wiki,
we can't rely on indentation)
Logged In: YES
user_id=406841
Originator: NO
BTW, see no big point in wiki output as a thing in itself.
It should be a dual-way system: changes made to wiki pages should immadiately be moved back to documentation source files.
It is quite complex task even when using separate help files.
Much harder if one would need to parse wiki editing, extract the difference, map it to the sources, generate the proper diff and checkin it into SVN/CVS/whatever version control system used
Logged In: YES
user_id=32619
Originator: YES
No, you misunderstood this.
The idea is to be able to write the comments in the code with a sort of wiki-like formatting, not a wiki itself. Hence, you don't need to write bold text but say '''bold text''' (like in moinmoin) in the pasdoc comment, and pasdoc would create proper HTML/tex/... from that.
The idea is not to edit the code like a wiki, nor to edit the comments like a wiki.
Logged In: YES
user_id=406841
Originator: NO
If to that, i'd prefer the WackoWiki syntax, as more intuitive than one of MediaWiki/moinmoin
But there would be another problem, for example in Fortran ** is mathematical operation of Power, in WackoWiki it would be bold font.
'' means apostrophe in Pascal strings, in wikies it would probably mean somthing.
Same is for //
So in comments any attempts to use sources or formulas may be problematic.
I think it is to be implemented like a tag @LaTex or @html, so writer would deliberately engage this mode when he needs to.