Greetings, please consider including the attached patch to make the doc/devel-notes.txt instructions a bit less confusing (there is no separate autoheader package) and a bit more helpful -- switching the automake version in particular requires re-running the ./prepare script. The GNU tools are rearranged so that GNU make doesn't get lost in the patch and they are listed in the order required for fresh installs. I've also revised other parts, for spelling (with compliments From aspell) or clarity. This goes with a second patch (also attached) that lets INSTALL point to doc/devel-notes.txt: for developers/CVS builds and for the instructions WRT building the documentation. (INSTALL has some sections for way obsolete operating systems, Red Hat 4.2 SPARC and Solaris 2.4 that was never Y2k certified, which can probably be removed in a separate commit.) -- Matthias Andree
Index: doc/devel-notes.txt
===================================================================
RCS file: /home/roessler/cvs/mutt/doc/devel-notes.txt,v
retrieving revision 3.4
diff -u -r3.4 devel-notes.txt
--- doc/devel-notes.txt 20 Jul 2006 00:57:33 -0000 3.4
+++ doc/devel-notes.txt 8 Aug 2006 07:55:14 -0000
@@ -9,17 +9,29 @@
You'll need several GNU development utilities for working on mutt:
+- autoconf (likewise, versions less than 2.59 are unsupported)
+ (this package includes autoheader and autoreconf)
+
+ If the build fails during any of the auto* stages, first of all try if
+ re-running the ./prepare script fixes things. Remember to give the
+ same options you passed to it or to the configure it generated the
+ last time, you can query them with:
+ ./config.status --version
+
- automake (versions less than 1.9 are not officially supported)
+ (this package includes aclocal)
-- autoconf (likewise, versions less than 2.59 are unsupported)
+ Note that you MUST re-run ./prepare (with the original arguments)
+ if you change the automake version between builds for the same source
+ directory.
-- autoheader
+- GNU make may be needed for the dependency tricks
-- The i18n stuff requires GNU gettext. See intl/VERSION for the
- version we are currently relying on. Please note that using
- gettext-0.10 will most probably not work - get the latest test
- release from alpha.gnu.org, it's the recommended version of
- gettext anyway.
+- The internationalization (i18n) stuff requires GNU gettext.
+ See intl/VERSION for the version we are currently relying on.
+ Please note that using gettext-0.10 will most probably not work -
+ get the latest test release from alpha.gnu.org, it's the recommended
+ version of gettext anyway.
If you are experiencing problems with unknown "dcgettext" symbols,
the autoconf/automake macros from your gettext package are broken.
@@ -49,16 +61,23 @@
if test "$gt_cv_func_gettext_libc" = "yes" \
-- GNU make may be needed for the dependency tricks
-
Generating Mutt Documentation From Source
-----------------------------------------
To translate Mutt's Docbook XML documentation into HTML (and then text),
you'll need one tool and two sets of data which you may need to download
-and install. The tool is xsltproc, and it's a command-line program for
-performing XSL transformations on XML documents. The data sets are the
-Docbook XML and Docbook XSL libraries. You can download these from:
+and install. The tool is xsltproc (part of the libxslt package), and
+it's a command-line program for performing XSL transformations on XML
+documents. The data sets are the Docbook XML and Docbook XSL libraries.
+
+Whenever your operating system provides packages or pkgsrc or ports of
+these, you should install them. Some systems, for instance SUSE Linux
+and FreeBSD's ports system, automatically set up a registry of installed
+XML/XSL and SGML catalogs so that the user does not need to care about
+what to install where, how to set environment variables, and so on.
+
+If your system does not provide these libraries and data sets,
+you can download them from:
. xsltproc
http://xmlsoft.org/
@@ -72,9 +91,8 @@
http://docbook.sourceforge.net/
http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.70.1.zip
-
-First, build and install libxslt to obtain xsltproc, if you don't
-already have it.
+First, if you don't already have xsltproc, build and install libxslt,
+which will provide xsltproc, too.
Next, obtain and unpack the two docbook archives. You can unpack these
anywhere that you want to have them installed -- there's no installation
@@ -86,6 +104,7 @@
the manuals. The environment variable will contain a space-separated
list of "catalog" files for the two docbook archives, so substitute
the path where you unpacked them below:
+
sh$ XML_CATALOG_FILES="/path/to/docbook-xml-4.2/catalog.xml
/path/to/docbook-xsl-1.70.1/catalog.xml"; export XML_CATALOG_FILES
or
csh$ setenv XML_CATALOG_FILES "/path/to/docbook-xml-4.2/catalog.xml
/path/to/docbook-xsl-1.70.1/catalog.xml"
@@ -98,13 +117,14 @@
to turn the HTML into text, so if that fails you may need to install
something else.
+
Getting started from CVS
------------------------
-Once you've checked out a copy of the source from CVS, you'll need to
-run the script called 'prepare' that is in the root directory. The
-script does all the automake/autoconf magic that needs to be done with
-a fresh checkout.
+Once you've checked out a copy of the source from CVS, or changed your
+automake version, you'll need to run the script called './prepare' that
+is in the root directory. The script does all the automake/autoconf
+magic that needs to be done with a fresh checkout.
A word about warnings
@@ -116,8 +136,8 @@
Nevertheless, the code in intl/ is said to generate some warnings with
the compiler settings we usually rely upon. This code is not
-maintained by the mutt developpers, so please redirect any comments to
-the GNU gettext library's developpers.
+maintained by the mutt developers, so please redirect any comments to
+the GNU gettext library's developers.
Style Guide
@@ -126,10 +146,10 @@
- global functions should have the prefix "mutt_". All
other functions should be declared "static".
-- avoid global vars where possible. If one is required,
+- avoid global variables where possible. If one is required,
try to contain it to a single source file and declare it
- "static". Global vars should have the first letter of
- each word capitilized, and no underscores should be used
+ "static". Global variables should have the first letter of
+ each word capitalized, and no underscores should be used
(e.g., MailGid, LastFolder, MailDir).
- re-use code as much as possible. There are a lot of
@@ -151,7 +171,7 @@
- doc/manual.xml.{head,tail} contain The Manual.
-- doc/muttrc.man.{head,tail} contain an abriged version of The
+- doc/muttrc.man.{head,tail} contain an abridged version of The
Manual in nroff format (see man(7)), which deals with
configuration file commands.
@@ -186,7 +206,7 @@
comments.
- \(rs can be used to represent a backslash (\). This is intended
- to help avoiding poblems when trying to represent any of the \
+ to help avoiding problems when trying to represent any of the \
sequences used by makedoc.
- .dl on a line starts a "definition list" environment (name taken
@@ -200,7 +220,7 @@
- .ts on a line starts a "verbose tscreen" environment (name taken from
SGML). Please try to keep lines inside such an environment
- short; a length of abut 40 characters should be ok. This is
+ short; a length of abut 40 characters should be OK. This is
necessary to avoid a really bad-looking muttrc (5) manual page.
- .te on a line finishes this environment.
Index: INSTALL
===================================================================
RCS file: /home/roessler/cvs/mutt/INSTALL,v
retrieving revision 3.3
diff -u -r3.3 INSTALL
--- INSTALL 18 May 2006 18:11:20 -0000 3.3
+++ INSTALL 8 Aug 2006 08:02:51 -0000
@@ -25,15 +25,16 @@
Ultrix
UnixWare
-- An ANSI C compiler (such as gcc) is required.
+- If you are building from CVS, or if you are changing parts of mutt,
+ particularly the build system, do read doc/devel-notes.txt.
+
+- An ANSI C compiler (such as GCC) is required.
- You must also have a SysV compatible curses library, or you must
install either
GNU ncurses, ftp://prep.ai.mit.edu/pub/gnu/
-
or
-
S-Lang, ftp://space.mit.edu/pub/davis/slang/
- Mutt needs an implementation of the iconv API for character set
@@ -43,12 +44,9 @@
- For building the manual, mutt needs the DocBook XSL stylesheets
as well as the DocBook DTD as of version 4.2 installed locally.
+ For details, please see the section "Generating Mutt Documentation
+ From Source" in doc/devel-notes.txt.
- You may find these packaged by your distribution likely named
- similar to 'docbook-xsl' and 'docbook-xml'. If not, try the
- homepage at:
-
- http://sourceforge.net/projects/docbook
Installation
============
Attachment:
pgpcbr6x58png.pgp
Description: PGP signature