I discovered Natural Docs a few days ago, and it seems closest to what I'm looking for in a documentation system, particularly its language independence, suitability as a replacement for POD, and output quality. I got about 15 modules successfully converted from POD. This did require a few patches though to handle some things more reasonably, so I have a few comments to share on this experience.
First, the "(see ...)" tag being using for images in NaturalDocs-Development-2007-02-10 seems problematic. It's fairly common to use this phrase in regular text as follows:
"if that fails, an error object is thrown (see below)."
"Roots can be obtained (see <sqrt>)."
"A module system is available (see Section 2.4)."
In fact, in the second case, NaturalDocs does not render "<sqrt>" as a link because of this special treatment.
I ran into this in my own modules and in other modules and so am probably not unique. As this was getting quite error prone, I just patched the source to recognize images with "(image ...)" instead. Also, "(see ...)" might be confused with the JavaDoc "@see" tag, which is different, and it's not immediately clear how the word "see" pertains specifically to images.
A related question is on the choice of parenthesis "(...)" for a few tags (like "(start code)"). This would have been less of an issue if it were written, say, "<see image.gif>", though it would be better to be more unambiguous: "<see:image.gif>", which has resemblance to "<http://www.google.com>"--or even, maybe, "[see image.gif]". The thing going for "(" is you might think of it in a LISP manner, used by a related project called Source Annotation Language (SAL). However, "[" is the Wikipedia approach. The "<" is consistent with Natural Docs link tags though.
The Natural Docs grammar does in some places seem ambiguous or suffer from DWIM syndrome. Just as an example, should this be interpreted as a definition list or an underline?
One of the more important patches made was to recognizes inline mono-spaced code (similar to POD C<> tags), which I saw a few other requests for. It uses the syntax <:...> such as in <:x+y> (":" was chosen as it resembles the ":" used for regular code blocks). Sometimes one wants to render, say, a less than sign <:>>, which can be escaped like <:\>>. Also, some code under "Make sure we don't accept >>, ->, or => as closing tags" was disabled to make this be handled more literally (less DWIM)--e.g. <:=>.
Support for LaTeX math would be nice. That could be done with dvipng. At the very least, superscripts and subscripts would be a useful addition, but the main question is what syntax should be used, particularly so that it does not introduce ambiguities.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Hello Greg,
I discovered Natural Docs a few days ago, and it seems closest to what I'm looking for in a documentation system, particularly its language independence, suitability as a replacement for POD, and output quality. I got about 15 modules successfully converted from POD. This did require a few patches though to handle some things more reasonably, so I have a few comments to share on this experience.
First, the "(see ...)" tag being using for images in NaturalDocs-Development-2007-02-10 seems problematic. It's fairly common to use this phrase in regular text as follows:
"if that fails, an error object is thrown (see below)."
"Roots can be obtained (see <sqrt>)."
"A module system is available (see Section 2.4)."
In fact, in the second case, NaturalDocs does not render "<sqrt>" as a link because of this special treatment.
I ran into this in my own modules and in other modules and so am probably not unique. As this was getting quite error prone, I just patched the source to recognize images with "(image ...)" instead. Also, "(see ...)" might be confused with the JavaDoc "@see" tag, which is different, and it's not immediately clear how the word "see" pertains specifically to images.
A related question is on the choice of parenthesis "(...)" for a few tags (like "(start code)"). This would have been less of an issue if it were written, say, "<see image.gif>", though it would be better to be more unambiguous: "<see:image.gif>", which has resemblance to "<http://www.google.com>"--or even, maybe, "[see image.gif]". The thing going for "(" is you might think of it in a LISP manner, used by a related project called Source Annotation Language (SAL). However, "[" is the Wikipedia approach. The "<" is consistent with Natural Docs link tags though.
The Natural Docs grammar does in some places seem ambiguous or suffer from DWIM syndrome. Just as an example, should this be interpreted as a definition list or an underline?
abc asdf - asdf
There was a related concern here: http://sourceforge.net/tracker/index.php?func=detail&aid=1256312&group_id=81796&atid=564049 . I've run into a few other cases and have some patches I plan to submit. It's not always clear what the correct behavior should be though, lacking a formal grammar.
One of the more important patches made was to recognizes inline mono-spaced code (similar to POD C<> tags), which I saw a few other requests for. It uses the syntax <:...> such as in <:x+y> (":" was chosen as it resembles the ":" used for regular code blocks). Sometimes one wants to render, say, a less than sign <:>>, which can be escaped like <:\>>. Also, some code under "Make sure we don't accept >>, ->, or => as closing tags" was disabled to make this be handled more literally (less DWIM)--e.g. <:=>.
Another patch was manual specification of prototypes, which was included here: http://sourceforge.net/tracker/index.php?func=detail&aid=1053318&group_id=81796&atid=564052
Support for LaTeX math would be nice. That could be done with dvipng. At the very least, superscripts and subscripts would be a useful addition, but the main question is what syntax should be used, particularly so that it does not introduce ambiguities.