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

[Alon Levy]

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.

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

> 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 :|
> _______________________________________________
> Spice-devel mailing list
> Spice-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/spice-devel