Change -- to <d/> where appropriate. Finish up the autotools doc

git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@11 176d3534-300d-0410-8db8-84e73ed771c3

19 files changed, 666 insertions, 46 deletions

diff --git a/ebuild-writing/file-format/text.xml b/ebuild-writing/file-format/text.xml
index 499a60c..2a439da 100644
--- a/ebuild-writing/file-format/text.xml
+++ b/ebuild-writing/file-format/text.xml
@@ -98,7 +98,7 @@ Overall, this gives us a filename like <c>libfoo-1.2.5b_pre5-r2.ebuild</c>.
 All ebuilds committed to the tree should have a three line header immediately at
 the start indicating copyright. This must be an exact copy of the contents of
 <c>$(portageq portdir)/header.txt</c>. Ensure that the <c>$Header: $</c> line is not
-modified manually -- CVS will handle this line specially.
+modified manually <d/> CVS will handle this line specially.
 </p>
 
 <codesample lang="ebuild">
@@ -128,7 +128,7 @@ tabs for indentation) when you commit.
 
 <p>
 Where possible, try to keep lines no wider than 80 positions. A
-'position' is generally the same as a character -- tabs are four
+'position' is generally the same as a character <d/> tabs are four
 positions wide, and multibyte characters are just one position wide.
 </p>
 
diff --git a/ebuild-writing/messages/text.xml b/ebuild-writing/messages/text.xml
index bcb002e..fdc5477 100644
--- a/ebuild-writing/messages/text.xml
+++ b/ebuild-writing/messages/text.xml
@@ -33,7 +33,7 @@ with their fancy leading markers.
 
 <p>
 There are a number of functions available to assist here. The `echo` bash
-internal is the simplest -- it simply displays its parameters as a message.
+internal is the simplest <d/> it simply displays its parameters as a message.
 </p>
 
 <p>
@@ -86,14 +86,14 @@ is mainly used for displaying additional error details before bailing out.
 For <e>really</e> important messages, <c>eutils.eclass</c> provides <c>ebeep</c> and
 <c>epause</c>. The former will beep a number of times, and the latter will pause
 for several seconds to allow the user to read any messages. Both can be disabled
-by the user -- you must <b>not</b> attempt to override the user's preference in
+by the user <d/> you must <b>not</b> attempt to override the user's preference in
 this. <c>ebeep</c> takes an optional parameter specifying how many times to beep.
 <c>epause</c> takes an optional parameter (which <b>must</b> be an exact whole number)
 specifying for how long it should sleep.
 </p>
 
 <p>
-Do not abuse these functions -- better to save them for when things really are
+Do not abuse these functions <d/> better to save them for when things really are
 important.
 </p>
 
diff --git a/ebuild-writing/use-conditional-code/text.xml b/ebuild-writing/use-conditional-code/text.xml
index 84fc490..79d580b 100644
--- a/ebuild-writing/use-conditional-code/text.xml
+++ b/ebuild-writing/use-conditional-code/text.xml
@@ -52,7 +52,7 @@ function available.
 </p>
 
 <p>
-You must not rely upon <c>use</c> producing an output -- this no longer happens.
+You must not rely upon <c>use</c> producing an output <d/> this no longer happens.
 If you really need output displayed, use the <c>usev</c> function. The
 <c>useq</c> function is available for explicitly requesting no output.
 </p>
diff --git a/ebuild-writing/using-eclasses/text.xml b/ebuild-writing/using-eclasses/text.xml
index 171d967..fdf8da0 100644
--- a/ebuild-writing/using-eclasses/text.xml
+++ b/ebuild-writing/using-eclasses/text.xml
@@ -21,7 +21,7 @@ how to use an eclass which has already been written.
 To use an eclass, it must be 'inherited'. This is done via the <c>inherit</c>
 function, which is provided by <c>ebuild.sh</c>. The <c>inherit</c> statement must
 come at the top of the ebuild, *before* any functions. Conditional inherits are
