"be consistent" | |
PerlMonks |
comment on |
( [id://3333]=superdoc: print w/replies, xml ) | Need Help?? |
There's already a perfectly good documentation format for Perl that has a much less bletcherous syntax. It's POD. Actually, the syntax doesn't look bad to me. In comparison to POD, you've got @foo{bar} instead of F<bar>. On average, they both seem to take up about the same amount of space on the page too. Now POD has its flaws, {snip}, but it's also fairly nice in what it does include and how it does it. Yup. Texinfo seems ok too though. From the few times I've used it anyway. More than that, whatever the document format of Perl 6, it must be portable to all of the systems where Perl 6 runs (and saying "every flavor of GNU/Linux that I've come across" doesn't really impress me with portability). Which flavors of GNU/Linux *isn't* Texinfo available for? ;) Seriously though, since you can easily convert Texinfo to various formats (ex. HTML), MS Windows users should be able to access their docs just fine. It must be lightweight enough that it can be part of the core distribution. The only heavy part of Texinfo is TeX, which, of course, isn't necessary unless you want to produce dvi or pdf. Dunno how Texinfo-sans-TeX weighs in compared to the POD suite of tools, but I'm guessing the difference is not a big deal either way. It should be sufficiently advanced over POD in Perl 5 to make up for any differences in syntax. Check. It should fix as many of the warts of POD in Perl 5 as possible. Check. It ought to be similar to POD in Perl 5 where possible, as change for the sake of arbitrary change is a lousy design goal. Well, it's not arbitrary, since -- evidently -- there's reasons to go from Perl5's POD to Perl6's Pod. Perl5's POD is well-defined, and so is Texinfo, so a translator shouldn't be too much of a problem. It needs to be extensible, which is one of the main problems of POD in Perl 5, Dunno what you mean here. What do you need in a doc system that's not in Texinfo? And why would it be hard to extend Texinfo? and it should allow better reuse and introspection and customization than Perl 5's POD. Ah. Well, you've got me there. I think Ruby's doc system has some introspection built into it. That seems to come with its own problems though. For example, you re-open and extend a class but the docs either don't show your additions, or else you can no longer read the docs how they were before your addition (though I guess these are problems that can be worked through...). It's also very nice to control the document formatter {snip} Yes. I think this is a substantial tradeoff you make when using a standardized doc system outside of your own mothership. You get benefits too though, and I still think the idea has merit. In reply to Re^2: Perl6 Pod -- reinventing the wheel?
by j3
|
|