Docs patches

diff -u orig/user-basics.sgml ./user-basics.sgml
--- orig/user-basics.sgml	Thu Aug 28 21:01:56 2003
+++ ./user-basics.sgml	Thu Aug 28 22:54:55 2003
@@ -431,3 +432,53 @@
     %
 </literallayout>
 </para>
+
+
+<bridgehead>Line Syntax</bridgehead>
+
+<para>
+&Aap; parses the recipe into a sequence of lines.
+A line is a sequence of characters terminated by a newline.
+You can escape the newline with a backslash to continue
+a logical line over more than one physical line,
+as follows:
+<programlisting>
+1   One line
+2   A longer line \
+3   that continues \
+4   over three physical lines.
+</programlisting>
+You can always use backslash continuations to continue
+lines in &Aap;. Indentation does not matter.
+</para>
+
+<para>
+In many constructions, &Aap; also supports Python-style
+line continuations, where a line is continued by
+increasing the indentation of subsequent physical lines.
+The above example would look different with
+Python-style continuation:
+<programlisting>
+1   One line
+2   A longer line
+3       that continues
+4       over three physical lines.
+</programlisting>
+As you can see, the &quot;block&quot; of lines
+with an increased amount of indentation is considered
+to belong to the line above it.
+</para>
+
+<para>
+Python-style line continuations are supported
+in all &Aap; constructions except the following:
+in <emphasis>build commands</emphasis> like
+<link linkend="cmd-program">:program</link>
+between the command and the colon <literal>:</literal>
+following the target name
+and
+in <emphasis><link linkend="cmd-route">:route</link></emphasis>
+because the line break is used to introduce the list
+of actions.
+</para>
+

diff -u orig/user-basics.sgml ./user-basics.sgml
--- orig/user-basics.sgml	Thu Aug 28 21:01:56 2003
+++ ./user-basics.sgml	Thu Aug 28 22:54:55 2003
@@ -264,7 +264,7 @@
 and sets variables for choices.  Separate recipes are used to handle specific
 tasks.  For example, you can move related sources to a sub-directory and put a
 recipe in that directory to build those sources.  For this situation you use
-the <literal>:child</literal> command.
+the <link linkend="cmd-child">:child</link> command.
 </para>
 <para>
 When a project gets bigger, and especially when working together with several
@@ -292,15 +292,16 @@
 Read the startup recipes, these define default rules and variables.  These
 recipes are used:
 <simplelist>
-   <member> "default.aap" from the distribution </member>
-   <member> all recipes matching "/usr/local/share/aap/startup/*.aap"
+   <member> <filename>default.aap</filename> from the distribution </member>
+   <member> all recipes matching
+       <filename>/usr/local/share/aap/startup/<replaceable>*</replaceable>.aap</filename>
    </member>
-   <member> all recipes matching "~/.aap/startup/*.aap" </member>
+   <member> all recipes matching <filename>~/.aap/startup/<replaceable>*</replaceable>.aap</filename> </member>
 </simplelist>
 </para></listitem>
 
 <listitem><para>
-Recipe processing: Read the recipe "main.aap" or the one specified with the
+Recipe processing: Read the recipe <filename>main.aap</filename> or the one specified with the
 "-f" argument and check for obvious errors.
 Then execute the toplevel items in the recipe.  Dependencies and rules are
 stored.  Also read included and child recipes and execute the toplevel items

diff -u orig/user-depend.sgml ./user-depend.sgml
--- orig/user-depend.sgml	Thu Aug 28 21:01:56 2003
+++ ./user-depend.sgml	Thu Aug 28 23:59:46 2003
@@ -61,7 +61,149 @@
 anything.
 </para>
 