-illegal (except where the inheritance criteria are cache-constant -- see `The
+illegal (except where the inheritance criteria are cache-constant <d/> see `The
 Portage Cache`_).
 </p>
 
diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index d6f5aec..a13202a 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -261,7 +261,7 @@ See `Keywording`_ for how to handle this variable.
 <p>
 Conditional source files based upon USE flags are allowed using the usual
 <c>flag? ( )</c> syntax. This is often useful for arch-specific code or for binary
-packages -- downloading sparc binaries on ppc would be a waste of bandwidth.
+packages <d/> downloading sparc binaries on ppc would be a waste of bandwidth.
 </p>
 
 <codesample lang="ebuild">
diff --git a/general-concepts/autotools/text.xml b/general-concepts/autotools/text.xml
index 3541d70..6224ebd 100644
--- a/general-concepts/autotools/text.xml
+++ b/general-concepts/autotools/text.xml
@@ -16,17 +16,17 @@ when working with ebuilds:
 
 <ul>
   <li>
-  Finding and correcting build issues is often easier if the build system is
-  not seen simply as a scary black box.
+    Finding and correcting build issues is often easier if the build system is
+    not seen simply as a scary black box.
   </li>
   <li>
-  The autotools input files can help when determining a package's build-time
-  dependencies.
+    The autotools input files can help when determining a package's build-time
+    dependencies.
   </li>
   <li>
-  The risk of accidentally breaking something by patching the wrong file at the
-  wrong time is greatly reduced if the relationship between the build system
-  files is understood.
+    The risk of accidentally breaking something by patching the wrong file at the
+    wrong time is greatly reduced if the relationship between the build system
+    files is understood.
   </li>
 </ul>
 </body>
@@ -46,6 +46,626 @@ create the build system for a package.
 A basic overview of how the main autotools components fit together.
 </figure>
 
+<p>
+In a simple setup:
+</p>
+
+<ul>
+  <li>
+    The <c>autoconf</c> program produces a <c>configure</c> script from either
+    <c>configure.in</c> or <c>configure.ac</c> (see note below).
+  </li>
+  <li>
+    The <c>automake</c> program produces a <c>Makefile.in</c> from a <c>Makefile.am</c>.
+  </li>
+  <li>
+    The <c>configure</c> script is run to produce one or more <c>Makefile</c> files from
+    <c>Makefile.in</c> files.
+  </li>
+  <li>
+    The <c>make</c> program uses the <c>Makefile</c> to compile the program.
+  </li>
+</ul>
+
+
+<note>
+The <c>configure.in</c> name used to be standard. However, the GNU
+documentation now recommends <c>configure.ac</c> as it is more obvious which
+program should be used when processing it. The files perform the same purpose
+and have the same format <d/> the only difference is the name.
+</note>
+
+<p>
+You will see autotools being used variously in both <c>src_unpack</c> and
+<c>src_compile</c>. The QA people prefer it in <c>src_unpack</c> <d/> the rationale is
+that <c>src_unpack</c> handles "getting the package ready to be compiled" <d/> but
+there is no official policy which mandates this.
+</p>
+
+<p>
+The <c>autoreconf</c> tool supposedly runs <c>autoconf</c> (and <c>automake</c>,
+<c>autoheader</c>, <c>aclocal</c>, <c>autopoint</c> and <c>libtoolize</c>) as necessary.
+Sometimes it works. Some packages ship a shell script named <c>autogen.sh</c> which
+does the same thing (this is <e>not</e> related to <c>autogen</c>).
+</p>
+
+<warning>
+You must <b>not</b> attempt to modify any of the generated files in
+between running <c>configure</c> and <c>make</c>. This can lead to autotools
+trying to be clever and recreate the files, in turn leading to your changes
+being removed. In some situations this will also result in <c>./configure</c>
+arguments being silently dropped, which can give broken dependencies.
+The best way to proceed is usually to work with the <c>.ac</c> / <c>.in</c> files
+instead.
+</warning>
+
+</body>
+</section>
+
+<section>
+<title>Simple Autotools Patching Example</title>
+<body>
+
+<p>
+The following snippet illustrates the correct way to proceed after patching
+either <c>Makefile.am</c> or <c>configure.ac</c>:
+</p>
+
+<codesample lang="ebuild">
+src_unpack() {
+    unpack ${A}
+    cd "${S}"
+
+    # Remove problematic LDFLAGS declaration
+    sed -i -e '/^LDFLAGS/d' src/Makefile.am
+
+    # Rerun autotools
+    einfo "Regenerating autotools files..."
+    WANT_AUTOCONF=2.5 autoconf || die "autoconf failed"
+    WANT_AUTOMAKE=1.9 automake || die "automake failed"
+}
+
+src_compile() {
+    econf $(use_enable nls) || die "econf failed"
+    emake || die "emake failed"
+}
+</codesample>
+
+<p>
+The <c>einfo</c> message before running autotools is not mandatory. However, these
+steps can sometimes take a while and may produce no output, so it may make sense
+to let the user know that something is still happening. See `Messages`_.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>The <c>configure.ac</c> File</title>
+<body>
+
+<p>
+The <c>configure.ac</c> file is used to create the <c>./configure</c> script. It
+consists of a series of macros which are processed and expanded by <c>autoconf</c>.
+These macros can check for packages and libraries, handle <c>--enable</c> and
+<c>--with</c> switches, and generate various files.
+</p>
+
+</body>
+
+<subsection>
+<title>Basic Format of <c>configure.ac</c></title>
+<body>
+
+<p>
+The <c>configure.ac</c> file is a basic text file. Indenting and whitespace are
+largely irrelevant. Comments are indicated by the string <c>dnl</c> (<c>dnl</c> is
+actually a macro which discards the remainder of the input <d/> it stands for
+"discard new line").
+</p>
+
+<p>
+If the previous sentence made you uneasy, you should probably stop reading this
+page. It gets far worse.
+</p>
+
+<p>
+A typical file might start with something like the following:
+</p>
+
+<codesample lang="autotools">
+dnl Process this file with autoconf
+AC_INIT(appname, 0.1)
+AC_PREREQ(2.5)
+AC_CONFIG_SRCDIR(src/main.c)
+AC_CONFIG_AUX_DIR(config)
+AM_INIT_AUTOMAKE(1.8)
+</codesample>
+
+<p>
+The <c>AC_PREREQ</c> line, if present, tells you which <c>autoconf</c> version you
+need. This is useful, because <c>autoconf</c> is not compatible between versions.
+In the above example, we need <c>=autoconf-2.5*</c>. and we should
+<c>export WANT_AUTOCONF="2.5"</c> (or use the <c>autoconf-2.59</c> script) when calling
+<c>autoconf</c>.
+</p>
+
+<p>
+The <c>AM_INIT_AUTOMAKE</c> line tells us which <c>automake</c> version we need.
+Again, there is little chance that an <c>automake-1.7</c> script will work properly
+with <c>automake-1.8</c>. Setting <c>WANT_AUTOMAKE="1.8"</c> in the environment can be
+used to make an unversioned <c>automake</c> call run the correct version.
+</p>
+
+<note>
+The <c>WANT_</c> variables are a Gentoo feature that originally came from
+Mandrake. Other distributions may handle things differently.
+</note>
+
+<p>
+Usually, some standard checks will follow:
+</p>
+
+<codesample lang="autotools">
+dnl Check for toolchain and install components
+AC_PROG_CC
+AC_PROG_INSTALL
+AC_PROG_LN_S
+AC_PROG_RANLIB
+</codesample>
+
+<p>
+For non-standard applications, you may also see manual checks:
+</p>
+
+<codesample lang="autotools">
+dnl Check for sed
+AC_CHECK_PROGS(regex_cmd, sed)
+if test x$regex_cmd = "x" ; then
+    AC_MSG_ERROR([sed is required to build the data files.])
+fi
+</codesample>
+
+<p>
+You may also see checks for compiler features:
+</p>
+
+<codesample lang="autotools">
+dnl Check that our compiler can do const and inline
+AC_C_CONST
+AC_C_INLINE
+</codesample>
+
+<p>
+Library and header checks:
+</p>
+
+<codesample lang="autotools">
+dnl Check for standard headers:
+AC_HEADER_STDC
+AC_HEADER_DIRENT
+AC_CHECK_HEADERS([stdlib.h stdio.h libintl.h locale.h])
+
+dnl Check for libraries:
+AC_CHECK_LIB(ssl, SSL_free)
+</codesample>
+
+<p>
+And function checks:
+</p>
+
+<codesample lang="autotools">
+dnl Check for functions:
+AC_CHECK_FUNCS([setlocale strtol])
+</codesample>
+
+<p>
+Often these will be all jumbled together without any useful comments. In some
+cases, many of the checks done won't even be necessary for the application in
+question <d/> most autotools code is copy/pasted rather than written from scratch,
+and <c>autoscan</c> (a tool which helps write <c>configure.ac</c>) is sometimes
+over-eager to add in checks.
+</p>
+
+<p>
+The file will finish with some output functions:
+</p>
+
+<codesample lang="autotools">
+AM_CONFIG_HEADER(config.h)
+AC_OUTPUT(Makefile src/Makefile nls/Makefile man/Makefile tests/Makefile)
+</codesample>
+
+<p>
+These are used to make the <c>./configure</c> script generate the relevant files.
+</p>
+
+</body>
+</subsection>
+
+<subsection>
+<title>Enable and Disable Checks</title>
+<body>
+
+<p>
+So far we've only seen 'hard' dependencies. Many packages have <e>optional</e>
+support for various extras (graphics toolkits, libraries which add
+functionality, interpreters, features, ...). This is (if we're lucky) handled
+via <c>--enable-foo</c> and <c>--disable-foo</c> switches to <c>./configure</c>. which
+are generated from <c>autoconf</c> rules.
+</p>
+
+<p>
+A simple <c>--enable</c> / <c>--disable</c> function might look something like the
+following:
+</p>
+
+<codesample lang="autotools">
+AC_MSG_CHECKING(--enable-cscope argument)
+AC_ARG_ENABLE(cscope,
+    [  --enable-cscope         Include cscope interface.],
+    [enable_cscope=$enableval],
+    [enable_cscope="no"])
+AC_MSG_RESULT($enable_cscope)
+if test "$enable_cscope" = "yes"; then
+  AC_DEFINE(FEAT_CSCOPE)
+fi
+</codesample>
+
+<p>
+Sometimes more complicated checks are included based upon whether or not an
+option is enabled. There are also some predefined macros which include
+<c>AC_ARG_ENABLE</c>. so grepping <c>configure.ac</c> for <c>AC_ARG_ENABLE</c> may not
+give a complete list. A better way is to use <c>./configure --help</c> and check
+the output.
+</p>
+
+<important>
+The third argument is used when a <c>--enable</c> or <c>--disable</c>
+switch to <c>./configure</c> is provided, and the fourth is used when such a
+switch is <e>not</e> passed. A common misconception is that the third is enable
+and the fourth is disable <d/> this is <b>not</b> the case. You may encounter
+packages that get this wrong.
+</important>
+
+<p>
+A simple way to check that a package is using this macro properly is to
+install the optional dependency, and then try all of <c>./configure</c>.
+<c>./configure --enable-foo</c> and <c>./configure --disable-foo</c>. If the second
+and third runs give the same results, something is wrong. If the first run gives
+a <e>different</e> result to the second and third, there is a good chance that a
+misunderstanding of the <c>AC_ARG_ENABLE</c> arguments is to blame.
+</p>
+
+</body>
+</subsection>
+
+<subsection>
+<title>With and Without Checks</title>
+<body>
+
+<p>
+A simple <c>--with</c> / <c>--without</c> check might look like:
+</p>
+
+<codesample lang="autotools">
+AC_MSG_CHECKING([whether to enable foo])
+AC_ARG_WITH(foo,
+    [  --with-foo           enable foo support],
+    with_foo=$withval,
+    with_foo=yes)
+AC_MSG_RESULT($with_foo)
+</codesample>
+
+<p>
+Again, the third argument is for 'specified' and the fourth for 'not specified',
+and there are standard macros which include <c>with</c> options.
+</p>
+
+</body>
+</subsection>
+
+<subsection>
+<title>Automatic Checks</title>
+<body>
+
+<p>
+It's possible to write autoconf rules which bypass the manual enable / disable
+convention (or which just ignore what the user asks for). If your package does
+this, it must be fixed to avoid dependency problems.
+</p>
+
+<p>
+The most common form is packages which simply use <c>AC_CHECK_LIB</c> to decide
+whether or not to enable a feature. If you find a package which does this, you
+<b>must</b> change the behaviour.
+</p>
+
+</body>
+</subsection>
+
+<subsection>
+<title>Quoting Rules for <c>configure.ac</c></title>
+<body>
+
+<p>
+Behind the scenes, <c>autoconf</c> makes heavy use of the <c>m4</c> macro processor to
+do the work. The <c>m4</c> quote characters are set by <c>autoconf</c> to be <c>[</c> and
+<c>]</c> for opening and closing quotes respectively. Using <c>"</c> or <c>'</c> may
+produce unexpected results.
+</p>
+
+<p>
+To include a literal left square bracket, the easiest thing to do is to use the
+special string <c>@&lt;:@</c>. For a right bracket, use <c>@:&gt;@</c>.
+</p>
+
+<p>
+For example:
+</p>
+
+<codesample lang="autotools">
+AC_MSG_RESULT(the first)
+AC_MSG_RESULT([the second])
+AC_MSG_RESULT("the third")
+AC_MSG_RESULT(@&lt;:@the fourth@:&gt;@)
+AC_MSG_RESULT([@&lt;:@the fifth@:&gt;@])
+</codesample>
+
+<p>
+gives:
+</p>
+
+<pre>
+    the first
+    the second
+    "the third"
+    [the fourth]
+    [the fifth]
+</pre>
+
+<p>
+When in doubt, it is generally safest to quote macro arguments using <c>[ ]</c>
+rather than leaving things unquoted.
+</p>
+
+</body>
+</subsection>
+</section>
+
+<section>
+<title>The <c>Makefile.am</c> Files</title>
+<body>
+
+<p>
+The <c>Makefile.am</c> file is processed by <c>automake</c> to create <c>Makefile.in</c>.
+which is in turn processed by <c>configure</c> to create <c>Makefile</c>. which is in
+turn used by <c>make</c> to build the software.
+</p>
+
+<p>
+The basic format is like that of a <c>Makefile</c>. However, you will see various
+'special' variables being set, rather than every rule being written manually.
+</p>
+
+<p>
+A very simple example:
+</p>
+
+<codesample lang="autotools">
+bin_PROGRAMS = myapp
+myapp_SOURCES = myapp_commandline.c myapp.c
+</codesample>
+
+<p>
+All the standard GNU rules will be generated, so <c>make</c>. <c>make clean</c>.
+<c>make distclean</c>. <c>make dist</c> and so on will all work here.
+</p>
+
+<p>
+You may also see some standard <c>Makefile</c> constructs showing up whenever there
+isn't a standard <c>automake</c> way of handling a certain task. For example:
+</p>
+
+<codesample lang="autotools">
+CLEANFILES = glep31check.1
+man_MANS = glep31check.1
+EXTRA_DIST = glep31check.in
+
+%.1 : %.in
+    @regex_cmd@ -e "s,\@VERSION\@,$(VERSION),g" $? > $@
+</codesample>
+
+<p>
+Here, the <c>@regex_cmd@</c> variable will be substituted with whatever
+<c>configure</c> detects (<c>sed</c> in this case) when creating the <c>Makefile</c>.
+This is handled via the macro <c>AC_SUBST(VARNAME)</c> in <c>configure.ac</c>.
+</p>
+
+</body>
+
+<subsection>
+<title>Makefile Variables</title>
+<body>
+
+<p>
+Sometimes, badly behaved <c>Makefile.am</c> files will override user variables such
+as <c>CFLAGS</c>. This must not be allowed <d/> see `Not Filtering Variables`_. There
+are separate special variables which should be used in these situations <d/> for
+setting <c>CFLAGS</c>. for example, a <c>Makefile.am</c> should use <c>AM_CFLAGS</c> so
+that user preferences are not ignored.
+</p>
+
+<p>
+So, if a <c>Makefile.am</c> contains, say:
+</p>
+
+<pre>
+CFLAGS="-Wall"
+</pre>
+
+<p>
+You should <c>sed</c> or <c>patch</c> it to use:
+</p>
+
+<pre>
+AM_CFLAGS="-Wall"
+</pre>
+
+<p>
+Remember to manually run <c>autoconf</c> then <c>automake</c> if you do this.
+</p>
+
+</body>
+</subsection>
+</section>
+
+<section>
+<title>The <c>config.h.in</c> File</title>
+<body>
+
+<p>
+The <c>config.h.in</c> file is generated by <c>autoheader</c>. You shouldn't have to
+worry about this usually, but occasionally you may need to run <c>autoheader</c>
+manually as part of the build process if upstream do not ship a pre-generated
+version.
+</p>
+
+</body>
+</section>
+
+<section>
+<title><c>aclocal</c> and <c>m4</c> Files</title>
+<body>
+
+<p>
+In the <c>configure.ac</c> or <c>configure.in</c> files you can call not only the
+default macros defined by <c>autoconf</c> and <c>automake</c>. but also other
+functions which can be defined by specific packages like libraries and programs
+to check for their features in the correct manner.
+</p>
+
+<p>
+Those functions are (usually) defined in <c>m4</c> files placed in
+the <c>/usr/share/aclocal</c> directory by packages. Problems can arise when you
+need to regenerate the <c>autotools</c> files, because the functions used by the
+<c>configure.ac</c> file can be defined in an <c>m4</c> macro file which isn't
+installed on the user's system. This is the case for example for some optional
+features which require libraries and are disabled by <c>USE</c> flags. If the
+<c>m4</c> files aren't installed in the user's system, the <c>autoconf</c> step will
+fail.
+</p>
+
+<p>
+To resolve this, most packages just ship the <c>m4</c> macro files needed for their
+<c>configure.ac</c> in an <c>m4</c> subdirectory in the source package. Unfortunately,
+not all <c>m4</c> directories are complete, even if they are present.
+</p>
+
+<p>
+In those cases you need to find out the <c>m4</c> file, usually installed by the
+dependency in <c>/usr/share/aclocal</c>. and make sure that the <c>src_unpack</c>
+stage both makes available those files to the autotools and calls <c>aclocal</c> to
+recreate the <c>aclocal.m4</c> file which is used by <c>autoconf</c> when creating the
+configure script.
+</p>
+
+<p>
+Usually it's more than one <c>m4</c> file which is missing, so you probably want to
+package them in a tarball, and add it to <c>SRC_URI</c>. After making sure that the
+tarball is extracted somewhere in <c>${WORKDIR}</c> (say, in a <c>gentoo-m4</c>
+directory), you usually have two general ways to handle those macro files, one
+for packages which ships with an incomplete <c>m4</c> directory and one for
+packages which ships without the <c>m4</c> directory.
+</p>
+
+<p>
+In the first case you usually want to do something like:
+</p>
+
+<codesample lang="ebuild">
+einfo "Regenerating autotools files..."
+cp ${WORKDIR}/gentoo-m4 ${S}/m4 || die "m4 copy failed"
+WANT_AUTOCONF="2.5" aclocal -I ${S}/m4 || die "aclocal failed"
+WANT_AUTOCONF="2.5" autoconf || die "autoconf failed"
+</codesample>
+
+<p>
+and so on. In the second case you can simplify it in this way:
+</p>
+
+<codesample lang="ebuild">
+einfo "Regenerating autotools files..."
+WANT_AUTOCONF="2.5" aclocal -I ${WORKDIR}/gentoo-m4 || die "aclocal failed"
+WANT_AUTOCONF="2.5" autoconf || die "autoconf failed"
+</codesample>
+
+<p>
+without need to copy the files.
+</p>
+
+<p>
+It's always better inform upstream when the needed <c>m4</c> files are missing in
+the distribution, asking them to add all the needed files in the source tarball
+to avoid version conflicts if the macro changes.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Libtool</title>
+<body>
+
+<todo>
+Stuff about libtool, libtoolize, elibtoolize, libtool.eclass. Which I
+know almost nothing about... Yay!
+</todo>
+
+</body>
+</section>
+
+<section>
+<title>Further Autotools Reading</title>
+<body>
+
+<p>
+For more details on autotools:
+</p>
+
+<ul>
+  <li>
+    The book "GNU Autoconf, Automake and Libtool" by Gary V. Vaughan, Ben
+    Elliston, Tom Tromey  and Ian Lance Taylor   (often called "The Autobook")
+    provides a good but somewhat outdated description of autotools. It is
+    `freely available online &lt;http://sources.redhat.com/autobook/&gt;`_.
+  </li>
+  <li>
+    The GNU documentation for the various autotools components is of varying
+    quality and completeness:
+  </li>
+  <ul>
+    <li>
+      `GNU automake Manual
+      &lt;http://www.gnu.org/software/automake/manual/automake.html&gt;`_
+    </li>
+    <li>
+      `GNU autoconf Manual &lt;http://www.gnu.org/software/autoconf/manual/&gt;`_
+    </li>
+    <li>
+      `GNU libtool Manual &lt;http://www.gnu.org/software/libtool/manual.html&gt;`_
+    </li>
+    <li>
+      `GNU m4 Manual &lt;http://www.gnu.org/software/m4/manual/m4.html&gt;`_
+    </li>
+  </ul>
+  <li>
+    There are some good overview lectures available online. `These slides
+    &lt;http://vipe.technion.ac.il/~shlomif/lecture/Autotools/slides/&gt;`_ are one
+    example.
+  </li>
+</ul>
+
 </body>
 </section>
 
diff --git a/general-concepts/dependencies/text.xml b/general-concepts/dependencies/text.xml
index da5153d..3d5d074 100644
--- a/general-concepts/dependencies/text.xml
+++ b/general-concepts/dependencies/text.xml
@@ -99,7 +99,7 @@ DEPEND="dev-lang/ruby
 
 <p>
 Each atom is the full category and name of a package. Atoms are separated by
-arbitrary whitespace -- convention is to specify one atom per line for
+arbitrary whitespace <d/> convention is to specify one atom per line for
 readability purposes. When specifying names, the category part should be treated
 as mandatory.
 </p>
diff --git a/general-concepts/digest-and-manifest/text.xml b/general-concepts/digest-and-manifest/text.xml
index 541d622..952824d 100644
--- a/general-concepts/digest-and-manifest/text.xml
+++ b/general-concepts/digest-and-manifest/text.xml
@@ -31,7 +31,7 @@ will do this automatically if <c>cvs</c> is included in <c>FEATURES</c>.
 <p>
 To generate digests and <c>Manifest</c>, use <c>ebuild foo.ebuild digest</c>. When
 committing, the <c>Manifest</c> file must be regenerated to handle any CVS keyword
-expansion changes -- <c>repoman</c> will do this automatically.
+expansion changes <d/> <c>repoman</c> will do this automatically.
 </p>
 
 </body>
diff --git a/general-concepts/ebuild-revisions/text.xml b/general-concepts/ebuild-revisions/text.xml
index 51c109f..33b7de1 100644
--- a/general-concepts/ebuild-revisions/text.xml
+++ b/general-concepts/ebuild-revisions/text.xml
@@ -6,14 +6,14 @@
 <body>
 <p>
 Ebuilds may have a Gentoo revision number associated with them. This is a
-<c>-rX</c> suffix, where <c>X</c> is an integer -- see `File Naming Rules`_. This
+<c>-rX</c> suffix, where <c>X</c> is an integer <d/> see `File Naming Rules`_. This
 component must only be used for Gentoo changes, not upstream releases. By
 default, <c>-r0</c> is implied and should not be specified manually.
 </p>
 
 <p>
 Ebuilds should have their <c>-rX</c> incremented whenever a change is made which
-will make a substantial difference to what gets installed by the package -- by
+will make a substantial difference to what gets installed by the package <d/> by
 substantial, we generally mean "something for which many users would want to
 upgrade". This is usually for bugfixes.
 </p>
diff --git a/general-concepts/filesystem/text.xml b/general-concepts/filesystem/text.xml
index e2eac96..64f9ac4 100644
--- a/general-concepts/filesystem/text.xml
+++ b/general-concepts/filesystem/text.xml
@@ -58,7 +58,7 @@ which is not modified at runtime.
 </p>
 
 <p>
-Try to avoid installing unnecessary things into <c>/etc</c> -- every file in there
+Try to avoid installing unnecessary things into <c>/etc</c> <d/> every file in there
 is additional work for the system administrator. In particular, non-text files
 and files that are not intended for system administrator usage should be moved
 to <c>/usr/share</c>.
diff --git a/general-concepts/herds-and-projects/text.xml b/general-concepts/herds-and-projects/text.xml
index c6f9811..c4ff6d5 100644
--- a/general-concepts/herds-and-projects/text.xml
+++ b/general-concepts/herds-and-projects/text.xml
@@ -8,7 +8,7 @@
 <p>
 A <e>herd</e> is a collection of developers who maintain a collection of related
 packages. A herd has an associated email address which can be used for bugzilla
-assignments. This email address is <b>not</b> always <c>herdname@gentoo.org</c> -- for
+assignments. This email address is <b>not</b> always <c>herdname@gentoo.org</c> <d/> for
 example, because of the way Gentoo's email aliases are set up, the <c>cron</c> herd
 use <c>cron-bugs@gentoo.org</c> (aliases cannot match system usernames).
 </p>
@@ -19,7 +19,7 @@ may have herds associated with it.
 </p>
 
 <p>
-Sometimes herd and project names overlap -- for example, the <c>sparc</c> project
+Sometimes herd and project names overlap <d/> for example, the <c>sparc</c> project
 has an associated <c>sparc</c> herd which maintains sparc-specific packages (such
 as the <c>silo</c> bootloader). This is <e>not</e> always the case.
 </p>
diff --git a/general-concepts/install-destinations/text.xml b/general-concepts/install-destinations/text.xml
index ff51cdf..9e9fe43 100644
--- a/general-concepts/install-destinations/text.xml
+++ b/general-concepts/install-destinations/text.xml
@@ -8,13 +8,13 @@
 <p>
 When an ebuild runs the <c>src_install</c> phase, it installs an image of the
 package in question from <c>${S}</c> into <c>${D}</c>. Ebuilds must <e>not</e> attempt to
-perform any operation upon the live filesystem at this stage -- this will break
+perform any operation upon the live filesystem at this stage <d/> this will break
 binaries, and will (often) cause a sandbox violation notice.
 </p>
 
 <p>
 When installing, portage will install the image in <c>${D}</c> into <c>${ROOT}</c>. By
-default, <c>${ROOT}</c> points to <c>/</c>, although the user can alter this -- for
+default, <c>${ROOT}</c> points to <c>/</c>, although the user can alter this <d/> for
 example, the user may be building a minimal image for another system in a
 different location. If your package must operate on the live filesystem (for
 example, to create some cache files during <c>pkg_postinst</c>), you must ensure
diff --git a/general-concepts/mirrors/text.xml b/general-concepts/mirrors/text.xml
index 47051db..dbbd855 100644
--- a/general-concepts/mirrors/text.xml
+++ b/general-concepts/mirrors/text.xml
@@ -14,7 +14,7 @@ trying the original upstream location.
 </p>
 
 <p>
-This is generally desired behaviour -- upstream mirrors are prone to being
+This is generally desired behaviour <d/> upstream mirrors are prone to being
 rearranged, tidied out or having files modified.
 </p>
 </body>
@@ -33,7 +33,7 @@ certain files.
 
 <p>
 The <c>RESTRICT="primaryuri"</c> setting causes portage to try
-original locations <e>first</e>, and then fall back to mirrors if necessary -- this
+original locations <e>first</e>, and then fall back to mirrors if necessary <d/> this
 is sometimes useful if approximate download counts are needed, or if upstream
 have a reliable mirror setup.
 </p>
diff --git a/general-concepts/overlay/text.xml b/general-concepts/overlay/text.xml
index d3ae6a1..dcf79ad 100644
--- a/general-concepts/overlay/text.xml
+++ b/general-concepts/overlay/text.xml
@@ -42,7 +42,7 @@ Be very careful when using eclasses in an overlay. Portage will not do cache
 updates when an overlay eclass is changed, nor will it do cache updates when a
 main portage tree eclass which is used by an overlay ebuild changes. You may
 also encounter bogus 'illegal inherit' notices when working with eclasses in
-overlay (see `QA Notice -- ECLASS foo inherited illegally`_). To be safe,
+overlay (see `QA Notice <d/> ECLASS foo inherited illegally`_). To be safe,
 manually <c>touch</c> all relevant overlay files after updating overlay eclasses.
 </p>
 </body>
diff --git a/general-concepts/sandbox/text.xml b/general-concepts/sandbox/text.xml
index d474f26..216be0d 100644
--- a/general-concepts/sandbox/text.xml
+++ b/general-concepts/sandbox/text.xml
@@ -13,7 +13,7 @@ badly written build systems) accidentally writing outside of permitted locations
 
 <p>
 <b>All packages must build correctly when sandbox is active.</b> Packages must not
