On Thu, Jun 03, 2010 at 03:24:33PM +1000, Justin Clift wrote: > Hi all, > > Looking at the virsh man page (tools/virsh.pod), it's getting pretty > unwieldy and hard to grok for end users. > > Wondering if it's worth breaking it up into sections? > > Maybe something similar to how git structures their man pages? > > ie. > > man virsh > > Giving an overview, the categories DEVICE, DOMAIN, NETWORKING, > STORAGE, (etc), and listing the more detailed man pages) > > > man virsh-console > > (initially a copy of the existing virsh console man page contents.) > > virsh console domain-id > > Connect the virtual serial console for the guest. > > > man virsh-create > > (initially a copy of the existing virsh create man page contents.) > > virsh create FILE > > Create a domain from an XML <file>. An easy way to create the XML > <file> is to use the dumpxml command to obtain the definition of > a pre-existing guest. > > Example > > # virsh dumpxml <domain-id> > domain.xml edit domain.xml virsh \ > create < domain.xml > > <etc> > > ??? > > Regards and best wishes, Honnestly, git does it that way and I hate that. The advantage of man is that it's text and you can search for verbs or descriptions which may correspond to the actions you're trying to accomplish. If you split it in a zillion man pages it's a zillion different files that you need to search on. It's far less convenient from my point of view. And really I don't see a big advantage, plus you need to duplicate lot of boilerplate on each sub man page section. If man was an hypertext tool with automatic reference access and unified search, this may be a bit nicer but splitting in many files is not convenient with the tool as designed in my opinion, Now what we really lack is the API man pages, libvirt.3 which should be autogenerated from the libvirt-api.xml but that will lead to an even more giantic man page, maybe splitting here would somehow make sense but those call should be grouped by themes. Daniel Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@xxxxxxxxxxxx | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/ -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list