Re: Document Snippets

[danilo gnome org (Danilo Šegan)]

Yesterday at 22:17, Shaun McCance wrote:

> 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.  

Just for reference, "gnome-desktop" module already includes FDL, GPL
and LGPL, and is ported to gnome-doc-utils build system as well
(thanks to vuntz, if I am not mistaken :). 

Should we reuse that or move them to g-d-u instead?

> 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:

Agreed.

IANALE (IANAL either :), but I think that nothing stops us from
dual-licensing any document, so by extension, dual licensing any part
of the document.

> 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.

Yeah, we'd need to somehow special case this or implement a more
general mechanism in xml2po for expanding original document based on
something in a translation (like we currently do with
translator-credits and <copyright> tags).

Another, simpler option is to just include those two paragraphs in C
version as well, and special case untranslated version not to include
them.

> 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.

Well, there is always an option of using intltool for these as well
(by providing "_" marking on all the tags, and using file-per-language
intltool-merge output, as used in eg. gok).  Of course, intltool will
instead set xml:lang on each of the translated tags, but that
shouldn't be too much of a problem, except for the missing "lang"
attribute on root element.


But, I am not sure we want this to appear in regular status pages:
legalese is *very* hard to translate, and even if translated, it can't
become official (due to FSF policies).  With it being so hard, we're
getting more difficult translatable things without it being too useful
if no other documentation is translated (i.e. all these snippets would
end up being unused if no docs are translated).

Cheers,
Danilo