Mark Overmeer writes: > * Damian Conway ([EMAIL PROTECTED]) [070615 00:17]: > > > * Pod 6 is both a structural and a semantic scheme; you can specify > > both the structure of a document, and the meaning of its various > > components > > Yes, and that is one of the things which worries me most *You can*. > It's full freedom,
You're concerned that an aspect of Perl 6 might have too much freedom? Isn't Perl all about giving users freedom to choose their own way of doing something? > like XML, and without a convention everyone may think-up there own way > of documenting the same kinds of code elements. Yes. But in reality many people will follow what others do, or look to follow best practices. With Perl 5 you have complete freedom as to the names of C<=head1> sections in the Pod for modules, yet in browsing Cpan it's clear that there are conventions and many people use the same headings. So not mandating a convention isn't much of a problem. Moreover, I reckon that not mandating a convention is essential. Look at what's being done with Perl 5 at the moment (not specifically Pod, just in the Perl 5 community in general) and the best practices that have sprung up in recent years (and are still evolving). People are, of their own accord, following conventions that nobody had even thought of at the time Perl 5 was released; even at the time Perl 5.6, say, was released. > In this structure, the responsibility of how things get interpreted is > not for the programmer, so consistent over all modules. We can make > search.cpan.org and manual-pages with a consistent structure. Do you really think that people can now, before Perl 6 has gained anything approaching the usage we expect, make policy for how things should be documented, such that that policy will be the best possible way of documenting everything written in Perl 6, for ever? Or even a good way? That strikes me as incredibly shortsighted, verging on arrogance by whoever comes up with the rules, and doomed to failure. Rather than trying to map out the future in detail (which is tricky), the best we can do is come up with things that are sufficiently flexible that they're capable of being used in ways we haven't yet thought of. Then when somebody, years from now, has a good idea, it will be possible for that to be implemented (and followed by others), rather than tying us to some convention set at an arbitrary point in the past. > > * To summarize the summary: > > - Use Perl for what Perl is good for (specification) > > - Use Pod for what Pod is good for (commentary) > - Use expressions where expressions are good for (calculation) > - Use regexes where regexes are good for (matching) > ... > > i.e. it is not a valid argument: expressions and regexes > are integrated. Yes, but on the other side of the argument coconuts and fax machines are not integrated. I'm reasonably confident that for every pair of things which you list as being integrated I can come up with a pair which aren't; I doubt that will really assist the argument one way or t'other. > the issue is to have sufficiently integrety in code and markup > to be able to create documentation-generating tools which produce enough > quality. Damian's spec permits this. > And at the same time give the programmer the mimimal burden on writing > documentation, to increase the chance that it is present and good. You should 'Perl 6 Documentation Best Practices', with guidelines for how to use Pod. I'm sure many people would appreciate just being able to follow a template rather than having to make decisions over the small details of what to do. That way we have a convention for those that want it, but also don't tie ourselves into anything. If a particular convention gains widespread approval then peer pressure should encourage its use (in the same way that strict and warnings are currently optional in Perl 5, but in the absence of a good reason it's expected that they be used). Smylers