-achieve this by using sneaky tricks to make sandbox warnings not show up -- the
+achieve this by using sneaky tricks to make sandbox warnings not show up <d/> the
 sandbox is there to ensure that binary packages will work correctly, and that
 a badly written <c>Makefile</c> won't cause problems. Using <c>addwrite</c> is
 generally <b>not</b> the correct solution.
diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml
index 928f3fd..9625a1a 100644
--- a/general-concepts/slotting/text.xml
+++ b/general-concepts/slotting/text.xml
@@ -6,14 +6,14 @@
 <body>
 <p>
 Packages can support having multiple versions installed simultaneously. This is
-useful for libraries which may have changed interfaces between versions -- for
+useful for libraries which may have changed interfaces between versions <d/> for
 example, the <c>gtk+</c> package can install both versions <c>1.2</c> and <c>2.6</c> in
 parallel. This feature is called slotting.
 </p>
 
 <p>
 Most packages have no need for slotting. These packages specify <c>SLOT="0"</c> in
-the ebuilds. This is <b>not</b> the same as specifying an empty slot -- an empty
+the ebuilds. This is <b>not</b> the same as specifying an empty slot <d/> an empty
 slot means &quot;disable slotting entirely&quot;, and should not be used.
 </p>
 
@@ -43,7 +43,7 @@ It is not possible to <c>DEPEND</c> upon a package in a specific slot.
 Currently portage will accept an arbitrary string for the value of <c>SLOT</c>. For
 future compatibility, it is recommended that slots contain only characters which
 are allowed in an ebuild name or version (alphanumerics, hypens, full stops,
-underscores, the plus character) -- other characters may cause problems with
+underscores, the plus character) <d/> other characters may cause problems with
 future portage enhancements.
 </p>
 </body>
diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 34ec457..3904a4c 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -7,7 +7,7 @@
 <p>
 USE flags are to control optional dependencies and settings which the user may
 reasonably want to select. For example, vim can optionally build with support for
-the ruby interpreter, and it needs ruby installed to do this -- we use the ruby USE
+the ruby interpreter, and it needs ruby installed to do this <d/> we use the ruby USE
 flag to provide this option. On the other hand, glark requires ruby no matter what,
 so no USE flag is used here.
 </p>
@@ -47,7 +47,7 @@ RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )"
 </codesample>
 
 <p>
-Except this is pretty nasty -- what happens when an AMD64 binary is made as
+Except this is pretty nasty <d/> what happens when an AMD64 binary is made as
 well? Also, users on other archs will see fakemedia listed in <c>emerge -pv</c>
 output, even though it is not actually available.
 </p>
diff --git a/general-concepts/user-environment/text.xml b/general-concepts/user-environment/text.xml
index d96e62b..34f4055 100644
--- a/general-concepts/user-environment/text.xml
+++ b/general-concepts/user-environment/text.xml
@@ -6,7 +6,7 @@
 <body>
 <p>
 User environment variables and <c>make.conf</c> settings get passed on to ebuilds.
-This can be useful -- it's how <c>CFLAGS</c> and friends work, for example -- but
+This can be useful <d/> it's how <c>CFLAGS</c> and friends work, for example <d/> but
 it can also result in nasty build-breaking variables like <c>LANG</c> and
 <c>LC_ALL</c> getting through. Currently no sanitisation is performed upon the
 environment.
