Re: [Qemu-devel] [RFC] wiki.qemu.org

[Anthony Liguori]

On 01/29/2010 03:47 PM, Stefan Weil wrote:
> Hi,
>
> it's great to have an "official" QEMU wiki.
> What will happen with http://qemu.kidsquid.com/?
>    

I don't know.  It's certainly provided a great service over the years.  
I see no reason not to continue to link to it and if people want to move 
content in either direction, that would be okay to.

> Before removing the texi documents, there should
> be solutions for these topics:
>
> * How do we get a man page for a certain qemu release?
>
> * How do we get online documentation for a certain qemu release?
>
> * How do we get offline documentation (html without internet access)?
>
> * How do we get printed documentation which looks nice?
>    

All good points.  Personally, I think there are two types of 
documentation.  There is exhaustive option documentation which covers 
things like the monitor commands and the command line options.  This 
documentation should continue to live in the git tree IMHO and we should 
continue to generate man pages and online help from this source.

Then I think there is user documentation.  This is documentation that is 
more oriented to guide a user through what they should and shouldn't do 
and most importantly, how to solve problems on their own.  This think 
this later category is where a wiki shines.

I think qemu-img-cmds.hx, qemu-monitor.hx, and qemu-options.hx 
definitely fall into the first category.  I think qemu-doc.texi and 
qemu-tech.texi fall into the second category.  I think the remaining 
texi files live in both worlds.

> The wiki provides online documentation. It can do this for
> several qemu releases, too. But maintainance of serveral
> pages which are nearly identical will be difficult.
> Applying documentation patches to qemu releases is easier.
>
> For man pages, offline or printed documentation (needed for
> distributions), the texi documents work well. I see no
> easy way to replace them.
>
> Therefore I'd keep the texi documentation.
>
> Instead of adding an external link to the wiki,
> it should be possible to create mediawiki output
> from texi. This output could be copied to the
> qemu wiki using copy+paste, or maybe it is also
> possible to create mediawiki pages automatically
> on demand.
>    

That's an interesting thought although it probably requires translating 
texi into a more friendly intermediary first.

Regards,

Anthony Liguori