Damian Conway wrote:
Darren suggested:
Use namespaces.
The upper/lower/mixed approach *is* a
namespace approach.
Yes it is. But I thought that prefix-namespaces would scale better. Especially
if the documentation system got complicated enough to involve modules, possibly
those by different sources, as some others have suggested.
That said, I'm inclined to think that the likely complexity of the documentation
system over time should grow by fewer orders of magnitude than code in general,
and so I grant that some ideas can look like over-engineering.
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. Or, alternatively, to require all
Pod parsers to be infinitely backwards compatible across
all versions. :-(
One main purpose of declaring the intended interpretation context of a work is
so that developers of interpreters have a lot more freedom to *not* be
backwards-compatible. Each version is effectively a separate language in some
ways. Because a work declares its language version, one should be able to take
the work anywhere and it would be completely unambiguous as to how to interpret
it, no matter how old it is and how much the state of the art has evolved. If
the meaning of a keyword changes in a spec, we know without a doubt which
meaning the user intended.
As for backwards compatibility, this is actually less onerous to implement with
my proposal than otherwise.
For one thing, if developers want to make an incompatible change, they can
release it right away, without a long deprecation or changeover cycle, and in
the typical case old works will continue to be interpreted correctly.
For another thing, assuming in the typical case that any time a language
evolves, it still provides the means to accomplish anything it was previously
capable of, then each implementation needs no backwards-compatibility
internally, but just the state of the art. Backwards compatibility can be
achieved with version-specific shims over top of this single core, which
translate works written to an older spec to their equivalent in the new one.
Because versions are explicitly declared, it is trivial to dispatch to the
correct interpreter or pseudo-interpreter.
Yet another thing, parsers don't have to be infinitely backwards compatible;
they can deprecate support for particular older versions as they choose to, when
necessary and reasonable.
So, explicit versioning is actually very good for *future-proofing*.
I believe there are various precedents for this.
In the Perl 5 world, for example, see "autodie" (optional) or "perl5i"
(mandatory).
use autodie qw(:1.994);
use perl5i::2;
I have also done this from day one in my Muldis D language, and I have no
regrets for doing so.
-- Darren Duncan
