On Fri, 2008-11-07 at 23:31 +0000, Toby Smithe wrote: > Hello all, > > My sponsor recommended I send a shout your way for advise pertaining > to PDF documentation exported from a website for inclusion in my > package "mscore". Could you run a brain cycle or two over the attached > message, and share some thoughts? I'm not subscribed, so please CC me > in all interesting replies. > Toby Smithe-2 wrote: > > > > I have added another patch to the CMakeLists that disables > > installation of the manual pdfs, as my current (rather simple) method > > for DFSG-izing the checkout removes all PDFs (as it is unclear for > > copyright reasons where they have their sources). In my next upload, > > that should be unnecessary. To help with this, please could I have > > some clarification as to exactly the process by which those files are > > generated. > > > > Good question Toby. The content of the handbook pdf comes directly from the > website. And the content (text & images) on the website are all published > under the Creative Commons Attribution 3.0 license, as stated at the bottom > of each page on the musescore.org website. I hope this license doesn't > prevent you of adding the manuals in the debian distribution. If it does, > let us know what license(s) can be used. > Regarding the pdf files: those are generated from within the website using > the DomPDF (http://sourceforge.net/projects/dompdf/) library which licensed > under the LGPL license. So, I guess this poses no issues. Consider how you would fix a bug reported against these PDF files - even a simple (but misleading) typo error. Patching a PDF isn't a nice idea (even if possible) so you would need a way to modify whatever is used to generate the PDF. This means that the content used by DomPDF would need to be packaged in the .orig.tar.gz - that sounds like the PHP code for the site itself. There could be all sorts of problems with that idea, not the least of which is trying to run DomPDF within the build. The basic problem is not in which format the docs are released, it is the fact that the docs are generated from the website. Any modification of the docs in the Debian package can never modify the website for the upstream package so you will always end up with users getting two different answers. This can be handled but needs to be done carefully and transparently. Talk to upstream again and ask them these questions: 1. Consider if a Debian bug report required that the contents of the docs in the Debian package needed to be modified and this modification retained in future releases. How do upstream intend to support this requirement - particularly if the change is specific to Debian and not meant to be part of the upstream website? 2. PHP generates HTML more easily than PDF and patches implementing changes to HTML are easier to integrate into the PHP than "patches" or modified PDF files. How do upstream want you to provide updates and patches for the docs? Are you expected to login to the website and make the changes directly (which means a new upstream release every time)? Generating docs from a website sounds like a neat idea but the reality is different - the docs need to become something separate from the website, the docs need to be considered as "released" and "versioned". Just as with the main code, the docs need to be modifiable using patches and other automated methods and those patches apply to a specific version of the released docs. The website then has a more recent version and each displays the version clearly at the start of the documents (removing any ambiguity for users). The website could be akin to Sid (never released) and older versions of the website (in effect) get archived into the releases. To do this, the docs should be HTML - the same HTML as the PHP itself would have generated at the precise time that the release was made - and include relevant CSS files and images. The HTML for that release needs to be released and probably archived on the website for reference (it would be good for the website to retain logs of what changed between releases) and updates to the docs would need to be acceptable as patches to the HTML. I don't see that PHP->PDF is ever going to be a DFSG-free process because the requirement for modification of the docs simply isn't workable. -- 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