Imported example files from catalyst 1.1.9 to make them more verbose.

git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/catalyst/trunk@609 d1e1f19c-881f-0410-ab34-b69fee027534

9 files changed, 499 insertions, 485 deletions

diff --git a/ChangeLog b/ChangeLog
index 674bbbcc..ffbdf853 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,14 @@
 # ChangeLog for gentoo/src/catalyst 
 # Copyright 2002-2005 Gentoo Foundation; Distributed under the GPL v2
-# $Header: /var/cvsroot/gentoo/src/catalyst/ChangeLog,v 1.223 2005/04/18 14:11:23 rocket Exp $
+# $Header: /var/cvsroot/gentoo/src/catalyst/ChangeLog,v 1.224 2005/04/20 18:34:22 wolf31o2 Exp $
+
+  20 Apr 2005; Chris Gianelloni <wolf31o2@gentoo.org>
+  examples/fsscript.sh.example, examples/gamecd.conf.example,
+  examples/generic_stage_template.spec, examples/grp_template.spec,
+  examples/livecd-stage1_template.spec,
+  examples/livecd-stage2_template.spec, examples/netboot_template.spec,
+  examples/snapshot_template.spec:
+  Imported example files from catalyst 1.1.9 to make them more verbose.
 
   18 Apr 2005; Eric Edgar <rocket@gentoo.org> modules/grp_target.py:
   Fix grp/use bug #89365
diff --git a/examples/fsscript.sh.example b/examples/fsscript.sh.example
index 47dd5a67..d34ced13 100644
--- a/examples/fsscript.sh.example
+++ b/examples/fsscript.sh.example
@@ -1,9 +1,9 @@
 #!/bin/bash
 
-# This is an example fsscript for use with the livecd-stage2 target via the
-# spec file option livecd/fsscript.  Basically, this file is copied to the
-# livecd rootfs at livecd creation time and then executed from within the
-# chroot.
+# This is an example fsscript for use with the livecd-stage2 target (key
+# livecd/fsscript).  This file is copied into the rootfs of the CD after the
+# kernel(s) and any external modules have been compiled and is then executed
+# within the context of the chroot.
 
-# Example, I want to add specific nameservers to the LiveCD's resolv.conf:
+# Example, I want to add specific nameservers to the CD's resolv.conf:
 echo "192.168.0.1" >> /etc/resolv.conf
diff --git a/examples/gamecd.conf.example b/examples/gamecd.conf.example
index 3c045393..955eac4e 100644
--- a/examples/gamecd.conf.example
+++ b/examples/gamecd.conf.example
@@ -1,9 +1,6 @@
 #!/bin/bash
-# Copyright 1999-2004 Gentoo Foundation
-# Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo/src/catalyst/examples/gamecd.conf.example,v 1.2 2005/04/08 22:39:45 wolf31o2 Exp $
 
 # these variables are to be used for creating the menu entry and also to tell
-# the CD what to execute
+# the CD what to execute once X starts
 GAME_NAME="Unreal Tournament 2004 Demo"
 GAME_EXECUTABLE="/usr/games/bin/ut2004-demo"
diff --git a/examples/generic_stage_template.spec b/examples/generic_stage_template.spec
index 3889d170..4a15ddcc 100644
--- a/examples/generic_stage_template.spec
+++ b/examples/generic_stage_template.spec
@@ -1,51 +1,60 @@
-## generic installation stage specfile
-## used to build a stage1, stage2, or stage3 installation tarball
+# generic installation stage specfile
+# used to build a stage1, stage2, or stage3 installation tarball
 
-## John Davis <zhen@gentoo.org>
-
-# subarch can be any of the supported Catalyst subarches (like athlon-xp). Refer
-# to the catalyst reference manual (http://www.gentoo.org/proj/en/releng/catalyst) for supported arches.
+# The subarch can be any of the supported catalyst subarches (like athlon-xp).
+# Refer to the catalyst reference manual for suppurted subarches.
+# http://www.gentoo.org/proj/en/releng/catalyst/reference.xml
 # example:
 # subarch: athlon-xp
 subarch:
 
-# version stamp is an identifier for the build. can be anything you want it to be, but it
-# is usually a date.
+# The version stamp is an identifier for the build.  It can be anything you wish
+# it to be, but it is usually a date.
 # example:
-# version_stamp: 2004.2
+# version_stamp: 2005.0
 version_stamp: 
 
-# target specifies what type of build Catalyst is to do. check the catalyst reference manual
-# for supported targets.
+# The target specifies what target we want catalyst to do. For stages, the
+# supported targets are: stage1 stage2 stage3
 # example:
 # target: stage2
 target:
 
-# rel_type defines what kind of build we are doing. usually, default will suffice.
+# The rel_type defines what kind of build we are doing.  This is merely another
+# identifier, but it useful for allowing multiple concurrent builds.  Usually,
+# default will suffice.
 # example:
 # rel_type: default
 rel_type:
 
-# system profile used to build the media
+# This is the system profile to be used by catalyst to build this target.  It is
+# specified as a relative path from /usr/portage/profiles.
 # example:
-# profile: default-x86-2004.0
+# profile: default-linux/x86/2005.0
 profile:
 
-# which snapshot to use
+# This specifies which snapshot to use for building this target.
 # example:
-# snapshot: 20040614
+# snapshot: 20050324
 snapshot:
 
-# where the seed stage comes from, path is relative to $clst_sharedir (catalyst.conf)
+# This specifies where the seed stage comes from for this target,  The path is
+# relative to $clst_sharedir/builds.  The rel_type is also used as a path prefix
+# for the seed.
 # example:
-# default/stage3-x86-2004.1
+# default/stage3-x86-2004.3
 source_subpath:
 
-# hosts used as distcc slaves (distcc required in options (catalyst.conf)
+# These are the hosts used as distcc slaves when distcc is enabled in your 
+# catalyst.conf.  It follows the same syntax as distcc-config --set-hosts and
+# is entirely optional.
 # example:
 # distcc_hosts: 127.0.0.1 192.168.0.1
