Re: [libvirt] Break up virsh man page into smaller sections?
On 06/04/2010 10:29 AM, Daniel Veillard wrote:
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,
Interesting. I hadn't considered the search aspect of things would
break, which I would find to be a PITA too. :)
Guess I'll just look at adding some of the missing commands and options
to the existing (single) virsh man page, as I have time (when/if) around
other things.
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.
Sounds like a worthwhile thing too. My personal interest is in making
things more day to day practical/usable from a SysAdmin point of view,
so I'll personally probably stick with the user level docs atm though.
They still need a lot of work. ;)
Regards and best wishes,
Justin Clift
Daniel
Daniel
--
Salasaga - Open Source eLearning IDE
http://www.salasaga.org