Documentation for applications in ubuntu-docs - USB Creator

[David Planella]

El dv 02 de 07 de 2010 a les 11:36 +0100, en/na Phil Bull va escriure:
> 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).

That's exactly what I was looking for, thanks Phil for the useful info.
I'll use that legal notice, then.

>  Once the move has been completed, let me know and I can check
> that a license has been included properly, if you like.
> 

Great, thanks a lot. I'll be away until Monday the 12th, but when I'm
back I'll look into adding it and I'll then come back to you.

Regards,
David.

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


-- 
David Planella
Ubuntu Translations Coordinator
www.ubuntu.com / www.davidplanella.wordpress.com
www.identi.ca/dplanella / www.twitter.com/dplanella
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: Aix? ?s una part d'un missatge signada digitalment
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20100702/cf874c0b/attachment.pgp>