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

[Daniel P. Berrange]

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")."

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.

Regards,
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 :|