Use html2text instead of lynx for dumping doc to flat text

svn path=/rpkid/Makefile; revision=3208

1 files changed, 159 insertions, 135 deletions

diff --git a/rpkid/doc/Installation b/rpkid/doc/Installation
index 83d3108c..5b191547 100644
--- a/rpkid/doc/Installation
+++ b/rpkid/doc/Installation
@@ -1,135 +1,159 @@
-Installation Guide
-
-   Installation instructions for rpkid et al.
-
-   These are the production-side RPKI tools, for Internet Registries
-   (RIRs, LIRs, etc). See the "rcynic" program for relying party tools.
-
-   rpkid is a set of Python modules supporting generation and maintenance
-   of resource certificates. Most of the code is in the rpkid/rpki/
-   directory. rpkid itself is a relatively small program that calls the
-   library modules. There are several other programs that make use of the
-   same libraries, as well as a collection of test programs.
-
-   At present the package is intended to be run out of its build
-   directory. Setting up proper installation in a system area using the
-   Python distutils package would likely not be very hard but has not yet
-   been done.
-
-   Note that initial development of this code has been on FreeBSD, so
-   installation will probably be easiest on FreeBSD.
-
-   Before attempting to build the package, you need to install any missing
-   prerequisites. Note that the Python code requires Python version 2.5 or
-   2.6. rpkid et al are mostly self-contained, but do require a small
-   number of external packages to run.
-
-     * If your Python installation does not already include the sources
-       files needed to compile new Python extension modules, you will need
-       to install whatever package does include those source files. The
-       need for and name of this package varies from system to system. On
-       FreeBSD, the base Python interpreter package includes the
-       development sources; on at least some Linux distributions, you have
-       to install a separate "python-devel" package or something similar.
-       If you get compilation errors trying to build the POW code (below)
-       and the error message says something about the file "Python.h"
-       being missing, this is almost certainly your problem.
-     * http://codespeak.net/lxml/, a Pythonic interface to the Gnome
-       LibXML2 libraries. lxml in turn requires the LibXML2 C libraries.
-          + FreeBSD: /usr/ports/devel/py-lxml
-          + Fedora: python-lxml.i386
-          + Ubuntu: python-lxml
-     * http://sourceforge.net/projects/mysql-python/, the Python "db"
-       interface to MySQL. MySQLdb in turn requires MySQL client and
-       server. rpkid et al have been tested with MySQL 5.0 and 5.1.
-          + FreeBSD: /usr/ports/databases/py-MySQLdb
-          + Fedora: MySQL-python.i386
-          + Ubuntu: python-mysqldb
-
-   rpkid et al also make heavy use of a modified copy of the Python
-   OpenSSL Wrappers (POW) package, but this copy has enough modifications
-   and additions that it's included in the subversion tree.
-
-   The next step is to build the OpenSSL and POW binaries. At present the
-   OpenSSL code is just a snapshot of the OpenSSL development sources,
-   compiled with special options to enable RFC 3779 support that ISC wrote
-   under previous contract to ARIN. The POW (Python OpenSSL Wrapper)
-   library is an extended copy of the stock POW release.
-
-   To build these, cd to the top-level directory in the distribution and
-   type "make".
-
-   $ cd $top
-   $ make
-
-   This should automatically build everything, in the right order,
-   including staticly linking the POW extension module with the OpenSSL
-   library to provide RFC 3779 support. If you get errors building POW,
-   see the above discussion of Python development sources.
-
-   The architecture is intended to support hardware signing modules
-   (HSMs), but the code to support them has not been written.
-
-   At this point, you should have all the necessary software installed to
-   run the core programs, but you will probably want to test it. The test
-   suite requires a few more external packages, only one of which is
-   Python code.
-
-     * http://pyyaml.org/. Several of the test programs use PyYAML to
-       parse a YAML description of a simulated allocation hierarchy to
-       test.
-          + FreeBSD: /usr/ports/devel/py-yaml
-          + Ubuntu: python-yaml
-     * http://xmlsoft.org/XSLT/. Some of the test code uses xsltproc, from
-       the Gnome LibXSLT package.
-          + FreeBSD: /usr/ports/textproc/libxslt
-          + Ubuntu: xsltproc
-
-   All tests should be run from the rpkid/ or myrpki/ directories.
-
-   Some of the tests require MySQL databases to store their data. To set
-   up all the databases that the tests will need, run the SQL commands in
-   rpkid/smoketest.setup.sql. The MySQL command line client is usually the
-   easiest way to do this, eg:
-
-   $ cd $top/rpkid
-   $ mysql -u root -p <smoketest.setup.sql
-
-   To run the tests, run "make all-tests":
-
-   $ cd $top/rpkid
-   $ make all-tests
-
-   If nothing explodes, your installation is probably ok. Any Python
-   backtraces in the output indicate a problem.
-
-   There's a last set of tools that only developers should need, as
-   they're only used when modifying schemas or regenerating the
-   documentation. These tools are listed here for completeness.
-
-     * http://www.doxygen.org/. Doxygen in turn pulls in several other
-       tools, notably Graphviz, pdfLaTeX, and Ghostscript.
-          + FreeBSD: /usr/ports/devel/doxygen
-          + Ubuntu: doxygen
-     * http://lynx.isc.org/current/. The documentation build process uses
-       xsltproc and Lynx to dump flat text versions of a few critical
-       documentation pages.
-          + FreeBSD: /usr/ports/www/lynx
-          + Ubuntu: lynx
-     * http://www.thaiopensource.com/relaxng/trang.html. Trang is used to
-       convert RelaxNG schemas from the human-readable "compact" form to
-       the XML form that LibXML2 understands. Trang in turn requires Java.
-          + FreeBSD: /usr/ports/textproc/trang
-     * http://search.cpan.org/dist/SQL-Translator/. SQL-Translator, also
-       known as "SQL Fairy", includes code to parse an SQL schema and dump
-       a description of it as Graphviz input. SQL Fairy in turn requires
-       Perl.
-          + FreeBSD: /usr/ports/databases/p5-SQL-Translator
-
-   Once you've finished with installation, the next thing you should read
-   is the Configuration Guide.
-     __________________________________________________________________
-
-
-    Generated on Fri Apr 16 17:28:16 2010 for RPKI Engine by  doxygen
-    1.6.3
+
+
+****** Installation Guide ******
+
+Installation instructions for rpkid et al.
+
+These are the production-side RPKI tools, for Internet Registries (RIRs, LIRs,
+etc). See the "rcynic" program for relying party tools.
+
+rpkid is a set of Python modules supporting generation and maintenance of
+resource certificates. Most of the code is in the rpkid/rpki/ directory. rpkid
+itself is a relatively small program that calls the library modules. There are
+several other programs that make use of the same libraries, as well as a
+collection of test programs.
+
+At present the package is intended to be run out of its build directory.
+Setting up proper installation in a system area using the Python distutils
+package would likely not be very hard but has not yet been done.
+
+Note that initial development of this code has been on FreeBSD, so installation
+will probably be easiest on FreeBSD.
+
+Before attempting to build the package, you need to install any missing
+prerequisites. Note that the Python code requires Python version 2.5 or 2.6.
+rpkid et al are mostly self-contained, but do require a small number of
+external packages to run.
+
+
+* If your Python installation does not already include the sources files needed
+  to compile new Python extension modules, you will need to install whatever
+  package does include those source files. The need for and name of this
+  package varies from system to system. On FreeBSD, the base Python interpreter
+  package includes the development sources; on at least some Linux
+  distributions, you have to install a separate "python-devel" package or
+  something similar. If you get compilation errors trying to build the POW code
+  (below) and the error message says something about the file "Python.h" being
+  missing, this is almost certainly your problem.
+
+* http://codespeak.net/lxml/, a Pythonic interface to the Gnome LibXML2
+  libraries. lxml in turn requires the LibXML2 C libraries.
+
+
+  o FreeBSD: /usr/ports/devel/py-lxml
+  o Fedora: python-lxml.i386
+  o Ubuntu: python-lxml
+
+* http://sourceforge.net/projects/mysql-python/, the Python "db" interface to
+  MySQL. MySQLdb in turn requires MySQL client and server. rpkid et al have
+  been tested with MySQL 5.0 and 5.1.
+
+  o FreeBSD: /usr/ports/databases/py-MySQLdb
+  o Fedora: MySQL-python.i386
+  o Ubuntu: python-mysqldb
+
+
+rpkid et al also make heavy use of a modified copy of the Python OpenSSL
+Wrappers (POW) package, but this copy has enough modifications and additions
+that it's included in the subversion tree.
+
+The next step is to build the OpenSSL and POW binaries. At present the OpenSSL
+code is just a snapshot of the OpenSSL development sources, compiled with
+special options to enable RFC 3779 support that ISC wrote under previous
+contract to ARIN. The POW (Python OpenSSL Wrapper) library is an extended copy
+of the stock POW release.
+
+To build these, cd to the top-level directory in the distribution and type
+"make".
+
+
+     $ cd $top
+     $ make
+
+This should automatically build everything, in the right order, including
+staticly linking the POW extension module with the OpenSSL library to provide
+RFC 3779 support. If you get errors building POW, see the above discussion of
+Python development sources.
+
+The architecture is intended to support hardware signing modules (HSMs), but
+the code to support them has not been written.
+
+At this point, you should have all the necessary software installed to run the
+core programs, but you will probably want to test it. The test suite requires a
+few more external packages, only one of which is Python code.
+
+
+* http://pyyaml.org/. Several of the test programs use PyYAML to parse a YAML
+  description of a simulated allocation hierarchy to test.
+
+
+  o FreeBSD: /usr/ports/devel/py-yaml
+  o Ubuntu: python-yaml
+
+* http://xmlsoft.org/XSLT/. Some of the test code uses xsltproc, from the Gnome
+  LibXSLT package.
+
+  o FreeBSD: /usr/ports/textproc/libxslt
+  o Ubuntu: xsltproc
+
+
+All tests should be run from the rpkid/ or myrpki/ directories.
+
+Some of the tests require MySQL databases to store their data. To set up all
+the databases that the tests will need, run the SQL commands in rpkid/
+smoketest.setup.sql. The MySQL command line client is usually the easiest way
+to do this, eg:
+
+
+     $ cd $top/rpkid
+     $ mysql -u root -p <smoketest.setup.sql
+
+To run the tests, run "make all-tests":
+
+
+     $ cd $top/rpkid
+     $ make all-tests
+
+If nothing explodes, your installation is probably ok. Any Python backtraces in
+the output indicate a problem.
+
+There's a last set of tools that only developers should need, as they're only
+used when modifying schemas or regenerating the documentation. These tools are
+listed here for completeness.
+
+
+* http://www.doxygen.org/. Doxygen in turn pulls in several other tools,
+  notably Graphviz, pdfLaTeX, and Ghostscript.
+
+
+  o FreeBSD: /usr/ports/devel/doxygen
+  o Ubuntu: doxygen
+
+* http://www.mbayer.de/html2text/. The documentation build process uses
+  xsltproc and html2text to dump flat text versions of a few critical
+  documentation pages.
+
+
+  o FreeBSD: /usr/ports/textproc/html2text
+
+* http://www.thaiopensource.com/relaxng/trang.html. Trang is used to convert
+  RelaxNG schemas from the human-readable "compact" form to the XML form that
+  LibXML2 understands. Trang in turn requires Java.
+
+
+  o FreeBSD: /usr/ports/textproc/trang
+
+* http://search.cpan.org/dist/SQL-Translator/. SQL-Translator, also known as
+  "SQL Fairy", includes code to parse an SQL schema and dump a description of
+  it as Graphviz input. SQL Fairy in turn requires Perl.
+
+  o FreeBSD: /usr/ports/databases/p5-SQL-Translator
+
+
+Once you've finished with installation, the next thing you should read is the
+Configuration_Guide.
+
+
+
+
+