+distcc_hosts:
 
-# optional directory containing portage configuration files
+# This is an optional directory containing portage configuration files.  It
+# follows the same syntax as /etc/portage and should be consistent across all
+# targets to minimize problems.
 # example:
 # portage_confdir: /etc/portage
-# portage_confdir:
+portage_confdir:
diff --git a/examples/grp_template.spec b/examples/grp_template.spec
index 4674d1c5..7aea887f 100644
--- a/examples/grp_template.spec
+++ b/examples/grp_template.spec
@@ -1,188 +1,100 @@
-## generic GRP (Gentoo Reference Platform) specfile
-## used to build a GRP set
+# generic GRP (Gentoo Reference Platform) specfile
+# used to build a GRP set
 
-## John Davis <zhen@gentoo.org>
-
-# subarch can be any of the supported Catalyst subarches (like athlon-xp). Refer
-# to the catalyst reference manual (http://www.gentoo.org/proj/en/releng/catalyst) for supported arches.
+# The subarch can be any of the supported catalyst subarches (like athlon-xp).
+# Refer to the catalyst reference manual for suppurted subarches.
+# http://www.gentoo.org/proj/en/releng/catalyst/reference.xml
 # example:
 # subarch: athlon-xp
 subarch:
 
-# version stamp is an identifier for the build. can be anything you want it to be, but it
-# is usually a date.
+# The version stamp is an identifier for the build.  It can be anything you wish# it to be, but it is usually a date.
 # example:
-# version_stamp: 2004.2
-version_stamp: 
+# version_stamp: 2005.0
+version_stamp:
 
-# target specifies what type of build Catalyst is to do. check the catalyst reference manual
-# for supported targets.
+# The target specifies what target we want catalyst to do. For GRP, the
+# supported targets are: grp
 # example:
 # target: grp
 target: grp 
 
-# rel_type defines what kind of build we are doing. usually, default will suffice.
+# The rel_type defines what kind of build we are doing.  This is merely another
+# identifier, but it useful for allowing multiple concurrent builds.  Usually,
+# default will suffice.
 # example:
 # rel_type: default
 rel_type:
 
-# system profile used to build the media
+# This is the system profile to be used by catalyst to build this target.  It is# specified as a relative path from /usr/portage/profiles.
 # example:
-# profile: default-x86-2004.0
+# profile: default-linux/x86/2005.0
 profile:
 
-# which snapshot to use
+# This specifies which snapshot to use for building this target.
 # example:
-# snapshot: 20040614
+# snapshot: 20050324
 snapshot:
 
-# where the seed stage comes from, path is relative to $clst_sharedir (catalyst.conf)
+# This specifies where the seed stage comes from for this target,  The path is
+# relative to $clst_sharedir/builds.  The rel_type is also used as a path prefix# for the seed.
+# example:
+# default/stage3-x86-2004.3
+source_subpath:
+
+# These are the hosts used as distcc slaves when distcc is enabled in your
+# catalyst.conf.  It follows the same syntax as distcc-config --set-hosts and
+# is entirely optional.
 # example:
-# default/stage3-x86-2004.1
+# distcc_hosts: 127.0.0.1 192.168.0.1
+distcc_hosts:
 
-# directories to organize the GRP into
+# This is an optional directory containing portage configuration files.  It
+# follows the same syntax as /etc/portage and should be consistent across all
+# targets to minimize problems.
+# example:
+# portage_confdir: /etc/portage
+portage_confdir:
+
+# Since GRP is capable of building packages/source sets for more than one CD,
+# this defines the layout for the directories under $clst_sharedir/builds.
+# example:
+# grp: src cd2
 grp: src cd2
 
-# use variables to use when building the GRP set
-grp/use: 
-	gtk2 
-	gnome 
-	kde 
-	qt 
-	bonobo 
-	cdr 
-	esd 
-	gtkhtml 
-	mozilla
-	mysql
-	perl
-	ruby
-	tcltk
-	acl
-	cups
-	ldap
-	ssl
-	tcpd
-	-svga
+# GRP is also able to build packages with customized USE settings.  However, 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.  Some examples would be things like the
+# socks5 USE flag.
+# example:
+# grp/use: gtk2 gnome kde qt bonobo cdr esd gtkhtml mozilla mysql perl ruby tcltk cups ldap ssl tcpd -svga
+grp/use:
 
-# okay, two things here. first, we know we are building stuff to go into the "src" directory
-# because of the grp/src line (first part before the / is the build type, second part is
-# directory specified in the grp: key). It is identified as a "srcset" which means that these
-# packages will be *fetched only* and not compiled.
-grp/src/type: srcset
+# This tells catalyst what type of GRP set this list of packages will create.
+# Valid options here are srcset or pkgset to either download the source, or to
+# build packages, respectively.
+# example:
+# grp/src/type: srcset
+grp/src/type:
+
+# Since this is a srcset, these ebuilds will have their distfiles fetched and
+# the distfiles will be stored in the src directory under $clst_sharedir/builds.
+# Packages will not be made out of this list.  We use this 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.
+# example:
+# grp/src/packages: gentoo-sources udev vanilla-sources rp-pppoe speedtouch fcdsl fritzcapi globespan-adsl pptpclient slmodem lvm2 evms iputils vixie-cron fcron dcron sysklogd metalog syslog-ng raidtools jfsutils xfsprogs reiserfsprogs dosfstools ntfsprogs lilo grub isdn4k-utils iproute2 wireless-tools wpa_supplicant pcmcia-cs hotplug coldplug dhcpcd slocate genkernel ipw2100 ipw2200 fxload logrotate
 grp/src/packages:
-	gentoo-sources
-	gentoo-dev-sources
-	vanilla-sources
-	development-sources
-	iptables
-	gpm
-	rp-pppoe
-	ppp
-	speedtouch
-	pciutils
-	hdparm
-	hotplug
-	aumix
-	xfree
-	iputils
-	vixie-cron
-	sysklogd
-	metalog
-	syslog-ng
-	raidtools
-	jfsutils
-	xfsprogs
-	reiserfsprogs
-	lvm-user
-	dosfstools
-	lilo
-	grub
-	superadduser
-	gentoolkit
-	chkrootkit
-	minicom
-	lynx
-	rpm2targz
-	parted
-	rdate
-	whois
-	tcpdump
-	cvs
-	unzip
-	zip
-	netcat
-	isdn4k-utils
-	nforce-net
-	nforce-audio
-	iproute
-	nvidia-kernel
-	nvidia-glx
-	ati-drivers
-	e100
-	e1000
-	wireless-tools
-	pcmcia-cs
-	emu10k1
-	evms
-	linux-wlan-ng
-	sys-apps/eject
-	genkernel
 
-# same as above, but this time we have a "pkgset". this means that we will fetch and compile
-# the desired package
-grp/cd2/type: pkgset
+# This is mostly here for completeness.  This is the pkgset definition.
+# example:
+# grp/cd2/type: pkgset
+grp/cd2/type:
+
+# This is our list of packages that will comprise our package set.  These are
+# fetched, compiled, and the packages are stored under $clst_sharedir/builds.
+# example:
+# grp/cd2/packages: dante tsocks sys-apps/eject minicom links acpid apmd parted whois tcpdump cvs zip unzip netcat partimage app-admin/sudo app-cdr/cdrtools gnome emacs dev-lang/ruby enlightenment kde mozilla-firefox mozilla-thunderbird xfce4 openbox fluxbox sylpheed openoffice-bin gimp xemacs xmms abiword gaim xchat pan tetex xcdroast k3b samba nmap gradm ettercap ethereal mplayer
 grp/cd2/packages:
-	pciutils
-	hdparm
-	hotplug
-	aumix
-	xfree
-	dante
-	tsocks
-	chkrootkit
-	minicom
-	lynx
-	rpm2targz
-	parted
-	rdate
-	whois
-	tcpdump
-	cvs
-	unzip
-	zip
-	netcat
-	partimage
-	DirectFB
-	apache
-	app-cdr/cdrtools
-	gnome
-	evolution
-	cups
-	dev-db/mysql
-	dev-lang/ruby
-	emacs
-	enlightenment
-	fluxbox
-	kde
-	libsdl
-	mozilla
-	xfce4
-	openbox
-	openoffice
-	sylpheed
-	vim
-	xemacs
-	xmms
-	mozilla-firefox
-	abiword
-	gaim
-	tetex
-	xcdroast
-	samba
-	nmap
-	gradm
-	ettercap
-	xchat
-	dante
-	tsocks
diff --git a/examples/livecd-stage1_template.spec b/examples/livecd-stage1_template.spec
index 5e2daf05..e09c1ea5 100644
--- a/examples/livecd-stage1_template.spec
+++ b/examples/livecd-stage1_template.spec
@@ -1,98 +1,74 @@
-## livecd-stage1 example specfile
-## used to build a livecd-stage1
+# livecd-stage1 example specfile
+# used to build a livecd-stage1
 
-## John Davis <zhen@gentoo.org>
-
-# subarch can be any of the supported Catalyst subarches (like athlon-xp). Refer
-# to the catalyst reference manual (http://www.gentoo.org/proj/en/releng/catalyst) for supported arches.
+# The subarch can be any of the supported catalyst subarches (like athlon-xp).
+# Refer to the catalyst reference manual for suppurted subarches.
+# http://www.gentoo.org/proj/en/releng/catalyst/reference.xml
 # example:
 # subarch: athlon-xp
 subarch:
 
-# version stamp is an identifier for the build. can be anything you want it to be, but it
-# is usually a date.
+# The version stamp is an identifier for the build.  It can be anything you wish# it to be, but it is usually a date.
 # example:
-# version_stamp: 2004.2
-version_stamp: 
+# version_stamp: 2005.0
+version_stamp:
 
-# target specifies what type of build Catalyst is to do. check the catalyst reference manual
-# for supported targets.
+# The target specifies what target we want catalyst to do.  For building a CD,
+# we start with livecd-stage1 as our target.
 # example:
-# target: stage2
-target: livecd-stage1
+# target: livecd-stage1
+target:
 
-# rel_type defines what kind of build we are doing. usually, default will suffice.
+# The rel_type defines what kind of build we are doing.  This is merely another
+# identifier, but it useful for allowing multiple concurrent builds.  Usually,
+# default will suffice.
 # example:
 # rel_type: default
 rel_type:
 
-# system profile used to build the media
+# This is the system profile to be used by catalyst to build this target.  It is# specified as a relative path from /usr/portage/profiles.
 # example:
-# profile: default-x86-2004.0
+# profile: default-linux/x86/2005.0
 profile:
 
-# which snapshot to use
+# This specifies which snapshot to use for building this target.
 # example:
-# snapshot: 20040614
+# snapshot: 20050324
 snapshot:
 
-# where the seed stage comes from, path is relative to $clst_sharedir (catalyst.conf)
+# This specifies where the seed stage comes from for this target,  The path is
+# relative to $clst_sharedir/builds.  The rel_type is also used as a path prefix# for the seed.
 # example:
-# default/stage3-x86-2004.1
+# default/stage3-x86-2004.3
 source_subpath:
 
-# use variables that we would like to use when building the LiveCD packages
+# These are the hosts used as distcc slaves when distcc is enabled in your
+# catalyst.conf.  It follows the same syntax as distcc-config --set-hosts and
+# is entirely optional.
+# example:
+# distcc_hosts: 127.0.0.1 192.168.0.1
+distcc_hosts:
+
+# This is an optional directory containing portage configuration files.  It
+# follows the same syntax as /etc/portage and should be consistent across all
+# targets to minimize problems.
+# example:
+# portage_confdir: /etc/portage
+portage_confdir:
+
+# The livecd-stage1 target is where you will build packages for your CD.  These
+# packages can be built with customized USE settings.  The settings here are
+# additive to the default USE configured by the profile.  For building release
+# media, the first thing we do is disable all default USE flags with -* and then
+# begin to set our own.
+# example:
+# livecd/use: -* ipv6 socks5 livecd fbcon ncurses readline ssl
 livecd/use:
-	-X
-	-gtk
-	-svga
-	ipv6
-	socks5
-	livecd
-	fbcon
 
-# list of packages to be merged into the LiveCD fs.
+# This is the set of packages that we will merge into the CD's filesystem.  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.
+# example:
+# livecd/packages: livecd-tools dhcpcd acpid apmd gentoo-sources kudzu-knoppix hotplug coldplug fxload irssi gpm syslog-ng parted links raidtools dosfstools nfs-utils jfsutils xfsprogs e2fsprogs reiserfsprogs ntfsprogs pwgen rp-pppoe screen mirrorselect penggy iputils hwdata-knoppix hwsetup lvm2 evms vim pptpclient mdadm ethtool wireless-tools prism54-firmware wpa_supplicant
 livecd/packages:
-	baselayout
-	livecd-tools
-	kudzu-knoppix
-	module-init-tools
-	hotplug
-	irssi
-	aumix
-	metalog
-	udev
-	parted
-	links
-	strace
-	raidtools
-	nfs-utils
-	jfsutils
-	usbutils
-	xfsprogs
-	xfsdump
-	e2fsprogs
-	reiserfsprogs
-	hdparm
-	dhcpcd
-	pwgen
-	popt
-	dialog
-	rp-pppoe
-	gpm
-	screen
-	mirrorselect
-	penggy
-	iputils
-	hwdata-knoppix
-	hwsetup
-	bootsplash
-	device-mapper
-	lvm2
-	evms
-	vim
-	pwgen
-	pptpclient
-	mdadm
-	ethtool
-	wireless-tools
diff --git a/examples/livecd-stage2_template.spec b/examples/livecd-stage2_template.spec
index 021c6bec..d185d34a 100644
--- a/examples/livecd-stage2_template.spec
+++ b/examples/livecd-stage2_template.spec
@@ -1,226 +1,291 @@
-## livecd-stage2 example specfile
-## used to build a livecd-stage2 iso image
+# livecd-stage2 example specfile
+# used to build a livecd-stage2 iso image
 
-## John Davis <zhen@gentoo.org>
-## Chris Gianelloni <wolf31o2@gentoo.org>
-
-# subarch can be any of the supported Catalyst subarches (like athlon-xp). Refer
-# to the catalyst reference manual:
-# (http://www.gentoo.org/proj/en/releng/catalyst) for supported arches.
+# The subarch can be any of the supported catalyst subarches (like athlon-xp).
+# Refer to the catalyst reference manual for suppurted subarches.
+# http://www.gentoo.org/proj/en/releng/catalyst/reference.xml
 # example:
 # subarch: athlon-xp
 subarch:
 
-# version stamp is an identifier for the build. can be anything you want it
-# to be, but it is usually a date.
+# The version stamp is an identifier for the build.  It can be anything you wish# it to be, but it is usually a date.
 # example:
-# version_stamp: 2004.3
-version_stamp: 
+# version_stamp: 2005.0
+version_stamp:
 
-# target specifies what type of build Catalyst is to do.
-# check the catalyst reference manual for supported targets.
+# The target specifies what target we want catalyst to do.  For building a CD,
+# we continue with livecd-stage2 as the target.
 # example:
 # target: livecd-stage2
-target: livecd-stage2
+target:
 
-# rel_type defines what kind of build we are doing.
-# usually, default will suffice.
+# The rel_type defines what kind of build we are doing.  This is merely another
+# identifier, but it useful for allowing multiple concurrent builds.  Usually,
+# default will suffice.
 # example:
 # rel_type: default
 rel_type:
 
-# system profile used to build the media
+# This is the system profile to be used by catalyst to build this target.  It is# specified as a relative path from /usr/portage/profiles.
 # example:
-# profile: default-linux/x86/2004.3
+# profile: default-linux/x86/2005.0
 profile:
 
-# which snapshot to use
+# This specifies which snapshot to use for building this target.
 # example:
-# snapshot: 20041022
+# snapshot: 20050324
 snapshot:
 
-# where the seed stage comes from, path is relative to $clst_sharedir (catalyst.conf)
+# This specifies where the seed stage comes from for this target,  The path is
+# relative to $clst_sharedir/builds.  The rel_type is also used as a path prefix# for the seed.
 # example:
 # default/stage3-x86-2004.3
 source_subpath:
 
-# which cdfs to use. valid values are:
-# zisofs, squashfs, cloop, gcloop, and noloop
-livecd/cdfstype: squashfs
+# These are the hosts used as distcc slaves when distcc is enabled in your
+# catalyst.conf.  It follows the same syntax as distcc-config --set-hosts and
+# is entirely optional.
+# example:
+# distcc_hosts: 127.0.0.1 192.168.0.1
+distcc_hosts:
 
-# archscript and runscript to use. DO NOT CHANGE THESE UNLESS YOU KNOW WHAT YOU ARE DOING.
-livecd/archscript: /usr/lib/catalyst/livecd/runscript/x86-archscript.sh
-livecd/runscript: /usr/lib/catalyst/livecd/runscript/default-runscript.sh
+# This is an optional directory containing portage configuration files.  It
+# follows the same syntax as /etc/portage and should be consistent across all
+# targets to minimize problems.
+# example:
+# portage_confdir: /etc/portage
+portage_confdir:
+
+# The cdfstype 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 options 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, withuot using a loopback.
+# gcloop - This is deprecated and only provided for backwards compatibility.
+# example:
+# livecd/cdfstype: squashfs
+livecd/cdfstype:
 
-# bootloader for the LiveCD - DO NOT CHANGE UNLESS YOU KNOW WHAT YOU ARE DOING.
-livecd/cdtar: /usr/lib/catalyst/livecd/cdtar/isolinux-2.08-memtest86-cdtar.tar.bz2
+# The archscript is for architecture-dependent configuration.  Not all Gentoo
+# architectures use their own archscript.  Some share with other architectures
+# that are similar.
+# example:
+# livecd/archscript: /usr/lib/catalyst/livecd/runscript/x86-archscript.sh
+livecd/archscript:
 