-<bridgehead>
+<bridgehead>The Production Commands</bridgehead>
+<anchor id="user-produce"/><!--/-->
+
+<para>
+The commands
+<link linkend="ref-program">:program</link>,
+<link linkend="ref-lib">:lib</link>,
+<link linkend="ref-dll">:dll</link>
+and
+<link linkend="ref-ltlib">:ltlib</link>
+are called <emphasis>production commands</emphasis>
+because they explicitly state what things &Aap; should
+produce and what
+sources are involved.
+Everything the production commands can do,
+can be done by hand with dependencies as well,
+but the automation the production commands provide
+is quite useful.
+This section discusses how the production commands can
+be used and the variables that affect them.
+</para>
+
+<para>
+The form of each of the production commands is
+<literal>:<replaceable>command</replaceable>
+<replaceable>targets</replaceable> :
+<replaceable>sources</replaceable></literal>.
+It is unusual to have more than one target,
+since both targets would be built from the
+same sources,
+but it is allowed.
+The list of sources should list the actual, original
+sources, i.e.&nbsp;only files that are actually written
+by the programmer and that exist on disk.
+It is these sources that will be packaged together
+for distributing the program or library in source form.
+</para>
+
+<para>
+Each production command transforms all of the
+sources into objects using <!-- how to markup? -->compile
+actions. The sources are transformed into object
+files of a particular type &mdash;
+e.g.&nbsp;libraries use libobject file.
+Once all of the sources have been compiled,
+a build action is invoked to turn the collected objects
+into the target.
+The table below lists the production commands
+and the actions used.
+</para>
+
+<para>
+Some of the production commands can use different
+programs to produce the final product, depending on
+settings in the recipe.
+In particular, you may need to chose to
+link a program with the compiler or
+through libtool, depending on whether your program
+links to any libtool libraries or not.
+The variants are listed in the table below as well.
+To select a variant form to build the final product,
+set the filetype of the target to a specific value,
+e.g.&nbsp;
+<programlisting>
+    :program myProgram { filetype=ltprogram } : source.c
+</programlisting>
+This example uses the <literal>ltprogram</literal>
+variant build command to build the program "myProgram."
+</para>
+
+<informaltable frame="none">
+<!-- title>Actions and Variables for Production Commands</title -->
+<tgroup cols="4">
+  <thead>
+  <row>
+    <entry>Command</entry>
+    <entry>Object Type</entry>
+    <entry>Build Command</entry>
+    <entry>Build Variants</entry>
+  </row>
+  </thead>
+  <tbody>
+  <row>
+    <entry>:program</entry>
+    <entry>object</entry>
+    <entry>build</entry>
+    <entry>
+    <variablelist>
+    <varlistentry><term>(normal)</term>
+      <listitem><para>Uses the C compiler to link all the
+      objects into a program. Uses $LIBS and $LDFLAGS.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry><term><literal>ltprogram</literal></term>
+      <listitem><para>
+      Uses libtool to link all the objects into a program.
+      Uses $LIBS and $LDFLAGS, but also adds
+      $LTLIBS and $LT_RPATH if defined.
+      </para>
+      </listitem>
+    </varlistentry>
+    </variablelist>
+    </entry>
+  </row>
+  <row>
+    <entry>:lib</entry>
+    <entry>libobject</entry>
+    <entry>buildlib</entry>
+    <entry>
+    (normal) Uses the <command>ar</command> utility
+    to link all the
+    objects into a static library.
+    Uses $ARFLAGS.
+    </entry>
+  </row>
+  <row>
+    <entry>:dll</entry>
+    <entry>dllobject</entry>
+    <entry>builddll</entry>
+    <entry>
+    (normal) Uses the C compiler to link the
+    objects into a dynamic (shared) library.
+    The object files are different from regular
+    library objects, and use a different extension.
+    Uses $SHLINK, and $LDFLAGS, as well as
+    $SHLINKFLAGS.
+    </entry>
+  </row>
+  <row>
+    <entry>:ltlib</entry>
+    <entry>ltlibobject</entry>
+    <entry>buildltlib</entry>
+    <entry>(normal)
+    Uses the <command>libtool</command> utility
+    to link the objects together.
+    Uses $LDFLAGS.
+    <!-- default.aap contains a partly wrong invocation.
+         Needs to use LTLIBS and LIBS as well. -->
+    </entry>
+  </row>
+  </tbody>
+</tgroup>
+</informaltable>
 
 <bridgehead>Rules And Dependencies</bridgehead>