Document Snippets (was xml2po -e)

[Shaun McCance <shaunm gnome org>]

On Sun, 2005-09-18 at 20:13 +0200, Danilo Šegan wrote:
> Today at 16:37, Matthew East wrote:
> 
> > I recently had some help on this list regarding the use of xml2po. We
> > have made a pot template using xml2po -e, expanding the templates, but
> > unfortunately this has resulted in the licences and revision history of
> > the document appearing in the template, which several translators have
> > complained about, given that there are official translations of the
> > licences available, and that translating these parts is essentially
> > unnecessary.
> 
> Why don't you include license using xinclude as well?
> 
> That will allow you to keep translations for legal.xml separate.

An idea I've been toying around with for a while is boilerplate
snippets for stuff like this.  These would be provided by, and
translated in, gnome-doc-utils.  So if your document is covered
by version 1.2 of the FDL, you would specify it as a snippet in
your Makefile.am:

DOC_SNIPPETS = legalnotice-fdl-1-2

You would still need to put the XInclude in your articleinfo:

<xi:include href="legalnotice-fdl-1-2.xml"/>

But you would not put legalnotice-fdl-1-2.xml into CVS, and it
would not be included in the PO files for translators.  Rather,
translators would translate this once in gnome-doc-utils, and
it would be installed into DATADIR/gnome-doc-utils/snippets/.
Then at build time, the correct translated version (or the C
version if no translated version exists) would be copied into
your build directory.

Here's the isses we'd need to resolve:

1. Some documents will choose to allow only that version of the
license, while others will allow that version or any later version.
I propose each legalnotice snippet comes in two forms:

legalnotice-fdl-1-2.xml   (Version 1.2 of the license)
legalnotice-fdl-1-2+.xml  (Version 1.2 or any later version)


2. Some documents include the license as an appendix.  Technically,
this is what the fdl calls for.  However, we've gotten around this
by shipping the GNU licenses as separate documents.  Clearly, it's
easy to include appendix versions as well:

DOC_SNIPPETS = legalnotice-fdl-1-1 appendix-fdl-1-1

The problem is that the text of the legalnotice likely needs to be
different based on whether or not you're including an appendix.
So now we're getting permutations of options for the legalnotice:
later version or not, appendix included or not, etc.  And that's
a pain.

Maybe we should just pick one technique and support it exclusively.


3. When documents include non-trivial code examples, it is common
and advisable to license those seperately under an appropriate free
software license.  I suggest (IANAL) that it is acceptable to give
a second legalnotice providing a license for the code.  That is,
I don't believe it's necessary to modify the FDL legalnotice.  It
is likely sufficient to provide a second legalnotice with text to
the effect of:

The programming code in this document is licensed seperately under
the terms of the GNU LGPL.  <boilerplate LGPL legalnotice crap>

This, of course, would also have to be included as a snippet.  We
would not be able to use just legalnotice-lgpl-2-0, as that would
just be a legalnotice to place the document under the LGPL.  We
would have to provide snippets to the effect of:

legalnotice-code-lgpl-2-0
legalnotice-code-lgpl-2-0+
legalnotice-code-gpl-2-0
legalnotice-code-gpl-2-0+
legalnotice-code-bsd
legalnotice-code-etc...

We would also want to provide appendices for each of these.


4. Translations of the GNU licenses, and probably other licenses
as well, are considered unofficial.  There are some translations
listed on GNU's web site:

http://www.gnu.org/licenses/translations.html#FDL

Most of these (and it should be all, from my understanding) have
two paragraphs at the top.  The first is an English paragraph
stating that the translation is unofficial and that the English
license is definitive, and the second is the translation of that
paragraph.  We would really want our translated appendices to
contain those disclaimer paragraphs.  However, those paragraphs
aren't translations of anything in the C document, so I don't
know how we would make that work with xml2po.


5. We would have to translate these document snippets using
xml2po, probably in a separate translation domain from the
one we use for stylesheet translations.  I would consider
these translations to be core gnome-doc-utils translations,
and not documentation translations.  Thus, I would want them
included in the regular translation status pages, rather than
the documentation translations status pages that Danilo has
put together.  But the regular status pages are generated with
intltool, which wouldn't be able to grok the xml2po stuff.


So that's what I'd like to do, and the problems I've run into
in trying to make it happen.  Maybe the wider community of
documentation tools hackers and translations can help me to
resolve these issues.

--
Shaun