Re: Perl6 new features
2007/6/20, cdumont [EMAIL PROTECTED]: I know that it is somehow not the subject, but I think the actual 5.8 doc should be changed to some extents. snip AND so that it could be a lot richer, allow people to comment... Well you can't comment it (CPAN Annotate allow you to comment the doc of any CPAN module though), but the perl documentation is quite extensive, and I for one don't understand what you mean by : It could be nice if we could browse each core functions, having the function parameters, flags (not that much used right?), and the return value of the function, followed by exampleS it seems to me that you already have this : in line of command you can use perldoc -f split to get the split() doc, where there are examples and return value and parameters are discussed at length, if you prefer a modern format, http://perldoc.perl.org/functions/split.html should content you, and you can use Pod::POM::Web to get a small HTTP server where all Perl doc (core and modules) can be browsed and searched, so what exactly are you speaking about ? -- Jedaï
Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
I'm quite surprised by this debate... To me it seems a clear rule that state that if a line begin with = then it starts a POD section is way easier to understand than a line beginning by = will start a POD section except if it is in a Perl statement, or in a :to section, or in a string literal, etc The Learning Perl 6 argument seems equally contrived to me since anyway you don't need POD to understand programming in Perl and I never actually learned POD until I wanted to do a real module and document my little console utilities in Perl. You don't need to understand POD to read a program where POD is used : it's usually quite clear from the content where it is POD and where it is doc and each section that don't look like Perl is usually POD. Even if you never heard of POD the first few samples would be a dead giveaway that those weird things are actually documentation and not code (it's my experience speaking here). I seriously doubt most programmer will start including POD section in confusing places because now they can do it, so the situation should not be any different from before. And if some do it, hell, I seriously doubt that their program would be in the scope of the beginning of Learning Perl 6 !! You didn't put -+- there in previous versions, did you ? The other problem is that if somehow a braindead guy (where would he get the idea from, I never saw such a style) put his = in first column expecting a assignment he won't get it... Seriously ? Are you really allowing for such weirdness in introductory material to a Language course ? So in my opinion, it would be fine to let slip that you can also create some kind of comment/doc by putting a = in the first column in the first chapter, and let the subject of POD for a later chapter. Of course some of you have far more experience teaching languages, but as a language _student_ I don't feel this would be any inconvenience, in fact I would have been very happy if all the Perl5 rules were that easy. -- Jedaï
