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

Reply via email to