Re: [Xen-devel] [PATCH] add man pages to xen

[Sean Dague <sean@xxxxxxxxx>]

On Tue, Aug 02, 2005 at 02:01:58AM +0100, Mark Williamson wrote:
> > The following patch adds the beginnings of man pages to xen, specifically
> > the xmdomain.cfg.5 man page, and a very small stub for xm.1, plus the build
> > elements required.  This is done using the pod (plain old text) markup and
> > converting to man format with pod2man.  If people like this, expect more
> > work in the future to fill out these man pages as well as others.
> 
> I do like the idea of getting some manpages in.
> 
> The only danger is that of inconsistent documentation.  Hopefully the docs 
> will stay consistent with each other and with the tools themselves :-)  The 
> user manual is getting some attention, I believe, so that should help.

Yeh, honestly merging some of the user docs to manpages, or vica versa might
be a good idea.  Formating from pod -> man is something easy to do (and
something we've done for a lot of other projects), hence why I spent an hour
last night starting the process.  Presumably you could go equally well from
tex -> man and tex -> user manual to include the man pages as appendex or
something.

> That said, it might be nice if we could somehow unify the command / config 
> option help that's present in main.py and create.py of the xm package to 
> either be generated from the docs or vice versa.  Don't want to 
> overcomplicate the build process but it'd be unfortunate to duplicate all 
> this stuff.

Honestly, I'd rather pull out the context specific help and put it into
something like man pages instead.  A man page can be printed and skimmed
electronically.  I've always found that sectionalized help tends to be hard
to deal with, but that may be just how my brain works.

The biggest problem with sectionalized help like in xm today is that it is
only really good if you already know that a command could do what you want
it to do.  While combing through xm over the weekend, I found all sorts of
flags on sub commands I didn't know existed (and some which no longer
worked).  Having a full man page I could look through to see all my options
would have made that learning curve a lot less.

> > +Domain configuration files live in /etc/xen by default, though the
> > +full path to the config file must be specified in the I<xm create>
> > +command, so they can exist anywhere in the filesystem.
> 
> Minor point: I think if you don't use -f, the default search path is 
> in /etc/xen.

That didn't seem to be working for me recently, though I might have been
doing something odd.  I'll check again.

> Personally, I'd also suggest that we actually patch the relevant files in the 
> tools with a prominent warning reminding people what docs they should update 
> when they touch those files (just as we put a big warning telling people to 
> change the XC interface version when updating dom0_ops.c).

I think that would be a perfectly good idea. :)

        -Sean

-- 
__________________________________________________________________

Sean Dague                                       Mid-Hudson Valley
sean at dague dot net                            Linux Users Group
http://dague.net                                 http://mhvlug.org

There is no silver bullet.  Plus, werewolves make better neighbors
than zombies, and they tend to keep the vampire population down.
__________________________________________________________________

Attachment: pgptmD79oMMh6.pgp
Description: PGP signature

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel