[libvirt] Virsh reference is out of date, should it be updated from the man page?
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. 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). 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? Regards, Povilas [1] - https://libvirt.org/virshcmdref.html [2] - https://libvirt.org/git/?p=libvirt-virshcmdref.git;a=summary
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).
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?
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. However, I'm no docbook/manpages master, so I'll let somebody else look into it (perhaps yourself? ;-)) Michal
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@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On Mon, Sep 03, 2018 at 12:09:42PM +0200, 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.
Yes, that is correct - it should be much more verbose information for it to be useful as a doc. If we just wanted HTML there's already the ability to convert the POD manpage to HTML. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
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
participants (4)
-
Daniel P. Berrangé -
Ján Tomko -
Michal Prívozník -
Povilas Kanapickas