@@ -52,7 +52,7 @@ respected (selective filtering is fine, but outright ignoring is not). Ignoring
 <ul>
 <li>
   Ignoring <c>march/mcpu</c> may force kernel or software emulation for certain
-  opcodes on some architectures. This can be <e>very</e> slow -- for example,
+  opcodes on some architectures. This can be <e>very</e> slow <d/> for example,
   <c>openssl</c> built for SPARC v7 but run on v9 is around five times slower for
   RSA operations.
 </li>
diff --git a/quickstart/text.xml b/quickstart/text.xml
index 5eb5753..c3a6907 100644
--- a/quickstart/text.xml
+++ b/quickstart/text.xml
@@ -7,7 +7,7 @@
 <p>
 This page provides a <e>very</e> brief introduction to ebuild
 writing. It does not attempt to cover many of the details or problems
-that will be encountered by developers -- rather, it gives some
+that will be encountered by developers <d/> rather, it gives some
 trivial examples which may be of use when trying to grasp the basic
 idea of how ebuilds work.
 </p>
@@ -109,7 +109,7 @@ The <c>SRC_URI</c> tells Portage the address to use for downloading
 the source tarball. Here, <c>mirror://sourceforge/</c> is a special
 notation meaning &quot;any of the Sourceforge mirrors&quot;. The
 <c>${P}</c> is a read-only variable set by Portage which is the package's
