[Libvir] man page for virsh

Enclosed is the man and the html page that were generated from POD Plain Old Doc from perl. pod2man virsh.pod.1 > virsh.1 pod2html virsh.pod.1 > virsh.html Behold the power of perl :)

On Thu, Apr 06, 2006 at 05:24:49PM -0400, andrew puch wrote:
Enclosed is the man and the html page that were generated from POD Plain Old Doc from perl.
Cool ! Thanks, I'm adding the man page to the distribution. However I don't feel like adding the pod file directly, I'm a bit concerned by the building dependancy it represents so I can't make it really part of the sources. I'm more used to DocBook based man pages, even though I think it is a pain to maintain. Also in that line of thinking, I think that based on doc/libvirt-api.xml it should be relatively easy to developp a program (XSLT or Python) generating the man page for libvirt.3 , except that I really don't know my roff and don't know what need to be generated in practice ... Thanks ! Daniel -- Daniel Veillard | Red Hat http://redhat.com/ veillard@redhat.com | libxml GNOME XML XSLT toolkit http://xmlsoft.org/ http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/

On Mon, 2006-04-10 at 09:29 -0400, Daniel Veillard wrote:
On Thu, Apr 06, 2006 at 05:24:49PM -0400, andrew puch wrote:
Enclosed is the man and the html page that were generated from POD Plain Old Doc from perl.
Cool ! Thanks, I'm adding the man page to the distribution. However I don't feel like adding the pod file directly, I'm a bit concerned by the building dependancy it represents so I can't make it really part of the sources. I'm more used to DocBook based man pages, even though I think it is a pain to maintain. Nod , maybe a make doc part of the make file ??
Are choices are as follows # 1 pod , some say it is evil do to the perl. # 2 docbook2x http://docbook2x.sourceforge.net/ Some say it is evil do to the nature of the perl, that allows the above program to do the the man pages. # 3 create yet another program to do the above.
Also in that line of thinking, I think that based on doc/libvirt-api.xml it should be relatively easy to developp a program (XSLT or Python) generating the man page for libvirt.3 , except that I really don't know my roff and don't know what need to be generated in practice ...
If we want to do down the path of docbook, then I think we should leverage the +2 man years in docbook2x, vs rolling a new program that will take us a few go around to get right. I will see how hard it will be to roll out the docbook2x man page solution for the next release of libvirt. If it looks promising I might need to roll up some of docbook2x rpms for us to place into extras if they are not there already. Also going down the doc book path, do we want to start with the internationalization efforts ??

On Mon, Apr 10, 2006 at 10:35:24PM -0400, Andrew Puch wrote:
On Mon, 2006-04-10 at 09:29 -0400, Daniel Veillard wrote:
Cool ! Thanks, I'm adding the man page to the distribution. However I don't feel like adding the pod file directly, I'm a bit concerned by the building dependancy it represents so I can't make it really part of the sources. I'm more used to DocBook based man pages, even though I think it is a pain to maintain. Nod , maybe a make doc part of the make file ??
Are choices are as follows
# 1 pod , some say it is evil do to the perl.
# 2 docbook2x http://docbook2x.sourceforge.net/ Some say it is evil do to the nature of the perl, that allows the above program to do the the man pages.
# 3 create yet another program to do the above.
Usually I use just the normal docbook to man stylesheets coming from Norman Walsh release and packaged like everywhere. You need to follow an exmaple but then you have a .xml and is a single xsltproc command to generate the man page. That's what we use for the man pages in libxml2 and libxslt.
the man page for libvirt.3 , except that I really don't know my roff and don't know what need to be generated in practice ...
If we want to do down the path of docbook, then I think we should leverage the +2 man years in docbook2x, vs rolling a new program that will take us a few go around to get right.
Well, the docbook stylesheets from Norm are from one of the main docbook author and from one of the XSLT standard guys, the 2 years of docbook2x can't really compare :-)
Also going down the doc book path, do we want to start with the internationalization efforts ??
I don't think we are really targetting normal users at this point, maybe for virsh, but english only for now sounds just fine to me (I'm biased, a biased french :-) Daniel -- Daniel Veillard | Red Hat http://redhat.com/ veillard@redhat.com | libxml GNOME XML XSLT toolkit http://xmlsoft.org/ http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/
participants (3)
-
Andrew Puch
-
andrew puch
-
Daniel Veillard