I think a getting started guide would help a lot. On Sat, Sep 28, 2002 at 10:46:36PM -0400, Erik Lechak wrote:
> 3)Do I have to use pod? No offense, but I can't stand pod. The pdd > design document states that pod is the "...documentation language for > All Things Perl", but this is Parrot not Perl. And this document would > not be a design doc. If Parrot is supposed to be a cross language VM, > why do people need to know pod to read (or write) the docs? I know that > it is easy to convert pod to an easy to read format, but would a > developer with little perl experience know that? Parrot is trying to > encourage developers from areas other than perl, so why discourage them > by introducing them to parrot with pod documents. Well, POD is supposed to be easy, and by implication easy to learn. But that's irrelevant if you already know it and know you don't like it. In my opinion it makes sense to have one documentation format consistently (in the same way that we intend to have one true C indenting style) What documentation format(s) do you like? Is there an easy way to convert them, or a subset of them, losslessly to and from POD? If we provided tools with parrot to do that, then (assuming we stick with POD as the documenting format) it would allow you (and everyone else who shares your preferences whom we hope to recruit) to write documentation in the way that feels natural to you by converting the POD documentation to whatever, editing that, and converting the changed version back. This would mean that the round trip conversion had to be lossless and (almost) canonical form, so that a diff of the original POD against the round trip would be empty, and I guess that possible in theory. However, are there any useful (not POD) documentation formats for which it's practical? > Could there possibly be a parrot comment style? It could be used > instead of other comment styles internal to parrot. Use it in the > c-code, the perl code, the parrot assembly code, and to write the > documentation. Then a (perl) preprocessor could strip it out before it > is compiled or run. Normally I would not suggest such a thing, but > there is a lot of code generation and manipulation going on anyway. It > could allow for document generation of all the parrot source, assembly, > tests, and documents into a javadoc-like html reference. Or maybe I'm > just dreaming. It's not clear to me what you think might work well for this. Do you have any suggestions - either of what we could do, or what there is already that is bad (and why)? > Please go easy on me for not liking pod. Well, you were crafty enough not to say why you don't like pod, which makes it hard for anyone to work out how to respond to your heresy. :-) Nicholas Clark -- Even better than the real thing: http://nms-cgi.sourceforge.net/
