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

[Povilas Kanapickas]

On 09/03/2018 01:09 PM, Ján Tomko wrote:
> 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
>>

Thanks for replies, I will come back again asking more questions when I
start working in this.

Regards,
Povilas

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20180905/b01b60a2/attachment-0001.sig>