[libvirt] Virsh reference is out of date, should it be updated from the man page?

[Ján Tomko]

On Mon, Sep 03, 2018 at 10:04:16AM +0200, Michal Prívozník wrote:
>On 09/03/2018 09:38 AM, Povilas Kanapickas wrote:
>> Hi!
>>
>> The online virsh command reference at [1] seems to be very out of date
>> according to [2]. There's much more recent documentation at
>> tools/virsh.pod in the main libvirt repository.
>
>Yes, this is because of lacking manpower. As usual O:-)
>
>>
>> I believe it would be great to update the web docs as they are much more
>> accessible and convenient to use (especially the one-command-per-page
>> version).
>>

AFAIK the "Virsh Command Reference" was intended to provide more
information than the man page, especially practical usage of the
commands, not just to have the manpage in HTML.

So providing this extra content with examples would be more worthwhile
than just a copy of the manpage.

>> What would be the best way to approach that? I suppose we could look
>> into automatically converting the current manpages into docbook and
>> using that to update the website? What do you think?
>

Generating parts of the document automatically would help it stay
current, but it should not get in the way of adding more 'human touch'
to it. But a manpage copy might be better than nothing.

We already generate the API documentation automatically, we have a
custom C parser in docs/apibuild.py and docs/hvsupport.pl
that generate some intermediate files - similar approach could be used
to generate a table of options and the availablity sections.

>This sounds like the best way to go. virsh is changed virtually with
>each release so an automated tool that would regenerate the docs which
>could run at every release is certainly desired.>

libvirt development goes much faster than that - it can be generated
hourly just like the rest of the autogenerated docs.

Jano

>However, I'm no docbook/manpages master, so I'll let somebody else look
>into it (perhaps yourself? ;-))
>
>Michal
>
>--
>libvir-list mailing list
>libvir-list at redhat.com
>https://www.redhat.com/mailman/listinfo/libvir-list
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: Digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20180903/ec32f56e/attachment-0001.sig>