I've been thinking, and the whole "=begin :lang [langtag] ... =end :lang"
thing for doing POD in multiple (alternate) languages is a good simple
workable solution if:
1) You say someplace what languages this document's content is available
in. (Otherwise a user would take a document in no,fr,fi, would tell the
formatter to format the "de" sections, and would be confused at the meager
output.) Explicitly telling the user exactly what language-tags they can
format the document with, avoids a whole horrible can of worms.
2) Even more importantly: everything that you say in one language, you must
also say in every other language you declared.
I.e., if you decide you're going to document something in "en", "es" and
"it", you must express that list someplace obvious in the document. Maybe
the VERSION section is a good place:
=head1 VERSION
...whatever...
Languages: en, es, it
...whatever else...
And then for every idea you express in a :lang en section in the remainder
of the document, you must also express it in a :lang es section.
So this is good:
=item Foo->bar()
=for :lang en
This bars the Foo. But it doesn't foo the Bar!
=for :lang es
Eso bara el Foo. E<iexcl>Pero no fooiza el Bar!
=for :lang it
Bara il foo, ma non fooa il Bar!
And this is bad:
=item Foo->hooboy
=for :lang en
Hooboy, this does something!
=for :lang es
E<iexcl>Wuju! Hace algo!
...because you forgot to have a corresponding "it" section there.
Now, that doesn't mean that language-alternative sections have to be in any
particular order, or that they need to have identical internal structure.
But you just don't want someone running the formatter with -L=it and seeing
no documentation for Foo->hooboy other than the item-heading.
People would be on their honor to obey those rules (declare your languages,
and live up to the promise).
And, also, hopefully no-one would do something demented like:
=begin :lang en
=over
=end :lang
By the way, I spent the last three hours thinking up a formalism for whole
language/format alternation thing. My idea is simultaneously more powerful
and more rigid, and it doesn't leave people on their honor as much as what
I described above. It's (overly) clever, applying the concepts of
multipart/alternative MIME stuff (both on the axes of content-language and
content-type) to POD, except at the level not of whole documents (as MIME
has it) but instaed of arbitrary groups of paragraphs.
But the complexity it imposes is significant, and is not in the general
spirit of POD, so I'll save you /that/ snapshot of Hell -- altho this XML
representation of my ideas should tell you more than you ever wanted to
know about what I had in mind:
<item>Foo->bar()</item>
<lg-alternation>
<lg-alternate lang='en'>
<p>This bars the Foo. But it doesn't foo the Bar!</p>
<format-alternation>
<format-alternate target="html">
<img src="fooey-en.png">
</format-alternate>
<format-alternate target="rtf">
{\funny\commands\to\draw\something\in\rtf}
</format-alternate>
<!-- and if none of the other formats match -->
<format-alternate target=":ELSE:">
<p>(picture a diagram here, folks!)</p>
</format-alternate>
</format-alternation>
</lg-alternate>
<lg-alternate lang='es'>
<p>Eso bara el Foo. �Pero no fooiza el Bar!</p>
</lg-alternate>
<lg-alternate lang='it'>
<p>Bara il foo, ma non fooa il bar!</p>
</lg-alternate>
</lg-alternation>
--
Sean M. Burke [EMAIL PROTECTED] http://www.spinn.net/~sburke/