-# (optional) create a iso and place it in the location specified
-# livecd/iso: /tmp/gentoo.iso
+# The runscript is the "brains" of the livecd-stage2 target and is designed to
+# be architecturer agnostic.  It is best not to change this.
+# example:
+# livecd/runscript: /usr/lib/catalyst/livecd/runscript/default-runscript.sh
+livecd/runscript:
 
-# (optional) run this script in the LiveCD chroot to tweak the LiveCD fs
-# livecd/fsscript: /tmp/myscript.sh
+# 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:
+# livecd/cdtar: /usr/lib/catalyst/livecd/cdtar/isolinux-2.13-memtest86+-cdtar.tar.bz2
+livecd/cdtar:
 
-# (optional) files to be added to the final livecd product. note that they
-# *are not* in the loopback fs itself, but in /mnt/cdrom when the cd is booted.
-# the layout is in the overlay mirrors how it will be on the LiveCD.
-# livecd/overlay: /tmp/files_for_livecd
+# This is the full path and filename to the ISO image that the livecd-stage2
+# target will create.
+# example:
+# livecd/iso: /tmp/installcd-x86-minimal.iso
+livecd/iso:
+
+# A fsscript is simply a shell script that is copied into the chroot of the CD
+# 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 livecd-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.  The script is copied
+# into the chroot by catalyst automatically.
+# example:
+# livecd/fsscript:
+livecd/fsscript:
 
-# (optional) "global" arguments that are to be passed to genkernel
-# livecd/gk_mainargs: --makeopts=-j3
+# The splash type determines the automatic arguments for the bootloader on
+# supported architectures.  The possible options are gensplash and bootsplash.
+# example:
+# livecd/splash_type: gensplash
+livecd/splash_type:
 
-# (optional) tweaks things such as the MOTD for release LiveCDs
-# livecd/type: gentoo-release-universal
+# This is where you set the splash theme.  This theme must be present in either
+# /etc/splash or /etc/bootsplash, depending on your livecd/splash_type, before
+# the kernel has completed building during the livecd-stage2 target.
+# example:
+# livecd/splash_theme: livecd-2005.0
+livecd/splash_theme:
 
-# (optional) the standard Gentoo release MOTD is included with Catalyst
-# livecd/motd: /usr/lib/catalyst/livecd/files/motd.txt
+# This is a set of arguments that will be passed to genkernel for all kernels
+# defined in this target.  It is useful for passing arguments to genkernel that
+# are not otherwise available via the livecd-stage2 spec file.
+# example:
+# livecd/gk_mainargs: --lvm2 --dmraid
+livecd/gk_mainargs:
+
+# 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.
+# example:
+# livecd/type: gentoo-release-minimal
+livecd/type:
+
+# This is for the CD's message of the day.  It is not required for official
+# release media, as catalyst builds a default motd when the livecd/type is set
+# to one of the gentoo-* options.  This setting overrides the default motd even
+# on official media.  Since we do not use this for the official releases, it is
+# left blank below.
+# example:
+# livecd/motd:
+livecd/motd:
 
-# (optional) list of modules that you want to blacklist for hotplug
+# This is for blacklisting modules from being hotplugged that are known to cause
+# problems.  Putting a module name here will keep it from being auto-loaded,
+# even if ti is detected by hotplug.
+# example:
 # livecd/modblacklist: 8139cp
+livecd/modblacklist:
 
-# (optional) splash type you wish to use on your LiveCD,  this can be either
-# gensplash or bootsplash
-# livecd/splash_type: gensplash
-
-# (optional) splash theme to use - must be present in /etc/splash or
-# /etc/bootsplash of the LiveCD before the initrd is completed.
-# livecd/splash_theme: livecd-2004.3
-
-# (optional) list of services to add to the specified runlevel
-# livecd/rcadd: mkxf86config:default alsasound:default
+# This is for adding init scripts to runlevels.  The syntax for the init script
+# is the script name, followed by a colon, 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.  Since we do not use this, it is left blank below.
+# example:
+# livecd/rcadd:
+livecd/rcadd:
+
+# 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 livcd/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, so it is left blank.
+# example:
+# livecd/rcdel:
+livecd/rcdel:
 
-# (optional) list of services to delete from the specified runlevel
-# livecd/rcdel: net.eth0:boot
+# This overlay is dropped onto the CD filesystem and is outside any loop which
+# has been configured.  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.
+# example:
+# livecd/overlay: /tmp/overlay-minimal
+livecd/overlay:
 
-# (optional) xinitrc to use on the livecd
-# livecd/xinitrc: /tmp/livecd_xinitrc
 
-# (optional) directory that is to be overlayed on the livecd rootfs
-# (the booted fs)
-# livecd/root_overlay: /tmp/livecd-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 CD filesystem.  Files added here are available when
+# docache is used.  We do not use this on the official media, so we will leave
+# it blank below.
+# example:
+# livecd/root_overlay:
+livecd/root_overlay:
 
-# (optional) if you want your livecd to use udev instead of devfs,
-# uncomment this line
+# This is here to enable udev support in both catalyst and genkernel.  This
+# option requires genkernel >= 3.1.0, and is not needed with genkernel >=3.2.0,
+# as udev is the default.
+# example:
 # livecd/devmanager: udev
+livecd/devmanager:
+
+# This is used by catalyst to copy the specified file to /etc/X11/xinit/xinitrc
+# and is used by the livecd/type gentoo-gamecd and generic-livecd.  While the
+# file will still be copied for any livecd/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, so it is left blank.
+# example:
+# livecd/xinitrc:
+livecd/xinitrc:
 
-# let catalyst know the names of the kernels that you want it to build
-boot/kernel: gentoo smp
+# 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, and is therefore blank.
+# example:
+# gamecd/conf:
+gamecd/conf:
 
