diff options
author | Sebastian Pipping <sebastian@pipping.org> | 2011-06-24 18:58:46 +0200 |
---|---|---|
committer | Sebastian Pipping <sebastian@pipping.org> | 2011-06-24 19:10:42 +0200 |
commit | fa940f755fbe539ffdeed748df7f1e31d9427f72 (patch) | |
tree | e65b4b212d120227f8f968c59c7e3dd6eb1aab0b /doc | |
parent | There is no dict conf_values.settings, replace by plain conf_values (diff) | |
download | catalyst-fa940f755fbe539ffdeed748df7f1e31d9427f72.tar.gz catalyst-fa940f755fbe539ffdeed748df7f1e31d9427f72.tar.bz2 catalyst-fa940f755fbe539ffdeed748df7f1e31d9427f72.zip |
Migrate man page to Asciidoc, generate list of subarches, add Makefile including "dist" target
Diffstat (limited to 'doc')
-rw-r--r-- | doc/asciidoc.conf | 3 | ||||
-rw-r--r-- | doc/catalyst.1.txt | 139 | ||||
-rwxr-xr-x | doc/make_subarch_table_guidexml.py | 112 |
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) |