Merge branch 'catalyst-spec-man-page' into catalyst_2old/catalyst_2

20 files changed, 649 insertions, 54 deletions

diff --git a/Makefile b/Makefile
index 30a0411f..016120a7 100644
--- a/Makefile
+++ b/Makefile
@@ -2,23 +2,33 @@
 # Licensed under GPL v2 or later
 
 PACKAGE_VERSION = `fgrep '__version__=' catalyst | sed 's|^__version__="\(.*\)"$$|\1|'`
-EXTRA_DIST = files/catalyst.1
-CLEAN_FILES = $(EXTRA_DIST) doc/subarches.generated.txt
+MAN_PAGE_SOURCES = $(wildcard doc/*.?.txt)
+MAN_PAGES = $(patsubst doc/%.txt,files/%,$(MAN_PAGE_SOURCES))
+MAN_PAGE_INCLUDES = doc/subarches.generated.txt doc/targets.generated.txt
+EXTRA_DIST = $(MAN_PAGES)
+GENERATED_FILES = $(MAN_PAGES) $(MAN_PAGE_INCLUDES)
 
 distdir = catalyst-$(PACKAGE_VERSION)
 
 
 all: $(EXTRA_DIST)
 
-files/catalyst.1: doc/catalyst.1.txt doc/subarches.generated.txt doc/asciidoc.conf Makefile catalyst
+files/%: doc/%.txt doc/asciidoc.conf Makefile catalyst
 	a2x --conf-file=doc/asciidoc.conf --attribute="catalystversion=$(PACKAGE_VERSION)" \
 		 --format=manpage -D files "$<"
 
+# Additional dependencies due to inclusion
+files/catalyst.1: doc/subarches.generated.txt
+files/catalyst-spec.5: doc/subarches.generated.txt doc/targets.generated.txt
+
 doc/subarches.generated.txt: $(wildcard arch/*.py) doc/make_subarch_table_guidexml.py
 	./doc/make_subarch_table_guidexml.py
 
+doc/targets.generated.txt: doc/make_target_table.py $(wildcard modules/*_target.py)
+	"./$<" > "$@"
+
 clean:
-	rm -f $(CLEAN_FILES)
+	rm -f $(GENERATED_FILES)
 	find -name '*.pyo' -delete
 
 check-git-repository:
diff --git a/doc/.gitignore b/doc/.gitignore
index b998e26d..2b8a08ca 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,2 +1,4 @@
 subarches.generated.txt
 subarches.generated.xml
+targets.generated.txt
+targets.generated.xml
diff --git a/doc/catalyst-spec.5.txt b/doc/catalyst-spec.5.txt
new file mode 100644
index 00000000..3be96fec
--- /dev/null
+++ b/doc/catalyst-spec.5.txt
@@ -0,0 +1,508 @@
+CATALYST-SPEC(5)
+================
+:man source:   catalyst {catalystversion}
+:man manual:   catalyst {catalystversion}
+
+
+NAME
+----
+catalyst-spec - Catalyst build specification files
+
+
+SYNOPSIS
+--------
+*catalyst* ['OPTIONS'] *-f* 'FILE'
+
+
+DESCRIPTION
+-----------
+
+*catalyst(1)* reads the specification file given with *-f* on the
+command line.  The file contains keyword-argument pairs, one per line,
+separated by a colon (`:`).  Subsequent indented lines continue the
+argument.  Lines starting with `#` and empty lines are interpreted as
+comments.  For example:
+
+---------------------------------
+# Select the subarch
+subarch: athlon-xp
+
+boot/use:
+  -*
+  multicall
+  readline
+  ssl
+---------------------------------
+
+The possible keywords and their meanings are as follows:
+
+Basic configuration
+~~~~~~~~~~~~~~~~~~~
+
+*subarch*::
+The subarch can be any of the supported catalyst subarches (example:
+`athlon-xp`).  See the *SUPPORTED ARCHITECTURES* section for a list of
+supported subarches.
+
+*version_stamp*::
+The version stamp is an identifier for the build.  It can be anything,
+but something date-like is recommended (example: `2006.1`).
+
+*target*::
+The target specifies what target we want catalyst to build (example:
+`stage3`).  Supported targets are:
+
+include::targets.generated.txt[tabsize=4]
+
+*rel_type*::
+The `rel_type` defines what kind of build we are doing (example:
+`default`).  This is merely another identifier, but it useful for
+allowing multiple concurrent builds.  Usually, `default` will suffice.
+
+*profile*::
+This is the system profile to be used by catalyst to build this target
+(example: `default/linux/x86/10.0/`).  It is specified as a relative
+path from `profiles` in your portage snapshot
+
+*snapshot*::
+This specifies which snapshot to use for building this target
+(example: `2006.1`).
+
+*source_subpath*::
+This specifies where the seed stage for this target comes from
+(example: `default/stage3-x86-2006.1`).  The path is relative to
+`$storedir/builds`.  The `rel_type` is also used as a path prefix for
+the seed.
+
+*distcc_hosts*::
+These are the hosts used as distcc slaves when distcc is enabled in
+your `catalyst.conf` (example: `127.0.0.1 192.168.0.1`).  It follows
+the same syntax as `distcc-config --set-hosts` and is entirely
+optional.
+
+*portage_confdir*::
+This is an optional directory containing portage configuration files
+(example: `/etc/portage`).  It follows the same syntax as
+`/etc/portage` and should be consistent across all targets to minimize
+problems.
+
+*portage_overlay*::
+This option specifies the location to a portage overlay that you would
+like to use when building this target (example: `/usr/local/portage`).
+
+*pkgcache_path*::
+This allows the optional directory containing the output packages for
+catalyst (example: `/tmp/packages`).  Mainly used as a way for
+different spec files to access the same cache directory.  Default
+behavior for this location is to be autogenerated under `$storedir`
+based on the spec file.
+
+*kerncache_path*::
+This allows the optional directory containing the output packages for
+kernel builds (example: `/tmp/kernel`).  Mainly used as a way for
+different spec files to access the same cache directory.  Default
+behavior is for this location to be autogenerated under `$storedir`
+based on the spec file.
+
+*<target>/type*::
+This option controls quite a bit of catalyst internals and sets up
+several defaults.  Each type behaves slightly differently and is
+explained below.
+  `gentoo-release-minimal`;; This creates an official minimal InstallCD.
+  `gentoo-release-universal`;; This creates an official universal InstallCD.
+  `gentoo-release-livecd`;; This creates an official LiveCD environment.
+  `gentoo-gamecd`;; This creates an official Gentoo GameCD.
+  `generic-livecd`;; This should be used for all non-official media.
+
+This setting is supported by the livecd targets.
+
+*<target>/builddate*::
+Set the build date of the `<target>` (example: `20060107`).  This
+setting is supported by the `netboot2` target.
+
+*<target>/readme*::
+This is for the README.txt on the root of the CD.  For Gentoo
+releases, we use a default README.txt, and this will be used on your
+CD if you do not provide one yourself.  We do not use this for the
+official releases.  This setting is supported by the livecd targets.
+
+*grp*::
+Since GRP is capable of building packages/source sets for more than
+one CD, this defines the layout for the directories under
+`$storedir/builds` (example: `src cd2`).
+
+Compilation
+~~~~~~~~~~~
+
+These options are only available when building a stage1 or stage2
+target and are all optional.  These allow for emulating the changes
+possible during a bootstrap.  Some possible uses of these would be
+building embedded stages requiring a different `CHOST` or building a
+stage2 with NPTL support from a stage1 tarball that is built without
+it.  If left blank, then the catalyst defaults from `arch.py` are
+used.
+
+*chost*::
+This option is used to change the CHOST from what is default in the
+profile to whatever you specify (example: `i686-pc-linux-gnu`).  This
+is useful for building NPTL, for example.
+
+*cflags*::
+This option allows you to change the default `CFLAGS` that will be
+used in building this stage (example: `-Os -pipe -fomit-frame-pointer
+-mcpu=i686`).  This really should remain generic, as putting
+optimizations flags here will build a stage1 tarball that is no longer
+generic.
+
+*cxxflags*::
+This is for setting the `CXXFLAGS` (example: `-Os -pipe
+-fomit-frame-pointer -mcpu=i686`).  Generally, this would be set to
+the same as `CFLAGS`.  In fact, it will mirror `CFLAGS` by default.
+
+*ldflags*::
+Setting this option sets `LDFLAGS` in `make.conf` in your stage
+(example: `-Wl,-O1 -Wl,-z,now`).  This would be useful for setting up
+an embedded or hardened system.
+
+Filesystem
+~~~~~~~~~~
+
+*livecd/fstype*::
+The fstype is used to determine what sort of CD we should build.  This
+is used to set the type of loopback filesystem that we will use on our
+CD.  Possible values are as follows:
+  `squashfs`;; This gives the best compression, but requires a kernel patch.
+  `zisofs`;; This uses in-kernel compression and is supported on all platforms.
+  `normal`;; This creates a loop without compression.
+  `noloop`;; This copies the files to the CD directly, without using a
+             loopback.
+
+*livecd/fsops*::
+The fsops are a list of optional parameters that can be passed to the
+tool which will create the filesystem specified in *livecd/fstype*
+(example: `-root-owned`).  It is valid for the following fstypes:
+`squashfs`, `jffs`, `jffs2`, and `cramfs`.
+
+*livecd/iso*::
+This is the full path and filename to the ISO image that the
+livecd-stage2 target will create (example:
+`/tmp/installcd-x86-minimal.iso`).
+
+*livecd/volid*::
+This option sets the volume ID of the CD created (example: `Gentoo
+Linux 2006.1 X86`).
+
+Bootloader
+~~~~~~~~~~
+
+*livecd/cdtar*::
+The cdtar is essentially the bootloader for the CD.  It also holds the
+main configuration for the bootloader.  On x86/amd64, it also can
+include a small memory testing application, called memtest86+
+(example:
+`/usr/lib/catalyst/livecd/cdtar/isolinux-2.13-memtest86+-cdtar.tar.bz2`).
+
+Kernel and boot issues
+~~~~~~~~~~~~~~~~~~~~~~
+
+*<target>/splash_theme*::
+This is where you set the splash theme (example: `livecd-2006.1`).
+This theme must be present in `/etc/splash`, before the kernel has
+completed building.  This setting is supported by the `stage4` and
+`livecd` targets.
+
+*boot/kernel*::
+This option is used to specify the number of kernels to build and also
+the labels that will be used by the CD bootloader to refer to each
+kernel image (example: `gentoo`).
+
+*boot/kernel/<label>/sources*::
+*netboot/kernel/sources*::
+This option tells catalyst which kernel sources to merge for this
+kernel label (example: `gentoo-sources`).  This can use normal portage
+atoms to specify a specific version.  `<label>` should match one of
+the labels given to *boot/kernel*.
+
+*boot/kernel/<label>/config*::
+*netboot/kernel/config*::
+This option is the full path and filename to a kernel `.config` file
+that is used by genkernel to compile the kernel this label applies to.
+`<label>` should match one of the labels given to *boot/kernel*.
+
+*boot/kernel/<label>/gk_kernargs*::
+This option sets genkernel parameters on a per-kernel basis and
+applies only to this kernel label.  This can be used for building
+options into only a single kernel, where compatibility may be an
+issue.  We do not use this on the official release media, but it
+follows the same syntax as *stage4/gk_mainargs*.  `<label>` should
+match one of the labels given to *boot/kernel*.
+
+*<target>/gk_mainargs*::
+This is a set of arguments that will be passed to genkernel for all
+kernels defined in this target (example: `--lvm --dmraid`).  It is
+useful for passing arguments to genkernel that are not otherwise
+available via the stage4-stage2 spec file.  This option is supported
+by the `stage4` and `livecd` targets.
+
+*boot/kernel/<label>/extraversion*::
+This option appends an extension to the name of your kernel, as viewed
+by a `uname -r`.  This also affects any modules built under this
+kernel label.  This is useful for having two kernels using the same
+sources to keep the modules from overwriting each other.  We do not
+use this on the official media.  `<label>` should match one of the
+labels given to *boot/kernel*.
+
+*boot/kernel/<label>/machine_type*::
+This option is only for ppc64 machines (example: `ibm`).  If used it
+will create the `/etc/yaboot.conf` entry used for booting an ibm
+powerpc machine.  `<label>` should match one of the labels given to
+*boot/kernel*.
+
+*boot/kernel/<label>/console*::
+This is only supported on ppc64 currently.  This entry sets up the
+console boot parameters required for sending the output to the
+appropriate console (example: `tty0 ttyS0`).  `<label>` should match
+one of the labels given to *boot/kernel*.
+
+*<target>/modblacklist*::
+This is for blacklisting modules from being hotplugged that are known
+to cause problems (example: `8139cp`).  Putting a module name here
+will keep it from being auto-loaded, even if it is detected by
+hotplug.  This setting is supported by the `stage4` and `livecd`
+targets.
+
+*netboot/kernel/use*::
+*boot/kernel/<label>/use*::
+This option sets the `USE` flags used to build the kernel and also any
+packages which are defined under this kernel label (example: `pcmcia
+usb -X`).  These `USE` flags are additive from the default `USE` for
+the specified profile.  `<label>` should match one of the labels given
+to *boot/kernel*.
+
+*boot/kernel/<label>/packages*::
+This option is for merging kernel-dependent packages and external
+modules that are configured against this kernel label (example:
+`pcmcia-cs speedtouch slmodem`).  `<label>` should match one of the
+labels given to *boot/kernel*.
+
+*livecd/bootargs*::
+This is a set of arguments that get passed to the bootloader for your
+CD (example: `dokeymap`).  It is used on the x86/amd64 release media
+to enable keymap selection.
+
+Netboot
+~~~~~~~
+
+*<target>/busybox_config*::
+The netboot target builds busybox for its root filesystem.  This
+option is where you specify the full path and filename to your busybox
+configuration (example: `/tmp/busybox.config`).  This setting is
+supported by the `netboot` and `netboot2` targets.
+
+*netboot/base_tarball*::
+This is the full path and filename to the tarball to use as the base
+for the netboot image (example:
+`/usr/lib/catalyst/netboot/netboot-base.tar.bz2`).
+
+Runlevels
+~~~~~~~~~
+
+*<target>/linuxrc*::
+This option allows you to specify your own linuxrc script for
+genkernel to use when building your CD.  This is not checked for
+functionality, so it is up to you to debug your own script.  We do not
+use one for the official release media.  This option is supported by
+the `stage4` and `livecd` targets.
+
+*<target>/rcadd*::
+This is for adding init scripts to runlevels.  The syntax for the init
+script is the script name, followed by a pipe, followed by the
+runlevel in which you want the script to run.  It looks like
+`spind|default` and is space delimited.  We do not use this on the
+official media, as catalyst sets up the runlevels correctly for us.
+This setting is supported by the `stage4` and `livecd` targets.
+
+*<target>/rcdel*::
+This is for removing init script from runlevels.  It is executed after
+the defaults shipped with catalyst, so it is possible to remove the
+defaults using this option.  It can follow the same syntax as
+*stage4/rcadd*, or you can leave the runlevel off to remove the script
+from any runlevels detected.  We do not use this on the official
+media.  This setting is supported by the `stage4` and `livecd` targets.
+
+Packages
+~~~~~~~~
+
+*<target>/use*::
+This is where you will build packages for updating a `stage3`.  These
+packages can be built with customized `USE` settings (example: `ipv6
+socks5 fbcon ncurses readline ssl`).  The settings here are additive
+to the default `USE` configured by the profile.  Leaving this blank
+will default to the system use flags.  It is very possible to cause
+quite a few problems with these, so be careful with whatever `USE`
+flags you add here.  This is generally used for adding some
+functionality that we do not want on by default for all Gentoo users,
+but that we want on by default in our binaries.  This setting is
+supported by the `stage4`, `netboot2`, `tinderbox`, and `grp` targets.
+
+*<target>/packages*::
+This is the set of packages that we will merge into the stage4 tarball
+(example: `livecd-tools dhcpcd acpid apmd gentoo-sources coldplug
+fxload irssi wpa_supplicant`).  They will be built with the `USE`
+flags configured above.  These packages must not depend on a
+configured kernel.  If the package requires a configured kernel, then
+it will be defined elsewhere.  This setting is supported by the
+`stage4`, `netboot2`, and `tinderbox` targets.
+
+*netboot/packages*::
+These package names are also labels used later when determining what
+files to copy into your netboot image (example: `raidtools
+e2fsprogs`).
+
+*<target>/packages/<label>/files*::
+This is where you tell catalyst which files from each package to copy
+into the netboot image.  `<label>` should match one of the labels
+given to *netboot/packages*.  For example:
+
+  netboot/packages/raidtools/files: /sbin/raidstart /sbin/mkraid
+
+This option is supported by the `netboot` and `netboot2` targets.
+
+*netboot/extra_files*::
+This is a list of any other files, not belonging to the above
+packages, that you would wish to have copied into your netboot image
+(example: `/lib/libresolv.so.2 /lib/libnss_compat.so.2`).
+
+*<target>/unmerge*::
+This is a list of packages that will be unmerged after all the kernels
+have been built (example: `autoconf automake libtool m4 bison`).
+There are no checks on these packages, so be careful what you add
+here.  They can potentially break your target.  This setting is
+supported by the `stage4` and `livecd` targets.
+
+*grp/<label>/type*::
+This tells catalyst what type of GRP set this list of packages will
+create (example: `srcset`).  Valid options here are `srcset` or
+`pkgset` to either download the source, or to build packages,
+respectively.  `<label>` should match one of the labels given to
+*grp*.
+
+*grp/<label>/packages*::
+This is our list of packages that will comprise our package set
+(example: `dante tsocks sys-apps/eject minicom`).  Packages listed for
+a `srcset` label should be used for grabbing things that need a
+compiled kernel to build, or things listed in the Handbook that should
+be available before the first reboot during an install.  Pagekages
+listed for a `pkgset` label will be fetched, compiled, and installed
+in the target.  `<label>` should match one of the labels given to
+*grp*.
+
+Miscellaneous
+~~~~~~~~~~~~~
+
+*<target>/fsscript*::
+A fsscript is simply a shell script that is copied into the chroot of
+the build after the kernel(s) and any external modules have been
+compiled and is executed within the chroot.  It can contain any
+commands that are available via the packages installed by our stages
+or by the packages installed during the stage4-stage1 build.  We do
+not use one for the official release media, so there will not be one
+listed below.  The syntax is simply the full path and filename to the
+shell script that you wish to execute (example:
+`/path/to/fsscript.sh`).  The script is copied into the chroot by
+catalyst automatically.  This setting is supported by the `stage4` and
+`livecd` targets.
+
+*<target>/motd*::
+This is for the message of the day.  It is not required for release
+media, as catalyst builds a default motd when the *<target>/type* is
+set to one of the `gentoo-*` options.  This setting overrides the
+default motd even on official media.  This setting is supported by the
+`stage4` and `livecd` targets.
+
+*<target>/root_overlay*::
+This overlay is dropped onto the filesystem within the loop.  This can
+be used for such things as updating configuration files or adding
+anything else you would want within your target filesystem.  Files
+added here are available when `docache` is used.  We do not use this
+on the official media.  This setting is supported by the `stage4` and
+`livecd` targets.
+
+*livecd/overlay*::
+This overlay is dropped onto the target filesystem and is outside any
+loop which has been configured (example: `/tmp/overlay-minimal`).
+This is typically used for adding the documentation, distfiles,
+snapshots, and stages to the official media.  These files will not be
+available if `docache` is enabled, as they are outside the loop.
+
+*<target>/xinitrc*::
+This is used by catalyst to copy the specified file to
+`/etc/X11/xinit/xinitrc` and is used by the *<target>/type*
+`gentoo-gamecd` and `generic-livecd`.  While the file will still be
+copied for any *<target>/type*, catalyst will only create the
+necessary `/etc/startx` for those types, so X will not be
+automatically started.  This is useful also for setting up X on a CD
+where you do not wish X to start automatically.  We do not use this on
+the release media.  This setting is supported by the `stage4` and
+`livecd` targets.
+
+*livecd/xdm*::
+This is used by catalyst to determine which display manager you wish
+to become the default (example: `gdm`).  This is used on the official
+Gentoo LiveCD and is valid for any `livecd/type`.
+
+*livecd/xsession*::
+This is used by catalyst to determine which X session should be
+started by default by the display manager (example: `gnome`).  This is
+used on the official Gentoo LiveCD and is valid for any livecd/type.
+
+*<target>/users*::
+This option is used to create non-root users on your target.  It takes
+a space separated list of user names.  These users will be added to
+the following groups: `users`, `wheel`, `audio`, `games`, `cdrom`, and
+`usb`.  If this is specified in your spec file, then the first user is
+also the user used to start X.  We do not use this on the release
+media.  This setting is supported by the `stage4` and `livecd` targets.
+
+*<target>/empty*::
+This option is used to empty the directories listed (example:
+`/var/tmp /var/cache /var/db`).  It is useful for getting rid of files
+that don't belong to a particular package, or removing files from a
+package that you wish to keep, but won't need the full functionality.
+This setting is supported by the `stage4` and `livecd` targets.
+
+*<target>/rm**::
+This option tells catalyst to clean specific files from the filesystem
+and is very useful in cleaning up stray files in `/etc` left over
+after *stage4/unmerge* (example: `/lib/*.a /usr/lib/*.a`).  This
+setting is supported by the `stage4` and `livecd` targets.
+
+*gamecd/conf*::
+This option is only used when creating a GameCD.  This specifies the
+file that contains the definitions for `GAME_NAME` and
+`GAME_EXECUTABLE`, which are used by the GameCD scripts to set some
+specific options for the game.  This is not used on the release media.
+
+FILES
+-----
+Example specfiles can be found in '/usr/share/doc/catalyst-{catalystversion}/examples'.
+An example configuration file can be found at '/etc/catalyst/catalyst.conf'.
+
+
+SUPPORTED ARCHITECTURES
+-----------------------
+The following table shows the list of supported architectures as well as
+the list of valid strings for key 'subarch'.
+
+include::subarches.generated.txt[tabsize=4]
+
+
+BUGS
+----
+An up-to-date list of Catalyst bugs can always be found listed on the Gentoo
+Linux bug-tracking system at 'http://bugs.gentoo.org'.
+
+
+SEE ALSO
+--------
+*catalyst(1)*
diff --git a/doc/catalyst.1.txt b/doc/catalyst.1.txt
index b7807a51..4d51eb01 100644
--- a/doc/catalyst.1.txt
+++ b/doc/catalyst.1.txt
@@ -114,13 +114,6 @@ An up-to-date list of Catalyst bugs can always be found listed on the Gentoo
 Linux bug-tracking system at 'http://bugs.gentoo.org'.
 
 
-SEE ALSO
---------
-A more in-depth examination of Catalyst options and procedures can be found
-linked from the *catalyst* project page, which is located at
-'http://www.gentoo.org/proj/en/releng/catalyst'.
-
-
 NOTES
 -----
 *catalyst* is conceptually derived from the Gentoo livecd-ng and Gentoo
@@ -138,3 +131,12 @@ AUTHORS
 - Raul Porcel <armin76@gentoo.org>
 - Sebastian Pipping <sping@gentoo.org>
 - Matt Turner <mattst88@gentoo.org>
+
+
+SEE ALSO
+--------
+*catalyst-spec(5)*
+
+Also, a more in-depth examination of Catalyst options and procedures can be found
+linked from the *catalyst* project page, which is located at
+'http://www.gentoo.org/proj/en/releng/catalyst'.
diff --git a/doc/make_target_table.py b/doc/make_target_table.py
new file mode 100755
index 00000000..e5e25f00
--- /dev/null
+++ b/doc/make_target_table.py
@@ -0,0 +1,42 @@
+#!/usr/bin/env python
+# Copyright (C) 2012 W. Trevor King <wking@drexel.edu>
+# Copyright (C) 2012 Sebastian Pipping <sebastian@pipping.org>
+# Licensed under GPL v2 or later
+
+# This script should be run from the root of the catalyst source.
+
+from __future__ import print_function
+
+import sys as _sys
+
+_sys.path.insert(0, 'modules')  # so we can find the `catalyst` module
+
+import glob
+import re
+
+
+def key_netboot_before_netboot2((target_name, module)):
+	return target_name + '1'
+
+
+if __name__ == '__main__':
+	extractor = re.compile('^modules/(([^ ]+)_target).py$')
+	targets = list()
+	for filename in sorted(glob.glob('modules/*_target.py')):
+		if 'generic' in filename:
+			continue
+
+		match = extractor.match(filename)
+		target_name = match.group(2).replace('_', '-')
+		module_name = match.group(1)
+
+		__import__(module_name)
+		module = _sys.modules[module_name]
+
+		targets.append((target_name, module))
+
+	for target_name, module in sorted(targets, key=key_netboot_before_netboot2):
+		print('`%s`;;' % target_name)
+		# Replace blank lines with `+` (asciidoc list item continuation)
+		print(module.__doc__.strip().replace('\n\n', '\n+\n'))
+		print('')
diff --git a/files/.gitignore b/files/.gitignore
index 10acc025..4a4f038b 100644
--- a/files/.gitignore
+++ b/files/.gitignore
@@ -1 +1,3 @@
 catalyst.1
+catalyst-spec.5
+
diff --git a/modules/embedded_target.py b/modules/embedded_target.py
index 2ab8cc5a..6d34a576 100644
--- a/modules/embedded_target.py
+++ b/modules/embedded_target.py
@@ -1,13 +1,14 @@
-
 """
-This class works like a 'stage3'.  A stage2 tarball is unpacked, but instead
-of building a stage3, it emerges a 'system' into another directory
-inside the 'stage2' system.  This way we do not have to emerge gcc/portage
-into the staged system.
+Enbedded target, similar to the stage2 target, builds upon a stage2 tarball.
 
-It sounds real complicated but basically it runs
-ROOT=/tmp/submerge emerge --blahblah foo bar
+A stage2 tarball is unpacked, but instead
+of building a stage3, it emerges @system into another directory
+inside the stage2 system.  This way, we do not have to emerge GCC/portage
+into the staged system.
+It may sound complicated but basically it runs
+ROOT=/tmp/submerge emerge --something foo bar .
 """
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
 
 import os,string,imp,types,shutil
 from catalyst_support import *
@@ -15,7 +16,9 @@ from generic_stage_target import *
 from stat import *
 
 class embedded_target(generic_stage_target):
-
+	"""
+	Builder class for embedded target
+	"""
 	def __init__(self,spec,addlargs):
 		self.required_values=[]
 		self.valid_values=[]
diff --git a/modules/generic_stage_target.py b/modules/generic_stage_target.py
index 5947e9a1..c4ef239c 100644
--- a/modules/generic_stage_target.py
+++ b/modules/generic_stage_target.py
@@ -1,9 +1,3 @@
-
-"""
-This class does all of the chroot setup, copying of files, etc. It is
-the driver class for pretty much everything that Catalyst does.
-"""
-
 import os,string,imp,types,shutil
 from catalyst_support import *
 from generic_target import *
@@ -11,7 +5,10 @@ from stat import *
 import catalyst_lock
 
 class generic_stage_target(generic_target):
-
+	"""
+	This class does all of the chroot setup, copying of files, etc. It is
+	the driver class for pretty much everything that Catalyst does.
+	"""
 	def __init__(self,myspec,addlargs):
 		self.required_values.extend(["version_stamp","target","subarch",\
 			"rel_type","profile","snapshot","source_subpath"])
diff --git a/modules/generic_target.py b/modules/generic_target.py
index 82a4c56b..fe96bd73 100644
--- a/modules/generic_target.py
+++ b/modules/generic_target.py
@@ -1,12 +1,9 @@
-
-"""
-The toplevel class for generic_stage_target. This is about as generic as we get.
-"""
-
 from catalyst_support import *
 
 class generic_target:
-
+	"""
+	The toplevel class for generic_stage_target. This is about as generic as we get.
+	"""
 	def __init__(self,myspec,addlargs):
 		addl_arg_parse(myspec,addlargs,self.required_values,self.valid_values)
 		self.settings=myspec
diff --git a/modules/grp_target.py b/modules/grp_target.py
index b077d9c8..88a91c78 100644
--- a/modules/grp_target.py
+++ b/modules/grp_target.py
@@ -1,13 +1,16 @@
-
 """
-The builder class for GRP (Gentoo Reference Platform) builds.
+Gentoo Reference Platform (GRP) target
 """
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
 
 import os,types,glob
 from catalyst_support import *
 from generic_stage_target import *
 
 class grp_target(generic_stage_target):
+	"""
+	The builder class for GRP (Gentoo Reference Platform) builds.
+	"""
 	def __init__(self,spec,addlargs):
 		self.required_values=["version_stamp","target","subarch",\
 			"rel_type","profile","snapshot","source_subpath"]
diff --git a/modules/livecd_stage1_target.py b/modules/livecd_stage1_target.py
index 0d5c97c8..58e2e80e 100644
--- a/modules/livecd_stage1_target.py
+++ b/modules/livecd_stage1_target.py
@@ -1,12 +1,15 @@
-
 """
-Builder class for LiveCD stage1.
+LiveCD stage1 target
 """
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
 
 from catalyst_support import *
 from generic_stage_target import *
 
 class livecd_stage1_target(generic_stage_target):
+	"""
+	Builder class for LiveCD stage1.
+	"""
 	def __init__(self,spec,addlargs):
 		self.required_values=["livecd/packages"]
 		self.valid_values=self.required_values[:]
diff --git a/modules/livecd_stage2_target.py b/modules/livecd_stage2_target.py
index 2b126ed2..11dcc632 100644
--- a/modules/livecd_stage2_target.py
+++ b/modules/livecd_stage2_target.py
@@ -1,13 +1,16 @@
-
 """
-Builder class for a LiveCD stage2 build.
+LiveCD stage2 target, builds upon previous LiveCD stage1 tarball
 """
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
 
 import os,string,types,stat,shutil
 from catalyst_support import *
 from generic_stage_target import *
 
 class livecd_stage2_target(generic_stage_target):
+	"""
+	Builder class for a LiveCD stage2 build.
+	"""
 	def __init__(self,spec,addlargs):
 		self.required_values=["boot/kernel"]
 		
diff --git a/modules/netboot2_target.py b/modules/netboot2_target.py
index 444f873c..c4d8311c 100644
--- a/modules/netboot2_target.py
+++ b/modules/netboot2_target.py
@@ -1,13 +1,16 @@
-
 """
-Builder class for a netboot build, version 2
+netboot target, version 2
 """
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
 
 import os,string,types
 from catalyst_support import *
 from generic_stage_target import *
 
 class netboot2_target(generic_stage_target):
+	"""
+	Builder class for a netboot build, version 2
+	"""
 	def __init__(self,spec,addlargs):
 		self.required_values=[
 			"boot/kernel"
diff --git a/modules/netboot_target.py b/modules/netboot_target.py
index 92c1b045..2f2435e3 100644
--- a/modules/netboot_target.py
+++ b/modules/netboot_target.py
@@ -1,13 +1,16 @@
-
 """
-Builder class for a netboot build.
+netboot target, version 1
 """
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
 
 import os,string,types
 from catalyst_support import *
 from generic_stage_target import *
 
 class netboot_target(generic_stage_target):
+	"""
+	Builder class for a netboot build.
+	"""
 	def __init__(self,spec,addlargs):
 		self.valid_values = [
 			"netboot/kernel/sources",
diff --git a/modules/snapshot_target.py b/modules/snapshot_target.py
index 0609377b..a427b191 100644
--- a/modules/snapshot_target.py
+++ b/modules/snapshot_target.py
@@ -1,6 +1,5 @@
-
 """
-Builder class for snapshots.
+Snapshot target
 """
 
 import os
@@ -8,6 +7,9 @@ from catalyst_support import *
 from generic_stage_target import *
 
 class snapshot_target(generic_stage_target):
+	"""
+	Builder class for snapshots.
+	"""
 	def __init__(self,myspec,addlargs):
 		self.required_values=["version_stamp","target"]
 		self.valid_values=["version_stamp","target"]
diff --git a/modules/stage1_target.py b/modules/stage1_target.py
index a6eb4352..32e63344 100644
--- a/modules/stage1_target.py
+++ b/modules/stage1_target.py
@@ -1,12 +1,15 @@
-
 """
-Builder class for a stage1 installation tarball build.
+stage1 target
 """
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
 
 from catalyst_support import *
 from generic_stage_target import *
 
 class stage1_target(generic_stage_target):
+	"""
+	Builder class for a stage1 installation tarball build.
+	"""
 	def __init__(self,spec,addlargs):
 		self.required_values=[]
 		self.valid_values=["chost"]
diff --git a/modules/stage2_target.py b/modules/stage2_target.py
index a5135b25..f5297212 100644
--- a/modules/stage2_target.py
+++ b/modules/stage2_target.py
@@ -1,12 +1,15 @@
-
 """
-Builder class for a stage2 installation tarball build.
+stage2 target, builds upon previous stage1 tarball
 """
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
 
 from catalyst_support import *
 from generic_stage_target import *
 
 class stage2_target(generic_stage_target):
+	"""
+	Builder class for a stage2 installation tarball build.
+	"""
 	def __init__(self,spec,addlargs):
 		self.required_values=[]
 		self.valid_values=["chost"]
diff --git a/modules/stage3_target.py b/modules/stage3_target.py
index 6ebdc495..8c839dfc 100644
--- a/modules/stage3_target.py
+++ b/modules/stage3_target.py
@@ -1,12 +1,15 @@
-
 """
-Builder class for a stage3 installation tarball build.
+stage3 target, builds upon previous stage2/stage3 tarball
 """
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
 
 from catalyst_support import *
 from generic_stage_target import *
 
 class stage3_target(generic_stage_target):
+	"""
+	Builder class for a stage3 installation tarball build.
+	"""
 	def __init__(self,spec,addlargs):
 		self.required_values=[]
 		self.valid_values=[]
diff --git a/modules/stage4_target.py b/modules/stage4_target.py
index cc8e6c02..591f9b20 100644
--- a/modules/stage4_target.py
+++ b/modules/stage4_target.py
@@ -1,12 +1,15 @@
-
 """
-Builder class for stage4.
+stage4 target, builds upon previous stage3/stage4 tarball
 """
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
 
 from catalyst_support import *
 from generic_stage_target import *
 
 class stage4_target(generic_stage_target):
+	"""
+	Builder class for stage4.
+	"""
 	def __init__(self,spec,addlargs):
 		self.required_values=["stage4/packages"]
 		self.valid_values=self.required_values[:]
diff --git a/modules/tinderbox_target.py b/modules/tinderbox_target.py
index 42ad6eb8..9cc1acc9 100644
--- a/modules/tinderbox_target.py
+++ b/modules/tinderbox_target.py
@@ -1,12 +1,15 @@
-
 """
-builder class for the tinderbox target
+Tinderbox target
 """
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
 
 from catalyst_support import *
 from generic_stage_target import *
 
 class tinderbox_target(generic_stage_target):
+	"""
+	Builder class for the tinderbox target
+	"""
 	def __init__(self,spec,addlargs):
 		self.required_values=["tinderbox/packages"]
 		self.valid_values=self.required_values[:]