-# for the first kernel (gentoo), let catalyst know what sources to use and
-# what kernel config to use
-boot/kernel/gentoo/sources: sys-kernel/gentoo-sources
-boot/kernel/gentoo/config:
+# 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:
+# boot/kernel: gentoo
+boot/kernel:
 
-# (optional) per-kernel arguments for genkernel
-# boot/kernel/gentoo/gk_kernargs: --makeopts=-j2
+# This option tells catalyst which kernel sources to merge for this kernel
+# label.  This can use normal portage atoms to specify a specific version.
+# example:
+# boot/kernel/gentoo/sources: gentoo-sources
+boot/kernel/gentoo/sources:
 
-# same as the gentoo kernel above, just different data
-boot/kernel/smp/sources: sys-kernel/gentoo-dev-sources
-boot/kernel/smp/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.
+# example:
+# boot/kernel/gentoo/config: /tmp/2.6.11-smp.config
+boot/kernel/gentoo/config:
 
-# (optional) per-kernel arguments for genkernel
-# boot/kernel/smp/gk_kernargs: --makeopts=-j1
+# 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.  Since we do not use this
+# on the official release media, it is left blank, but it follows the same
+# syntax as livecd/gk_mainargs.
+# example:
+# boot/kernel/gentoo/gk_kernargs:
+boot/kernel/gentoo/gk_kernargs:
 
-# this next line sets any USE settings you want exported to the environment for
-# your kernel build *and* during the build of any kernel-dependent packages
-boot/kernel/gentoo/use: pcmcia usb
-boot/kernel/smp/use: pcmcia usb
+# This option sets the USE flags used to build the kernel and also any packages
+# which are defined under this kernel label.  These USE flags are additive from
+# the default USE for the specified profile.
+# example:
+# boot/kernel/gentoo/use: pcmcia usb -X
+boot/kernel/gentoo/use:
+
+# 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, so it
+# is left blank.
+# example:
+# boot/kernel/gentoo/extraversion:
+boot/kernel/gentoo/extraversion:
 
-# use this next option to add an extension to the name of your kernel. This
-# allows you to have 2 identical kernels on the livecd built with different
-# options, and each with their own modules dir in /lib/modules (otherwise
-# the second kernel would overwrite the first modules directory.
-boot/kernel/gentoo/extraversion: gentoo
-boot/kernel/smp/extraversion: smp
+# This option is a list of packages which genkernel will emerge after the kernel
+# has been configured, but before it is compiled.  This option is used for the
+# exclusive purpose of including our gensplash theme into the kernel bzImage.
+# example:
+# boot/kernel/gentoo/postconf: splashutils splash-themes-livecd
+boot/kernel/gentoo/postconf:
 
-# this next line is for merging kernel-dependent packages after your kernel
-# is built. This is where you merge third-party ebuilds that contain kernel
-# modules.
+# This option is for merging kernel-dependent packages and external modules that
+# are configured against this kernel label.
+# example:
+# boot/kernel/gentoo/packages: pcmcia-cs speedtouch slmodem globespan-adsl hostap-driver hostap-utils ipw2100 ipw2200 fritzcapi fcdsl cryptsetup
 boot/kernel/gentoo/packages:
-	pcmcia-cs
-	speedtouch
-	slmodem
-	globespan-adsl
-	hostap-driver
-	hostap-utils
-	ipw2100
-	
-boot/kernel/smp/packages:
-	pcmcia-cs
-	speedtouch
-	slmodem
-	globespan-adsl
-	hostap-driver
-	hostap-utils
-	ipw2100
-
-# remove gcc from the list if you want distcc
+
+# This is a list of packages that will be unmerged after all the kernels have
+# been built.  There are no checks on these packages, so be careful what you
+# add here.  They can potentially break your CD.
+# example:
+# livecd/unmerge: acl attr autoconf automake bin86 binutils libtool m4 bison ld.so make perl patch linux-headers man-pages sash bison flex gettext texinfo ccache distcc addpatches man groff lib-compat miscfiles rsync sysklogd bc lcms libmng genkernel diffutils libperl gnuconfig gcc-config gcc bin86 cpio cronbase ed expat grub lilo help2man libtool gentoo-sources
 livecd/unmerge:
-	autoconf
-	automake
-	gcc
-	bin86
-	binutils
-	libtool
-	m4
-	bison
-	ld.so
-	make
-	perl
-	patch
-	linux-headers
-	man-pages
-	sash
-	bison
-	flex
-	gettext
-	texinfo
-	ccache
-	addpatches
-	man
-	groff
-	lib-compat
-	python
-	miscfiles
 
+# This option is used to empty the directories listed.  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.
+# example:
+# livecd/empty: /var/tmp /var/cache /var/db /var/empty /var/lock /var/log /var/run /var/spool /var/state /tmp /usr/portage /usr/share/man /usr/share/info /usr/share/unimaps /usr/include /usr/share/zoneinfo /usr/share/dict /usr/share/doc /usr/share/ss /usr/share/state /usr/share/texinfo /usr/lib/python2.2 /usr/lib/portage /usr/share/gettext /usr/share/i18n /usr/share/rfc /usr/lib/X11/config /usr/lib/X11/etc /usr/lib/X11/doc /usr/src /usr/share/doc /usr/share/man /root/.ccache /etc/cron.daily /etc/cron.hourly /etc/cron.monthly /etc/cron.weekly /etc/logrotate.d /etc/rsync /usr/lib/awk /usr/lib/ccache /usr/lib/gcc-config /usr/lib/nfs /usr/local /usr/diet/include /usr/diet/man /usr/share/consolefonts/partialfonts /usr/share/consoletrans /usr/share/emacs /usr/share/gcc-data /usr/share/genkernel /etc/bootsplash/gentoo /etc/bootsplash/gentoo-highquality /etc/splash/gentoo /etc/splash/emergence /usr/share/gnuconfig /usr/share/lcms /usr/share/locale /etc/skel
 livecd/empty:
-	/var/tmp
-	/var/cache
-	/var/db
-	/var/empty
-	/var/cache
-	/var/lock
-	/tmp
-	/usr/portage
-	/usr/share/man
-	/usr/share/info
-	/usr/share/unimaps
-	/usr/include
-	/usr/share/zoneinfo
-	/usr/share/dict
-	/usr/share/doc
-	/usr/share/ss
-	/usr/share/state
-	/usr/share/texinfo
-	/usr/lib/python2.2
-	/usr/lib/portage
-	/usr/share/gettext
-	/usr/share/i18n
-	/usr/share/rfc
-	/usr/X11R6/man
-	/usr/X11R6/include
-	/usr/X11R6/lib/X11/config
-	/usr/X11R6/lib/X11/etc
-	/usr/X11R6/lib/X11/doc
-	/usr/src
-	/usr/share/doc
-	/usr/share/man
-	/root/.ccache
-livecd/rm:
-	/lib/*.a
-	/usr/lib/*.a
-	/usr/lib/gcc-lib/*/*/libgcj*
-	/usr/X11R6/lib/*.a
-	/var/log/emerge.log
-	/var/log/genkernel.log
 
+# This option tells catalyst to clean specific files from the filesystem and is
+# very usefu in cleaning up stray files in /etc left over after livecd/unmerge.
+# example:
+# livecd/rm: /lib/*.a /usr/lib/*.a /usr/lib/gcc-lib/*/*/libgcj* /etc/dispatch-conf.conf /etc/etc-update.conf /etc/*- /etc/issue* /etc/make.conf /etc/man.conf /etc/*.old /root/.viminfo /usr/sbin/bootsplash* /usr/sbin/fb* /usr/sbin/fsck.cramfs /usr/sbin/fsck.minix /usr/sbin/mkfs.minix /usr/sbin/mkfs.bfs /usr/sbin/mkfs.cramfs /lib/security/pam_access.so /lib/security/pam_chroot.so /lib/security/pam_debug.so /lib/security/pam_ftp.so /lib/security/pam_issue.so /lib/security/pam_mail.so /lib/security/pam_motd.so /lib/security/pam_mkhomedir.so /lib/security/pam_postgresok.so /lib/security/pam_rhosts_auth.so /lib/security/pam_userdb.so /usr/share/consolefonts/1* /usr/share/consolefonts/7* /usr/share/consolefonts/8* /usr/share/consolefonts/9* /usr/share/consolefonts/A* /usr/share/consolefonts/C* /usr/share/consolefonts/E* /usr/share/consolefonts/G* /usr/share/consolefonts/L* /usr/share/consolefonts/M* /usr/share/consolefonts/R* /usr/share/consolefonts/a* /usr/share/consolefonts/c* /usr/share/consolefonts/dr* /usr/share/consolefonts/g* /usr/share/consolefonts/i* /usr/share/consolefonts/k* /usr/share/consolefonts/l* /usr/share/consolefonts/r* /usr/share/consolefonts/s* /usr/share/consolefonts/t* /usr/share/consolefonts/v* /etc/splash/livecd-2005.0/16* /etc/splash/livecd-2005.0/12* /etc/splash/livecd-2005.0/6* /etc/splash/livecd-2005.0/8* /etc/splash/livecd-2005.0/images/silent-16* /etc/splash/livecd-2005.0/images/silent-12* /etc/splash/livecd-2005.0/images/silent-6* /etc/splash/livecd-2005.0/images/silent-8* /etc/splash/livecd-2005.0/images/verbose-16* /etc/splash/livecd-2005.0/images/verbose-12* /etc/splash/livecd-2005.0/images/verbose-6* /etc/splash/livecd-2005.0/images/verbose-8* /etc/make.conf.example /etc/make.globals /etc/resolv.conf
+livecd/rm:
diff --git a/examples/netboot_template.spec b/examples/netboot_template.spec
index 9d929407..41d3335d 100644
--- a/examples/netboot_template.spec
+++ b/examples/netboot_template.spec
@@ -1,79 +1,126 @@
-## generic netboot image specfile
-## used to build a network bootable image
+# generic netboot image specfile
+# used to build a network bootable image
 
-## John Davis <zhen@gentoo.org>
-
-# subarch can be any of the supported Catalyst subarches (like athlon-xp). Refer
-# to the catalyst reference manual (http://www.gentoo.org/proj/en/releng/catalyst) for supported arches.
+# The subarch can be any of the supported catalyst subarches (like athlon-xp).
+# Refer to the catalyst reference manual for suppurted subarches.
+# http://www.gentoo.org/proj/en/releng/catalyst/reference.xml
 # example:
 # subarch: athlon-xp
 subarch:
 
-# version stamp is an identifier for the build. can be anything you want it to be, but it
-# is usually a date.
+# The version stamp is an identifier for the build.  It can be anything you wish# it to be, but it is usually a date.
 # example:
-# version_stamp: 2004.2
-version_stamp: 
+# version_stamp: 2005.0
+version_stamp:
 
-# target specifies what type of build Catalyst is to do. check the catalyst reference manual
-# for supported targets.
+# The target specifies what target we want catalyst to do.  For building a
+# netboot image, we use the netboot target.
 # example:
-# target: stage2
+# target: netboot
 target:
 
-# rel_type defines what kind of build we are doing. usually, default will suffice.
+# The rel_type defines what kind of build we are doing.  This is merely another
+# identifier, but it useful for allowing multiple concurrent builds.  Usually,
+# default will suffice.
 # example:
 # rel_type: default
 rel_type:
 
-# system profile used to build the media
+# This is the system profile to be used by catalyst to build this target.  It is# specified as a relative path from /usr/portage/profiles.
 # example:
-# profile: default-x86-2004.0
+# profile: default-linux/x86/2005.0
 profile:
 
-# which snapshot to use
+# This specifies which snapshot to use for building this target.
 # example:
-# snapshot: 20040614
+# snapshot: 20050324
 snapshot:
 
-# where the seed stage comes from, path is relative to $clst_sharedir (catalyst.conf)
+# This specifies where the seed stage comes from for this target,  The path is
+# relative to $clst_sharedir/builds.  The rel_type is also used as a path prefix# for the seed.
 # example:
-# default/stage3-x86-2004.1
+# default/stage3-x86-2004.3
 source_subpath:
 
-# kernel sources to use (e.g gentoo-dev-sources, gentoo-sources, vanilla-sources)
+# These are the hosts used as distcc slaves when distcc is enabled in your
+# catalyst.conf.  It follows the same syntax as distcc-config --set-hosts and
+# is entirely optional.
+# example:
+# distcc_hosts: 127.0.0.1 192.168.0.1
+distcc_hosts:
+
+# This is an optional directory containing portage configuration files.  It
+# follows the same syntax as /etc/portage and should be consistent across all
+# targets to minimize problems.
+# example:
+# portage_confdir: /etc/portage
+portage_confdir:
+
+# This option tells catalyst which kernel sources to merge for building this
+# image.  This can use normal portage atoms to specify a specific version.
+# example:
+# netboot/kernel/sources: gentoo-sources
 netboot/kernel/sources:
 
-# kernel config (.config) used to build the kernel
+# This option is the full path and filename to a kernel .config file that is
+# used by genkernel to compile the kernel for this image.
+# example:
+# netboot/kernel/config: /tmp/2.6.11-netboot.config
 netboot/kernel/config:
 
-# (optional) USE flags to set for the kernel
+# This option sets the USE flags used to build the kernel.  These USE flags are
+# additive from the default USE for the specified profile.
+# example:
+# netboot/kernel/use: ultra1
 netboot/kernel/use:
 
-# (optional) USE flags to set for the packages that are to be included in the netboot image
+# This option sets the USE flags with which the optional packages below are
+# built.  Like the kernel USE, they are additive.
+# example:
+# netboot/use:
 netboot/use:
 
-# config used to build busybox
+# 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
+# netboot/busybox_config: /tmp/busybox.config
 netboot/busybox_config:
 
-# base tarball to use for the netboot image
-netboot/base_tarball: /usr/lib/catalyst/netboot/netboot-base.tar.bz2
+# This is the full path and filename to the tarball to use as the base for the
+# netboot image.
+# example:
+# netboot/base_tarball: /usr/lib/catalyst/netboot/netboot-base.tar.bz2
+netboot/base_tarball:
 
-# packages that you want to have available in the netboot image
-netboot/packages:
-	raidtools
-	xfsprogs
-	e2fsprogs
-	reiserfsprogs
+# These are the packages that will be built for your netboot image using the USE
+# flags set in netboot/use.  These package names are also labels used later when
+# determining what files to copy into your netboot image.
+# example:
+# netboot/packages: raidtools xfsprogs e2fsprogs reiserfsprogs
 
-# here you can set which files from the above packages you want copied over to the image
-netboot/packages/raidtools/files: /sbin/raidstart /sbin/mkraid /sbin/detect_multipath /sbin/raidreconf /sbin/raidstop /sbin/raidhotadd /sbin/raidhotremove /sbin/raidsetfaulty /sbin/raid0run
+# This is where you tell catalyst which files from each package to copy into the
+# netboot image.
+# example:
+# netboot/packages/raidtools/files: /sbin/raidstart /sbin/mkraid /sbin/detect_multipath /sbin/raidreconf /sbin/raidstop /sbin/raidhotadd /sbin/raidhotremove /sbin/raidsetfaulty /sbin/raid0run
+netboot/packages/raidtools/files:
 
-netboot/packages/xfsprogs/files: /sbin/mkfs.xfs /sbin/xfs_repair /bin/xfs_check
+# Here is the same thing for xfsprogs.
+# example:
+# netboot/packages/xfsprogs/files: /sbin/mkfs.xfs /sbin/xfs_repair /bin/xfs_check
+netboot/packages/xfsprogs/files:
 
-netboot/packages/e2fsprogs/files: /sbin/mke2fs
+# Here is the same thing for e2fsprogs.
+# example:
+# netboot/packages/e2fsprogs/files: /sbin/mke2fs
+netboot/packages/e2fsprogs/files:
 
-netboot/packages/reiserfsprogs/files: /sbin/mkreiserfs
+# Here is the same thing for reiserfsprogs.
+# example:
+# netboot/packages/reiserfsprogs/files: /sbin/mkreiserfs
+netboot/packages/reiserfsprogs/files:
 
-# any extra files that need copied over to the image to make it work
-netboot/extra_files: /lib/libresolv.so.2 /lib/libnss_compat.so.2 /lib/libnss_dns.so.2 /lib/libnss_files.so.2 /sbin/consoletype
+# 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:
+# netboot/extra_files: /lib/libresolv.so.2 /lib/libnss_compat.so.2 /lib/libnss_dns.so.2 /lib/libnss_files.so.2 /sbin/consoletype
+netboot/extra_files:
diff --git a/examples/snapshot_template.spec b/examples/snapshot_template.spec
index 31e3abc5..30acb6e9 100644
--- a/examples/snapshot_template.spec
+++ b/examples/snapshot_template.spec
@@ -1,17 +1,17 @@
-## portage snapshot example specfile
+# portage snapshot example specfile
 
-## John Davis <zhen@gentoo.org>
-
-# lets catalyst know what it is building
-target: snapshot
+# Thsi is the target for creating a snapshot.
+# example:
+# target: snapshot
+target:
 
-# marks the tarball and makes it unique. Usually, this is a date.
+# The version stamp is an identifier for the build.  It can be anything you wish# it to be, but it is usually a date.
 # example:
-# version_stamp: 20040611
+# version_stamp: 2005.0
 version_stamp:
 
-# portdir_overlay (optional) specifies the path to a portage overlay for inclusion
-# in the portage snapshot
+# This option specifies the location to a portage overlay that you would like to
+# have included in this snapshot.
 # example:
 # portdir_overlay: /usr/local/portdir_overlay
 portdir_overlay: