[libvirt] Break up virsh man page into smaller sections?

[Daniel Veillard]

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 at veillard.com  | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library  http://libvirt.org/