-name and version -- in this case, it would be <c>ctags-5.5.4</c>.
+name and version <d/> in this case, it would be <c>ctags-5.5.4</c>.
 </p>
 
 <p>
@@ -119,7 +119,7 @@ you've not seen slots before, either just use <c>&quot;0&quot;</c> or read `Slot
 
 <p>
 The <c>KEYWORDS</c> variable is set to archs upon which this ebuild has been
-tested. We use <c>~</c> keywords for newly written ebuilds -- packages are not
+tested. We use <c>~</c> keywords for newly written ebuilds <d/> packages are not
 committed straight to stable, even if they seem to work. See `Keywording`_ for
 details.
 </p>
@@ -135,17 +135,17 @@ Next, a function named <c>src_compile</c>. Portage will call this
 function when it wants to <e>compile</e> the package. The <c>econf</c>
 function is a wrapper for calling <c>./configure</c>, and <c>emake</c>
 is a wrapper for <c>make</c>. In both cases, the common <c>|| die
-&quot;something went wrong&quot;</c> idiom is used -- this is to
+&quot;something went wrong&quot;</c> idiom is used <d/> this is to
 ensure that if for some reason an error occurs, portage will stop
 rather than trying to continue with the install.
 </p>
 
 <p>
 The <c>src_install</c> function is called by portage when it wants
