[Spice-devel] spice manuals - repository / docs dir in spice?

[Daniel P. Berrange]

On Thu, Nov 24, 2011 at 05:12:30PM +0200, Alon Levy wrote:
> On Thu, Nov 24, 2011 at 01:15:48PM +0000, Daniel P. Berrange wrote:
> > On Thu, Nov 24, 2011 at 02:43:52PM +0200, Alon Levy wrote:
> > > Hi,
> > > 
> > >  I want to finally have some work on the odt manuals we currently have,
> > >  if only to mark stuff as "obsolete / not up to date" and fix simple to
> > >  fix things (like mentioning vdagent now supports Linux/Win7/Win2008).
> > > 
> > >  But where should those odt files be? put them in spice/docs or a new
> > >  repository? Just so no one shoots me when I send a patch with 6 odt
> > >  files (binaries all).
> > > 
> > >  Or do we want to start with a different format? odt 2 markdown? (and
> > >  use asciio for charts?
> > 
> > My strong recommendation would be to use the Fedora docbook toolchain
> > "publican", and certainly abandon odt as the format - HTML & PDF are
> > what docs should aim for primarily. This will enable to upstream docs
> > to be easily repackaged in Fedora and RHEL simply by changing the
> > branding package they are built with.
> > 
> > The way it works is that you provide a custom brand (aka style)
> > See libvirt-publican.git for our example brand:
> > 
> >    http://libvirt.org/git/?p=libvirt-publican.git;a=summary
> > 
> > And then you can create multiple documents using the brand:
> > 
> >    http://libvirt.org/git/?p=libvirt-appdev-guide.git;a=summary
> >    http://libvirt.org/git/?p=libvirt-virshcmdref.git;a=summary
> > 
> > By default it will build you PDF and HTML versions of the documents.
> > Here's a libvirt HTML example:
> > 
> >    http://builder.virt-tools.org/artifacts/libvirt-appdev-guide/html/
> > 
> > And a PDF example:
> > 
> >    http://libvirt.org/guide/pdf/Application_Development_Guide.pdf
> > 
> > In theory you can write further style sheets which transform the docbook
> > into plain text, or man pages if applicable, but we've not tried that in
> > libvirt yet since we're happy with just HTML and PDF output.
> > 
> > I'd also recommend that you apply
> > 
> >   "Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA")."
> > 
> 
> They are all already licensed under:
>  Licensed under a Creative Commons Attribution-Share Alike 3.0
> 
> Note sure what the "Unported license" means.

"Unported" means the license is written to be applicable worldwide. This is
generally what most projects want. The other alternative is to "port" the
license to a specific country's legal jurisdiction.

Since your existing docs don't mention a jurisdiction it is reasonable to
assume it refers to the "Unported" variant.

> 
> > as the license for your docs. This is the standard license used by Fedora
> > docs, Fedora wiki, Wikipedia and many other open doc sites, so by following
> > this license you gain interoperability allowing easy copy/paste of text
> > from other docs under the same license.
> > 
> 
> Thanks for the input. How would you go about converting the existing
> documents? they are extensive and rewriting them would be a pain.

This tool claims to be able to export OpenOffice docs to Docbook (and
many other formats). That said, there are soo many ways you can use
DocBook, that I can't say whether the output will actually be usable
with the publican templating system:

 http://dag.wieers.com/home-made/unoconv/

My strategy would probably be to convert the existing openoffice docs
into plain text, and then go through an put in the minimal structure
ie section headings & paragraphs. Then do a second pass to extract
any images from the OOfice file saving them to PNGs and the setup
links to then in the docbook. Finally convert any data tables in the
plain text, into proper docbook tables. Somewhat time consuming
though...

Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|