On Fri, 2008-01-25 at 23:32 +0100, Gilles Filippini wrote: > Hello mentors, > > My upstream has just included localized documentation in DocBook format. > I'm not sure how I should deal with this doc. If the package is part of GNOME (or KDE possibly but I'm not certain), then docbook (XML flavour) can be parsed directly by the help tools within the environment - yelp in the case of GNOME. To make this help available smoothly, you need to depend on the tools for the respective environments and install the documentation in directories specified for those environments. The program also needs to work with the respective libraries to be able to call the helper program to display the docs upon request. The docbook file could then be part of a foo-common package along with translations, images etc. It isn't trivial to handle localized docbook help file installation manually - investigate the proper tools for the environment. If you want to provide *any* docs via docbase then the docbook needs to be converted, usually via xsltproc. Example commands are included in the debian/manpage.xml.ex files created by dh_make. > According to [1], documentation should be in HTML and the XML DocBook > format should stay in the source package. Unless the package specifically depends on (or recommends) a tool that can access the docbook files directly. > Which is the best option? > a) provide only the DocBook files just like showimg does Not via docbase, only via gtk-doc-tools or similar. > b) provide the DocBook files plus the generated HTML files Only with a Recommends on yelp or similar (as long as yelp is able to read your docbook file.) > c) provide only the generated HTML files and leave the DocBook files in > the source package. Overall, probably best. You will need to build-depend on xsltproc, xml-core, docbook-xsl. Add a Recommends for dwww in the -doc package too. -- Neil Williams ============= http://www.data-freedom.org/ http://www.nosoftwarepatents.com/ http://www.linux.codehelp.co.uk/
Attachment:
signature.asc
Description: This is a digitally signed message part