On Wed, Aug 4, 2010 at 10:05 PM, Damian Conway <dam...@conway.org> wrote:
> Darren suggested: > > > Use namespaces. > > The upper/lower/mixed approach *is* a > namespace approach. > It's a very C-like approach, but yes, it's certainly a crude sort of namespace. Perl already has a more robust and modern namespace system, however. Using it would seem wise. > > Explicit versioning is your friend. > > > > Can I get some support for this? > > Not from me. ;-) > > I think it's a dreadful prospect to allow people to > write documentation that they will have to rewrite when > the Pod spec gets updated. I would hope... really, desperately hope that the POD spec changing would be the least of anyone's worries. If you're writing documentation, it's a foregone conclusion that it has to be maintained, just like any other part of your software. If the POD spec is adding new config options at a rate that isn't several orders of magnitude less than the frequency with which your code changes then either you're documenting the Magna Carta or we have a problem with our documentation system. If the latter is the case, then the right solution is to provide new documentation features via modules and allow the user to select which new features they desire, automatically resolving the problem, since old docs simply won't pull in newer features. This could go both ways, as well. "use v6" might get you the default first-pressing documentation features of Perl 6.0.0 while "use v6.1" might get you the default features of 6.1. Then you could mix it up: use v6; use Docs::SectionImage; > Or, alternatively, to require all > Pod parsers to be infinitely backwards compatible across > all versions. :-( > If you never want documentation to break, then that's your only option. Someday we're going to decide to make an incompatible change to Perl's documentation system, and we'll have a very good reason to do so, I'd imagine. The right thing to do will be to make sure that we roll it out carefully and with all due warning. -- Aaron Sherman Email or GTalk: a...@ajs.com http://www.ajs.com/~ajs
