Converting documentation to DocBook

doc/configure.sgml

@@ -1,91 +1,98 @@
-configure documentation
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
------------------------
+<article>
-
+<artheader>
-
+<title>configure documentation</title>
+<author><firstname>Pierre</firstname><surname>Pronchery</surname></author>
+</artheader>
+<para>
 These are the documentation notes for configure. The configure project is a
 Makefiles generator. It uses project description files to propose simple
 Makefiles. It is intended to keep generated code as simple as possible.
-
+</para>
-                    ----------------------------------------
+<section>
-
+<title>Overview</title>
-
+<section>
-Table of contents
+<title>What is configure</title>
------------------
+<para>
-
-I. Overview of configure
-1.1 What is configure
-1.2 Who should use configure
-1.3 Who should not use configure
-1.4 Why use configure
-
-II. Using configure
-2.1 configure usage
-2.2 Project configuration
-2.3 Targets definition
-2.4 Migrating to configure
-
-III. Getting further
-3.1 Current caveats
-3.2 Planned improvements
-
-                    ----------------------------------------
-
-
-I. Overview of configure
-
-1.1 What is configure
 configure generates Makefiles needed in an entire project. Instead of trying
 every little trick to let it work in a number of potential uses, it sticks to
 the simplest possible code generation. Consequently, it will mostly be useful
 for projects running on UNIX platforms first.
-
+</para>
-1.2 Who should use configure
+</section>
+<section>
+<title>Who should use configure</title>
+<para>
 Every software developer could gain using configure. However, due to its
 intentional simplicity, it may not be appropriate to use along with code
 compilation on some non-portable platforms.
+</para>
+<para>
 Of course an advanced user, trying to modify a given project Makefile on his
 platform, inside a project using configure may have to use configure too.
-
+</para>
-1.3 Who should not use configure
+</section>
+<section>
+<title>Who should not use configure</title>
+<para>
 configure will certainly not be appropriate alone for cross-plaform projects,
 and maybe not for big projects. However one should be able to keep its
 configuration files inside a project without creating any trouble for potential
 other Makefile files generators.
-
+</para>
-1.4 Why use configure
+</section>
+<section>
+<title>Why use configure</title>
+<para>
 configure has been created to be efficient at writing simple and compliant
 Makefiles for small to big software development projects. It should be useful:
-- for people learning software development using Makefiles;
+<itemizedlist>
-- for developers of some small to big projects;
+<listitem><para>for people learning software development using Makefiles;</para></listitem>
-- for developers concerned by the readability and efficiency of their
+<listitem><para>for developers of some small to big projects;</para></listitem>
-  Makefiles.
+<listitem><para>for developers concerned by the readability and efficiency of their Makefiles.</para></listitem>
-
+</itemizedlist>
-                    ----------------------------------------
+</para>
-
+</section>
-
+</section>
-II. Using configure
+<section>
-
+<title>Using configure</title>
-2.1 configure usage
+<section>
+<title>configure usage</title>
+<para>
 The configure utility may be invoked from the command line this way:
+<computeroutput>
 $ configure [-nv][directory]
-
+</computeroutput>
+</para>
+<para>
 The "-n" option just parses the project definition files, without actually
 re-generating the Makefiles.
+</para>
+<para>
 The "-v" option gives information about the progress of the operation.
-
+</para>
+<para>
 It then processes the current directory, or one given at the command line,
 according to the project configuration files.
-
+</para>
-2.2 Project configuration
+</section>
+<section>
+<title>Project configuration</title>
+<para>
 This file should be found in every project directory. It must be named
 "project.conf". It is organized in sections, and string variables. Section names
 are written on their own line, between brackets (eg "[section]"). Variables are
 given on their own line too, like this:
+<computeroutput>
 variable=value
+</computeroutput>
 Configuration files may be commented, comment lines being prepended with a
 hash sign "#".
+</para>
+<para>
 The significant variables are the following:
-- in the default section (has an empty name, eg "[]" in the file)
+<itemizedlist>
+<listitem><para>in the default section (has an empty name, eg "[]" in the file)
   * subdirs: subdirectories to look for too
   * cflags_force: CFLAGS to force globally
   * cflags: optional global CFLAGS
@@ -97,37 +104,50 @@ The significant variables are the following:
   * type (mandatory): type of the target (eg "binary", "library", "object", ...)
   * cflags: additional CFLAGS for this target
   * ldflags: additional LDFLAGS for this target
-  * sources: source files to compile
+  * sources: source files to compile</para></listitem>
-
+</itemizedlist>
-2.3 Targets definitions
+</para>
+</section>
+<section>
+<title>Targets definitions</title>
+<para>
 The following target types are currently supported:
-- "binary": produces binary files, linked from every object file produced with
+<itemizedlist>
-  their source files.
+<listitem><para>"binary": produces binary files, linked from every object file produced with their source files.</para></listitem>
-- "library": produces a static and a shared version of the target, linked from
+<listitem><para>"library": produces a static and a shared version of the target, linked from every object file produced with their source files, and respectively appending ".a" and ".so" extensions to the target name.</para></listitem>
-  every object file produced with their source files, and respectively appending
+<listitem><para>"object": produces a binary object file from the given source.</para></listitem>
-  ".a" and ".so" extensions to the target name.
+</itemizedlist>
-- "object": produces a binary object file from the given source.
+</para>
-
+</section>
-2.4 Migrating to configure
+<section>
+<title>Migrating to configure</title>
+<para>
 You may first create all necessary "project.conf" files with the subdirectories
 definitions. Then for every binary or library built, specify the adequate target
 along with its section.
+</para>
+<para>
 When migrating from automake/autoconf, the existing subdirectories are defined
 in the "Makefile.am" files, in the "SUBDIRS" variable. The binary targets are
 defined in the same file, as the "bin_PROGRAMS" variable, each declined to
 "program_SOURCES" for their respective source files.
-
+</para>
-                    ----------------------------------------
+</section>
-
+</section>
-
+<section>
-III. Getting further
+<title>Getting further</title>
-
+<section>
-3.1 Current caveats
+<title>Current caveats</title>
-- configure is not user-proof when necessary development files are not available
+<itemizedlist>
-  (relies on appropriate third-party programs error messages, eg
+<listitem><para>configure is not user-proof when necessary development files are not available (relies on appropriate third-party programs error messages, eg "project-config" or "pkgconfig")</para></listitem>
-  "project-config" or "pkgconfig")
+</itemizedlist>
-
+</section>
-3.2 Planned improvements
+<section>
-- run-time system detection or selection;
+<title>Planned improvements</title>
-- generation of the Makefiles altered acordingly;
+<itemizedlist>
-- tweakable installation path.
+<listitem><para>run-time system detection or selection;</para></listitem>
+<listitem><para>generation of the Makefiles altered acordingly;</para></listitem>
+<listitem><para>tweakable installation path.</para></listitem>
+</itemizedlist>
+</section>
+</section>