From fa940f755fbe539ffdeed748df7f1e31d9427f72 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Fri, 24 Jun 2011 18:58:46 +0200 Subject: [PATCH] Migrate man page to Asciidoc, generate list of subarches, add Makefile including "dist" target --- .gitignore | 3 + ChangeLog | 4 + Makefile | 35 ++++++++ doc/asciidoc.conf | 3 + doc/catalyst.1.txt | 139 +++++++++++++++++++++++++++++ doc/make_subarch_table_guidexml.py | 112 +++++++++++++++++++++++ files/catalyst.1 | 124 ------------------------- 7 files changed, 296 insertions(+), 124 deletions(-) create mode 100644 Makefile create mode 100644 doc/asciidoc.conf create mode 100644 doc/catalyst.1.txt create mode 100755 doc/make_subarch_table_guidexml.py delete mode 100644 files/catalyst.1 diff --git a/.gitignore b/.gitignore index 539da741..9de57880 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,4 @@ *.py[co] +/files/catalyst.1 +/doc/subarches.generated.txt +/doc/subarches.generated.xml diff --git a/ChangeLog b/ChangeLog index 68ef5bef..c07d25c1 100644 --- a/ChangeLog +++ b/ChangeLog @@ -3,6 +3,10 @@ # Distributed under the GPL v2 # $Id$ + 24 Jun 2011; Sebastian Pipping Makefile, + doc/asciidoc.conf, doc/catalyst.1.txt, doc/make_subarch_table_guidexml.py: + Include list of supported subarches in man page. + 14 Apr 2011; Raúl Porcel catalyst: This is catalyst 2.0.6.916 diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..bcc40c7c --- /dev/null +++ b/Makefile @@ -0,0 +1,35 @@ +# Copyright (C) 2011 Sebastian Pipping +# Licensed under GPL v2 or later + +PACKAGE_VERSION = `fgrep '__version__=' catalyst | sed 's|^__version__="\(.*\)"$$|\1|'` +CLEAN_FILES = files/catalyst.1 doc/subarches.generated.txt +EXTRA_DIST = files/catalyst.1 + +distdir = catalyst-$(PACKAGE_VERSION) + + +all: files/catalyst.1 + +files/catalyst.1: doc/catalyst.1.txt doc/subarches.generated.txt doc/asciidoc.conf Makefile catalyst + a2x --conf-file=doc/asciidoc.conf --attribute="catalystversion=$(PACKAGE_VERSION)" \ + --format=manpage -D files "$<" + +doc/subarches.generated.txt: + ./doc/make_subarch_table_guidexml.py + +clean: + rm -f $(CLEAN_FILES) + find -name '*.pyo' -delete + +check-git-repository: + git diff --quiet || { echo 'STOP, you have uncommitted changes in the working directory' ; false ; } + git diff --cached --quiet || { echo 'STOP, you have uncommitted changes in the index' ; false ; } + +dist: check-git-repository $(EXTRA_DIST) + rm -Rf "$(distdir)" "$(distdir)".tar "$(distdir)".tar.bz2 + mkdir "$(distdir)" + git ls-files -z | xargs -0 cp --no-dereference --parents --target-directory="$(distdir)" \ + $(EXTRA_DIST) + tar cf "$(distdir)".tar "$(distdir)" + bzip2 -9v "$(distdir)".tar + rm -Rf "$(distdir)" 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 +- Chris Gianelloni +- Raúl Porcel +- Sebastian Pipping 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 +# 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(""" + + + + + +""") + for arch_id, subarch_titles in sorted(arch_id_to_subarch_titles.items()): + f.write(""" +%s +%s + +""" % (arch_id, '\n'.join(textwrap.wrap(' '.join(sorted(subarch_titles)), 60)))) + + f.write("""
ArchitectureSub-architectures
+""") + 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) diff --git a/files/catalyst.1 b/files/catalyst.1 deleted file mode 100644 index 4154760e..00000000 --- a/files/catalyst.1 +++ /dev/null @@ -1,124 +0,0 @@ -.TH "CATALYST" "1" "December 8, 2005" "Catalyst 2.0" "Catalyst" - -.SH NAME -catalyst \- The Gentoo Linux Release Engineering meta-tool - -.SH SYNOPSIS -.TP - -.BR catalyst -[\fIoptions\fR] [\fI\-f file\fR | \fI\-C keys\fR | \fI\-s version_stamp\fR] ... -.TP - -.BR catalyst -\fI\-\-help \-h\fR -.TP - -.BR catalyst -\fI\-\-version \-V\fR - -.SH DESCRIPTION -\fBcatalyst\fR 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. \fBcatalyst\fR is also capable of providing a simple -tinderbox environment for ebuild/package testing. - -For more information, please visit the \fBcatalyst\fR project page -on the web at . - -.SH OPTIONS -.TP - -.BR "\-\-clear\-autoresume " (\fB\-a\fR) -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. -.TP - -.BR "\-\-cli " (\fB\-C\fR) -This option is to be used in place of a specfile. All options are passed -to \fBcatalyst\fR on the commandline. Please note that this option must -be the last option passed to \fBcatalyst\fR for everything to work correctly. -.TP - -.BR "\-\-config " (\fB\-c\fR) -Tell \fBcatalyst\fR to use a user-defined configuration file. A sample -configuration file is installed at /etc/catalyst/catalyst.conf. -.TP - -.BR "\-\-debug " (\fB\-d\fR) -Enable debugging mode -.TP - -.BR "\-\-fetchonly " (\fB\-F\fR) -This tells \fBcatalyst\fR to only fetch distfiles for the given packages without -performing any building. -.TP - -.BR "\-\-file " (\fB\-f\fR) -Tell \fBcatalyst\fR to use the user supplied specfile. -.TP - -.BR "\-\-help " (\fB\-h\fR) -Print the help message and exit -.TP - -.BR "\-\-purge " (\fB\-p\fR) -Tell \fBcatalyst\fR to clear all temporary directories, package caches, and -autoresume flags for the given target. -.TP - -.BR "\-\-snapshot " (\fB\-s\fR) -Create a Portage snapshot using the specified identifier stamp. -.TP - -.BR "\-\-verbose " (\fB\-v\fR) -Enable verbose mode. - -.BR "\-\-version " (\fB\-V\fR) -Print the version information and exit -.TP - -.SH EXAMPLES -.TP -Using the commandline option (\-C, \-\-cli) to build a Portage snapshot: -catalyst \-C target=snapshot version_stamp=my_date -.TP -Using the specfile option (\-f, \-\-file) to build a stage target: -catalyst \-f stage1\-specfile.spec -.TP -Using the snapshot option (\-s, \-\-snapshot) to package a Portage snapshot -using the datestamp 20051208: -catalyst \-s 20051208 - -.SH FILES -.TP -Example specfiles can be found in /usr/share/doc/catalyst-/examples. -An example configuration file can be found at /etc/catalyst/catalyst.conf. - -.SH BUGS -.TP -An up-to-date list of Catalyst bugs can always be found listed on the Gentoo -Linux bug-tracking system at . - -.SH SEE ALSO -.TP -A more in-depth examination of Catalyst options and procedures can be found -linked from the \fBcatalyst\fR project page, which is located at -. - -.SH NOTES -.TP -\fBCatalyst\fR is conceptually derived from the Gentoo livecd-ng and Gentoo -stager projects, both of which were used to create pre-1.4 Gentoo releases. -.LP -\fBCatalyst\fR was originally conceived and coded by both Daniel Robbins and -John Davis. It is currently maintained by Chris Gianelloni and Eric Edgar and -hass been mostly re-written. - -.SH AUTHOR -John Davis -Chris Gianelloni - -.SH "CVS HEADER" -$Id: catalyst.1,v 1.5 2005/12/08 14:48:58 wolf31o2 Exp $ -- 2.26.2