-to <e>install</e> the package. A slight subtlety here -- rather than
+to <e>install</e> the package. A slight subtlety here <d/> rather than
 installing straight to the live filesystem, we must install to a
 special location which is given by the <c>${D}</c> variable (portage sets
-this -- see `Install Destinations`_ and `Sandbox`_).  Again, we check
+this <d/> see `Install Destinations`_ and `Sandbox`_).  Again, we check
 for errors.
 </p>
 
@@ -166,7 +166,7 @@ files into the relevant part of <c>/usr/share/doc</c>.
 Ebuilds can define other functions (see `Ebuild Functions`_). In all cases,
 portage provides a reasonable default implementation which quite often does the
 'right thing'. There was no need to define a <c>src_unpack</c> function here, for
-example -- this function is used to do any unpacking of tarballs or patching of
+example <d/> this function is used to do any unpacking of tarballs or patching of
 source files, but the default implementation does everything we need.
 </p>
 </body>
@@ -223,7 +223,7 @@ src_install() {
 Again, you can see the ebuild header and the various informational variables. In
 <c>SRC_URI</c>, <c>${PN}</c> is used to get the package's
 name <e>without</e> the version suffix (there are more of these
-variables -- see `Predefined Read-Only Variables`_).
+variables <d/> see `Predefined Read-Only Variables`_).
 </p>
 
 <p>
@@ -293,10 +293,10 @@ src_install() {
 </codesample>
 
 <p>
-Note the <c>${FILESDIR}/${P}-destdir.patch</c> -- this refers to
+Note the <c>${FILESDIR}/${P}-destdir.patch</c> <d/> this refers to
 <c>detox-1.1.0-destdir.patch</c>, which lives in the <c>files/</c>
 subdirectory in the portage tree. Larger patch files must go on the
-mirrors rather than in <c>files/</c> -- see `Basic epatch Usage`_.
+mirrors rather than in <c>files/</c> <d/> see `Basic epatch Usage`_.
 </p>
 
 </body>
@@ -427,7 +427,7 @@ src_install() {
 
 <p>
 Note the optional dependencies. Some of the <c>use_enable</c> lines use the
-two-argument version -- this is helpful when the USE flag name does not exactly
+two-argument version <d/> this is helpful when the USE flag name does not exactly
 match the <c>./configure</c> argument.
 </p>
 </body>