Documentation for applications in ubuntu-docs - USB Creator

[Phil Bull]

Hi David,

On Tue, 2010-06-29 at 12:04 +0200, David Planella wrote:
> At UDS we discussed how to best package documentation and the
> corresponding translations for Ubuntu applications [1]. This came as a
> request from the OEM team after experiencing that in customized images
> they cannot always include the whole ubuntu-docs package but would still
> want to include the documentation for each separate application.
> 
> After discussing it with Sebastien Bacher from the Desktop and Kyle
> Nitzsche from the OEM team, we agreed that it would be best to have a
> policy whereby all applications ship their own documentation. The idea
> is to keep topic-based documentation (Ubuntu Docs) separate from
> application-specific documentation, and thus be able to ship the
> application's documentation translations in customized images with as
> little modification as possible.

This is sensible, and I agree with the policy. The reason we weren't
doing this already was because of some difficulty in managing
translations and updates, if I remember correctly (documentation
templates on Launchpad needed to be treated specially or something).

> Right now the USB Creator documentation is part of Ubuntu Docs, and I've
> talked to Evan Dandrea as the maintainer to move it from ubuntu-docs to
> the application, to which he agreed.
> 
> I'm now contacting you as the maintainers of the usb-creator
> documentation in ubuntu-docs. As I said, we'd like to move the
> documentation to the application source package. At the technical level,
> this is just a matter of:
> 
>      1. Moving the original xml sources to usb-creator.
>      2. Adding an additional document page or section with the license
>         and the copyright from the Ubuntu Documentation Project
>      3. Moving the current usb-creator translations (PO files) to the
>         usb-creator sources
>      4. Integrate translations into the build system of usb-creator with
>         po4a
>      5. Disabling the translation template for usb-creator under the
>         ubuntu-docs source package in Launchpad
>      6. Enabling the translation template for usb-creator under the
>         usb-creator source package in Launchpad.
> 
> I've mostly figured out how to perform these steps. Please feel free to
> add your comments or questions, especially if I've forgotten any step.
> 
> Especially I'd like to hear if you've got any advice on 2. (adding the
> license and the copyright notice), as that's the one I haven't quite
> figured out.

You can just link a "legal.xml" file into the source. For an example,
see [1]; line 16 shows the &legalnotice; entity being added into the
articleinfo tag. You would have to define your own legalnotice entity.
Add something like this to the page header:

<!ENTITY legalnotice SYSTEM 'legal.xml'>

The contents of the legal.xml file [2] are just the terms of the license
that the docs are released under (we normally recommend the CC-BY-SA 3.0
license). Once the move has been completed, let me know and I can check
that a license has been included properly, if you like.

Thanks,

Phil

[1] -
http://bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-docs/maverick/annotate/head:/add-applications/C/add-applications.xml
[2] -
http://bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-docs/maverick/annotate/head:/libs/C/legalnotice.xml

-- 
Phil Bull
https://launchpad.net/~philbull