thr3ads.net - Xen devel - [Xen-devel] [PATCH] add man pages to xen [Aug 2005]

If this information is useful, please help other people find it:
Share via:

Sean Dague

2005-Aug-01 03:07 UTC

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

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.

Signed-off-by: Sean Dague <sean@dague.net>

Diffstat output:
 Makefile               |   26 ++++++++++++++
 man/xm.pod.1           |    5 ++
 man/xmdomain.cfg.pod.5 |   87 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 118 insertions(+)

diff -urN xen-unstable.hg/docs/Makefile xen-unstable.sean/docs/Makefile
--- xen-unstable.hg/docs/Makefile	2005-07-01 09:10:32.000000000 -0400
+++ xen-unstable.sean/docs/Makefile	2005-07-31 21:38:39.000000000 -0400
@@ -1,5 +1,6 @@
 #!/usr/bin/make -f
 
+VERSION		= xen-unstable
 INSTALL		= install
 INSTALL_DIR	= $(INSTALL) -d -m0755
 
@@ -8,9 +9,15 @@
 LATEX		:= latex
 FIG2DEV		:= fig2dev
 LATEX2HTML	:= latex2html
+POD2MAN		:= pod2man
 
 pkgdocdir	:= /usr/share/doc/xen
+mandir		:= /usr/share/man
 
+DOC_MAN5SRC	:= $(wildcard man/*.pod.5)
+DOC_MAN1SRC	:= $(wildcard man/*.pod.1)
+DOC_MAN1	:= $(patsubst man/%.pod.1,man1/%.1,$(DOC_MAN1SRC))
+DOC_MAN5	:= $(patsubst man/%.pod.5,man5/%.5,$(DOC_MAN5SRC))
 DOC_TEX		:= $(wildcard src/*.tex)
 DOC_PS		:= $(patsubst src/%.tex,ps/%.ps,$(DOC_TEX))
 DOC_PDF		:= $(patsubst src/%.tex,pdf/%.pdf,$(DOC_TEX))
@@ -30,16 +37,35 @@
 	@if which $(LATEX2HTML) 1>/dev/null 2>/dev/null; then \
 	$(MAKE) $(DOC_HTML); fi
 
+man-pages:
+	@if which $(POD2MAN) 1>/dev/null 2>/dev/null; then \
+	$(MAKE) $(DOC_MAN1) $(DOC_MAN5); fi
+
+man1/%.1: man/%.pod.1 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed
''s/^man1.//''| \
+       		sed ''s/.1//''` -s 1 -c "Xen" $< $@
+
+man5/%.5: man/%.pod.5 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed
''s/^man5.//''| \
+		sed ''s/.5//''` -s 5 -c "Xen" $< $@
+
 clean:
 	rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~ 
 	rm -rf *.ilg *.log *.ind *.toc *.bak core
	rm -rf $(GFX) ps pdf html
+	rm -rf man5 
+	rm -rf man1
 
 install: all
 	rm -rf $(DESTDIR)$(pkgdocdir)
 	$(INSTALL_DIR) $(DESTDIR)$(pkgdocdir)
 	cp -dR ps $(DESTDIR)$(pkgdocdir)
 	cp -dR pdf $(DESTDIR)$(pkgdocdir)
+	$(INSTALL_DIR) $(DESTDIR)$(mandir)
+	cp -dR man1 $(DESTDIR)$(mandir)
+	cp -dR man5 $(DESTDIR)$(mandir)
 	[ ! -d html ] || cp -dR html $(DESTDIR)$(pkgdocdir)
 
 pdf/%.pdf: ps/%.ps
diff -urN xen-unstable.hg/docs/man/xmdomain.cfg.pod.5
xen-unstable.sean/docs/man/xmdomain.cfg.pod.5
--- xen-unstable.hg/docs/man/xmdomain.cfg.pod.5	1969-12-31 19:00:00.000000000
-0500
+++ xen-unstable.sean/docs/man/xmdomain.cfg.pod.5	2005-07-31 22:24:53.000000000
-0400
@@ -0,0 +1,87 @@
+=head1 NAME
+
+xmdomain.cfg - xm domain create config file format
+
+=head1 SYNOPSIS
+
+ /etc/xen/myxendomain
+ /etc/xen/myxendomain2
+ /etc/xen/auto/myxenautostarted
+
+=head1 DESCRIPTION
+
+The xm(1) program uses python executable config files to define
+domains to create from scratch.  Each of these config files needs to
+contain a number of required options, and may specify many more.
+
+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.
+
+/etc/xen/auto is a special case however, as domain config files in
+that directory will be started automatically at system boot if the
+xendomain init script is enabled.
+
+=head1 OPTIONS
+
+The following lists the most commonly used options for a domain config
+file.  
+
+=over 4
+
+=item I<kernel>
+
+The kernel image used in the domain.
+
+=item I<ramdisk>
+
+The initial ramdisk to be used in the domain.  Default xen domU
+kernels do not usually need a ramdisk.
+
+=item I<memory>
+
+The amount of memory, in megabytes to allocate to the domain when it
+starts.  Allocating insufficient memory for a domain may produce
+extremely bizarre behavior.
+
+=item I<name>
+
+A unique name for the domain.  You can not create 2 domains with the
+same name.
+
+=item I<root>
+
+Root stanza for the domain (required for Linux domains).
+
+=item I<disk>
+
+An array of disk stanzas 
+
+=back
+
+A bare minimal config file example might be as follows:
+
+    kernel = "/boot/vmlinuz-2.6-xenU"
+    memory = 128
+    name = "MyLinux"      
+    root = "/dev/hda1 ro"
+
+=head1 ADDITIONAL OPTIONS
+
+=over 4
+
+=item I<builder>
+
+=back
+
+=head1 SEE ALSO
+
+B<xm>(1)
+
+=head1 AUTHOR
+
+  Sean Dague <sean at dague dot net>
+
+=head1 BUGS
+
+Not all options are currently documented
diff -urN xen-unstable.hg/docs/man/xm.pod.1 xen-unstable.sean/docs/man/xm.pod.1
--- xen-unstable.hg/docs/man/xm.pod.1	1969-12-31 19:00:00.000000000 -0500
+++ xen-unstable.sean/docs/man/xm.pod.1	2005-07-31 18:01:12.000000000 -0400
@@ -0,0 +1,5 @@
+=head1 NAME
+
+xm - Xen management user interface
+
+


	-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.
__________________________________________________________________


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

Mark Williamson

2005-Aug-02 01:01 UTC

head link

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

> 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.

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.
> +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.

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).

Cheers,
Mark

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

Sean Dague

2005-Aug-02 03:12 UTC

head link

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

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.
__________________________________________________________________


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

Xen devel - Aug 2005 - [PATCH] add man pages to xen

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

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

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