[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Xen-devel] RE: [Xen-users] Push for Better Documentation

At 12:23 19/07/2007, Artur Linhart - Linux communication wrote:
OK, thank Zou for information. Do You know something about who is
responsible for the documentation creation etc, or where the developen
"pod"-s are stored and managed (some version control system, etc? I would be
good to work on documentation of something, what is not yet in processing by
somebody - or work on the themes together...

The docs are part of the Xen "source code", so if you grab the Xen source tarball, or install "mercurial" (hg)[1] and do "hg clone http://xenbits.xensource.com/xen-unstable";.

Using mercurial is the best way, since that means that you can:
1) Generate patches from your changes without keeping a second copy of everything you may want to change [2]. 2) Update your current source-directory to the latest unstable sources with "hg pull && hg update" 3) Roll back your changes if you decide that you haven't "done the right changes" [e.g. when you do "too many fingers on keyboard" in the editor and end up with half the file missing and no backup file]. You can even keep your own local set of changes and thus have a history of what you've done, and then export all changes as one patch-set.

[1] Here's the first place google found for downloading mercurial: http://linux.softpedia.com/get/Programming/Version-Control/Mercurial-9329.shtml

[2] Of course there is a second copy, but it's automatically maintained by mercurial rather than by manually. The drawback here is that since mercurial keeps ALL the changes, the "second copy" is quite a bit larger than the whole Xen source-tree - but it is compressed, so not that bad, and in a place where disk-space is counted in tens or hundreds of gigabytes, it's not a real problem.


        With regards


-----Original Message-----
From: Dylan Martin [mailto:dmartin@xxxxxxxxxxxx]
Sent: Wednesday, July 18, 2007 10:26 PM
To: Artur Linhart - Linux communication
Cc: 'Lev Lafayette'; 'Tom Horsley'; 'Christian Horn';
Subject: Re: [Xen-users] Push for Better Documentation

> I would help with it, but I never wrote some manual pages and have zero
> know-how about it... Right now I do not know if there are some tools for
> writing of man pages.

Okay, I said I'd get back to you about this, but I didn't think I'd
take this long... ;)

The source for the xen man pages is in pod format.  That's Plain Old
Documentation.  It's a really simple format used for perl.  If you're
on a unixy box, you can type 'man perlpod' to read all about it.
There are different commands to convert pod code to
man,html,text,latex etc... pod2man, pod2html etc..

If you look in the  docs dir in the source tarball, you'll see
dirs called man, man1, and man5.  The 'man' dir contains the pod
files.  Edit those and then run 'make' from inside the 'docs' dir.
The new man files will show up in man1 and man5.  To view man files
that aren't in the system man dirs, you can run "nroff -man filename |

Have fun!


> Where did You get even the old manual pages? In the binary tarball there
> the directory /usr/share/man with the subdirs man1 and man8, but there are

> Only 3 fragments (for example nothing about xm) and that's it...

It looks like Fedora 7 doesn't even bother to include the crusty old
man files.  Can't blame them for that...

__________ Informace od NOD32 2405 (20070718) __________

Tato zprava byla proverena antivirovym systemem NOD32.

Xen-devel mailing list

Xen-users mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.