Migrate man page to Asciidoc, generate list of subarches, add Makefile including "dist" target

3 files changed, 254 insertions, 0 deletions

diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf
new file mode 100644
index 00000000..b116d54a
--- /dev/null
+++ b/doc/asciidoc.conf
@@ -0,0 +1,3 @@
+#
+# asciidoc.conf for catalyst's man page
+#
diff --git a/doc/catalyst.1.txt b/doc/catalyst.1.txt
new file mode 100644
index 00000000..67f4df6c
--- /dev/null
+++ b/doc/catalyst.1.txt
@@ -0,0 +1,139 @@
+CATALYST(1)
+===========
+:man source:   catalyst {catalystversion}
+:man manual:   catalyst {catalystversion}
+
+
+NAME
+----
+catalyst - The Gentoo Linux Release Engineering meta-tool
+
+
+SYNOPSIS
+--------
+*catalyst* ['OPTIONS'] [*-f* 'FILE' | *-C* 'KEYS' | *-s* 'DATE'] ...
+
+
+DESCRIPTION
+-----------
+*catalyst* is the tool that the Gentoo Release Engineering team
+utilizes to build all Gentoo Linux releases. It is capable of building
+installation stages, bootable LiveCDs, netboot images, and Gentoo Reference
+Platform (GRP) sets. *catalyst* is also capable of providing a simple
+tinderbox environment for ebuild/package testing.
+
+For more information, please visit the *catalyst* project page
+on the web at 'http://www.gentoo.org/proj/en/releng/catalyst'.
+
+
+OPTIONS
+-------
+*--clear-autoresume*::
+*-a*::
+This option is to be used to clear any autoresume points that have been saved
+for this target. It is used in conjunction with *-f*, *-C*, or both.
+
+*--cli*|*-C* 'KEY'='VALUE' ..::
+This option is to be used in place of a specfile. All options are passed
+to *catalyst* on the commandline. Please note that this option must
+be the last option passed to *catalyst* for everything to work correctly.
+
+*--config*|*-c* 'FILE'::
+Tell *catalyst* to use a user-defined configuration file. A sample
+configuration file is installed at '/etc/catalyst/catalyst.conf'.
+
+*--debug*::
+*-d*::
+Enable debugging mode
+
+*--fetchonly*::
+*-F*::
+This tells *catalyst* to only fetch distfiles for the given packages without
+performing any building.
+
+*--file*|*-f* 'FILE'::
+Tell *catalyst* to use the user supplied specfile.
+
+*--help*::
+*-h*::
+Print the help message and exit
+
+*--purge*::
+*-p*::
+Tell *catalyst* to clear all temporary directories, package caches, and
+autoresume flags for the given target.
+
+*--snapshot*|*-s* 'DATE'::
+Create a Portage snapshot using the specified identifier stamp.
+
+*--verbose*::
+*-v*::
+Enable verbose mode.
+
+*--version*::
+*-V*::
+Print the version information and exit
+
+
+EXAMPLES
+--------
+Using the commandline option (*-C*, *--cli*) to build a Portage snapshot:
+---------------------------------------------------
+# catalyst -C target=snapshot version_stamp=my_date
+---------------------------------------------------
+
+Using the specfile option (*-f*, *--file*) to build a stage target:
+---------------------------------------------------
+# catalyst -f stage1-specfile.spec
+---------------------------------------------------
+
+Using the snapshot option (*-s*, *--snapshot*) to package a Portage snapshot
+using the datestamp 20051208:
+---------------------------------------------------
+# catalyst -s 20051208
+---------------------------------------------------
+
+
+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
+--------
+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
+stager projects, both of which were used to create pre-1.4 Gentoo releases.
+
+*catalyst* was originally conceived and coded by both Daniel Robbins and
+John Davis. It is currently maintained by Chris Gianelloni and Eric Edgar and
+has been mostly re-written.
+
+
+AUTHORS
+-------
+- John Davis <zhen@gentoo.org>
+- Chris Gianelloni <wolf31o2@gentoo.org>
+- Raúl Porcel <armin76@gentoo.org>
+- Sebastian Pipping <sping@gentoo.org>
diff --git a/doc/make_subarch_table_guidexml.py b/doc/make_subarch_table_guidexml.py
new file mode 100755
index 00000000..22e6c6dd
--- /dev/null
+++ b/doc/make_subarch_table_guidexml.py
@@ -0,0 +1,112 @@
+#! /usr/bin/env python
+# Copyright (C) 2011 Sebastian Pipping <sebastian@pipping.org>
+# Licensed under GPL v2 or later
+
+
+import os
+import re
+import textwrap
+
+
+_pattern_arch_generic = re.compile('^class arch_([a-z0-9_.-]+)\\(generic_([a-z0-9_.-]+)\\):')
+_pattern_arch_arch = re.compile('^class arch_([a-z0-9_.-]+)\\(arch_([a-z0-9_.-]+)\\):')
+_pattern_title = re.compile('"([a-z0-9_.-]+)"[ \\t]*:[ \\t]*arch_([a-z0-9_.-]+),?')
+
+_pattern_arch_genericliases = {
+	'armeb':'arm',
+	'sheb':'sh',
+	'mipsel':'mips',
+}
+
+
+def handle_line(line, subarch_title_to_subarch_id, subarch_id_to_pattern_arch_genericrch_id):
+	x = _pattern_arch_generic.search(line)
+	if x is not None:
+		subarch = x.group(1)
+		arch = x.group(2)
+
+		# Apply alias grouping
+		arch = _pattern_arch_genericliases.get(arch, arch)
+
+		assert(subarch not in subarch_id_to_pattern_arch_genericrch_id)
+		subarch_id_to_pattern_arch_genericrch_id[subarch] = arch
+
+		return
+
+	x = _pattern_arch_arch.search(line)
+	if x is not None:
+		child_subarch = x.group(1)
+		parent_subarch = x.group(2)
+
+		assert(child_subarch not in subarch_id_to_pattern_arch_genericrch_id)
+		subarch_id_to_pattern_arch_genericrch_id[child_subarch] = subarch_id_to_pattern_arch_genericrch_id[parent_subarch]
+
+		return
+
+	for x in re.finditer(_pattern_title, line):
+		subarch_title = x.group(1)
+		subarch_id = x.group(2)
+
+		assert(subarch_title not in subarch_title_to_subarch_id)
+		subarch_title_to_subarch_id[subarch_title] = subarch_id
+
+
+def handle_file(fn, subarch_title_to_subarch_id, subarch_id_to_pattern_arch_genericrch_id):
+	f = open(fn, 'r')
+	for l in f:
+		line = l.rstrip()
+		handle_line(line, subarch_title_to_subarch_id, subarch_id_to_pattern_arch_genericrch_id)
+	f.close()
+
+
+def dump(subarch_title_to_subarch_id, subarch_id_to_pattern_arch_genericrch_id):
+	arch_id_to_subarch_titles = dict()
+	for subarch_title, subarch_id in subarch_title_to_subarch_id.items():
+		arch_id = subarch_id_to_pattern_arch_genericrch_id.get(subarch_id, subarch_id)
+
+		if arch_id not in arch_id_to_subarch_titles:
+			arch_id_to_subarch_titles[arch_id] = set()
+		arch_id_to_subarch_titles[arch_id].add(subarch_title)
+
+	# GuideXML version
+	f = open('doc/subarches.generated.xml', 'w')
+	f.write("""
+<table>
+<tr>
+<th>Architecture</th>
+<th>Sub-architectures</th>
+</tr>
+""")
+	for arch_id, subarch_titles in sorted(arch_id_to_subarch_titles.items()):
+		f.write("""<tr>
+<ti><c>%s</c></ti>
+<ti><c>%s</c></ti>
+</tr>
+""" % (arch_id, '\n'.join(textwrap.wrap(' '.join(sorted(subarch_titles)), 60))))
+
+	f.write("""</table>
+""")
+	f.close()
+
+	# Asciidoc
+	f = open('doc/subarches.generated.txt', 'w')
+	for arch_id, subarch_titles in sorted(arch_id_to_subarch_titles.items()):
+		f.write('*%s*::\n' % arch_id)
+		f.write('    %s\n' % ', '.join(sorted(subarch_titles)))
+		f.write('\n')
+	f.close()
+
+
+if __name__ == '__main__':
+	subarch_title_to_subarch_id = dict()
+	subarch_id_to_pattern_arch_genericrch_id = dict()
+
+	for (dirpath, dirnames, filenames) in os.walk('arch'):
+		for _fn in filenames:
+			if not _fn.endswith('.py'):
+				continue
+
+			fn = os.path.join(dirpath, _fn)
+			handle_file(fn, subarch_title_to_subarch_id, subarch_id_to_pattern_arch_genericrch_id)
+
+	dump(subarch_title_to_subarch_id, subarch_id_to_pattern_arch_genericrch_id)