Some work on the documentation.

4 files changed, 307 insertions, 332 deletions

diff --git a/doc/Makefile b/doc/Makefile
index ec8f2cc3..8d406a01 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -12,7 +12,7 @@ clean:
 		-V %no-make-index% libgtop.sgml > /dev/null && \
 		touch .timestamp
 
-.timestamp2:	gnome-hackers.sgml
+.timestamp2:	gnome-hackers.sgml autoconf.sgml
 	-rm -rf gnome-hackers
 	mkdir gnome-hackers
 	-rm -f .timestamp2
diff --git a/doc/autoconf.sgml b/doc/autoconf.sgml
new file mode 100644
index 00000000..16bf1603
--- /dev/null
+++ b/doc/autoconf.sgml
@@ -0,0 +1,253 @@
+  <sect1 id="macros">
+    <title>Autoconf macros</title>
+
+    <para>
+      All you need to check for &libgtop; is in &gnome-libgtop-check.m4;,
+      just use <function>GNOME_INIT_LIBGTOP</function> with an optional
+      <parameter>fail</parameter> argument in the same way like
+      <function>GNOME_INIT</function>:
+
+      <example>
+	<title>Warn if &libgtop; cannot be found</title>
+
+	<programlisting>GNOME_INIT_LIBGTOP</programlisting>
+      </example>
+
+      <example>
+	<title>Abort if &libgtop; cannot be found</title>
+
+	<programlisting>GNOME_INIT_LIBGTOP(fail)</programlisting>
+      </example>
+
+    <para>
+      This will define a <function>HAVE_LIBGTOP</function> automake
+      conditional and everything from the configuration script of
+      &libgtop;.
+
+  <sect1 id="libgtopConf.sh">
+    <title>The configuration script of &libgtop; (&libgtopConf.sh;)</title>
+
+    <para>
+      After a successful build of &libgtop;, a &libgtopConf.sh; script
+      containing useful configuration variables is created.
+
+    <para>
+      It defines the following variables which you can use in your
+      <filename>Makefile.am</filename>:
+
+      <variablelist>
+	<varlistentry>
+	  <term><parameter>LIBGTOP_LIBDIR</parameter></term>
+	  <listitem>
+
+	    <para>
+	      The directory where the library files of &libgtop; are installed.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_INCLUDEDIR</parameter></term>
+	  <listitem>
+
+	    <para>
+	      The directory where the header files of &libgtop; are installed.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_LIBS</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Use this to link your program with &libgtop;.
+	      
+	<varlistentry>
+	  <term><parameter>LIBGTOP_INCS</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Use this to get the header files for &libgtop;.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_NAMES_LIBS</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Use this to link your program with &libgtop; and its
+	      names interface.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_NAMES_INCS</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Use this to get the header files for &libgtop; and the
+	      required <literal>-DGLIBTOP_NAMES</literal> to get its
+	      names interface.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_GUILE_LIBS</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Use this to link your program with &libgtop; and its
+	      guile interface. This will also include all the required
+	      guile libraries.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_GUILE_INCS</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Use this to get the header files for &libgtop; and guile
+	      and the required <literal>-DGLIBTOP_GUILE</literal> to get
+	      the guile interface of &libgtop;.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_GUILE_NAMES_LIBS</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Use this to link your program with &libgtop; and both its
+	      names and its guile interface. This will also include all the
+	      required guile libraries.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_GUILE_NAMES_INCS</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Use this to get the header files for &libgtop;, its guile
+	      and its names interface, the guile header files and the
+	      required <literal>-DGLIBTOP_GUILE</literal> and
+	      <literal>-DGLIBTOP_NAMES</literal>.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_BINDIR</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      The directory where the binaries of &libgtop; are installed.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_SERVER</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Full pathname of the &libgtop; server.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_MAJOR_VERSION</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Major version of &libgtop;.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_MINOR_VERSION</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Minor version of &libgtop;.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_VERSION</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Full version of &libgtop;.
+
+	<varlistentry>
+	  <term><parameter>LIBGTOP_SERVER_VERSION</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Version of the &libgtop; server. This is incremented each
+	      time the client/server protocol changes.
+
+	<varlistentry>
+	  <term><parameter>libgtop_sysdeps_dir</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      The sysdeps directory that is used on your system.
+
+	<varlistentry>
+	  <term><parameter>libgtop_need_server</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Either <literal>yes</literal> or <literal>no</literal>.
+
+	<varlistentry>
+	  <term><parameter>libgtop_use_machine_h</parameter></term>
+	  <listitem>
+
+	    <para>
+	      Either <literal>yes</literal> or <literal>no</literal>.
+	      Intended for <emphasis>internal use only</emphasis>
+	      and may be removed in future versions.
+
+	      <note>
+		<title>Note for &libgtop; hackers</title>
+
+		<para>
+		  This variable gets set in
+		  <filename>macros/gnome-libgtop-sysdeps.m4</filename>.
+
+		<para>
+		  If this is enabled, you need to put a
+		  <filename>glibtop_machine.h</filename> header file in the
+		  sysdeps directory which needs to define a structure of
+		  type <type>glibtop_machine</type>.
+
+		<para>
+		  This structure represents the
+		  <structfield>machine</structfield> field of
+		  <type>glibtop</type> defined in
+		  <filename>glibtop.h</filename>
+		  and can be used to store some
+		  machine dependent data.
+	      </note>
+
+	<varlistentry>
+	  <term><parameter>libgtop_guile_found</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Either <literal>yes</literal> or <literal>no</literal>.
+
+	<varlistentry>
+	  <term><parameter>libgtop_want_examples</parameter></term>
+	  <listitem>
+	    
+	    <para>
+	      Considered obsolete.
+
+      </variablelist>
+
+    <para>
+      All this variables are taken from the
+      &libgtopConf.sh; script which is created during
+      the installation of &libgtop;.
+
+      <example>
+	<title>
+	  Sample &libgtopConf.sh; (gnome and guile are installed in
+	  <filename>/home/baulig/INSTALL</filename> and &libgtop; in
+	  <filename>/home/norwegen/TEST</filename>)
+	</title>
+	
+	<programlisting>&example-libgtopConf-sh;</programlisting>
+      </example>
+
+  </sect1>
+  
+<!--
+  Local Variables:
+  mode: sgml
+  sgml-omittag:t
+  sgml-shorttag:t
+  sgml-minimize-attributes:nil
+  sgml-always-quote-attributes:t
+  sgml-indent-step:2
+  sgml-indent-data: t
+  sgml-parent-document: ("gnome-hackers.sgml" "book" "chapter" "")
+  End:
+ -->
diff --git a/doc/gnome-hackers.sgml b/doc/gnome-hackers.sgml
index 71fbfaff..3132b708 100644
--- a/doc/gnome-hackers.sgml
+++ b/doc/gnome-hackers.sgml
@@ -1,12 +1,16 @@
 <!-- $Id$ -->
 
 <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
-<!entity libgtopConf.sh SYSTEM "../libgtopConf.sh" >
+<!entity example-libgtopConf-sh SYSTEM "libgtopConf.sh">
+<!entity autoconf.sgml SYSTEM "autoconf.sgml">
 <!entity home-of-linux "http://www.home-of-linux.org/">
+<!entity gnome-libgtop-check.m4 "<filename>macros/gnome-libgtop-check.m4</filename>">
+<!entity libgtopConf.sh "<filename>libgtopConf.sh</filename>">
+<!entity libgtop "<productname>libgtop</productname>">
 ]>
 <book>
   <bookinfo>
-    <title>Using LibGTop in the Gnome Project</title>
+    <title>Using Libgtop in the Gnome Project</title>
     <authorgroup>
       <author>
 	<firstname>Martin</firstname>
@@ -22,7 +26,7 @@
       <year>1998</year>
       <holder>Martin Baulig</holder>
     </copyright>
-
+    
     <legalnotice>
 
       <para>
@@ -47,13 +51,15 @@
 
       <para>
 	For more details see the file COPYING in the source
-	distribution of LibGTop.</para>
+	distribution of &libgtop;.</para>
 
     </legalnotice>
 
     <abstract>
       <para>
-	<literal>$Id$</literal>
+	<literal>
+          $Id$
+        </literal>
 
       <para>
 	This is a short introduction in how to use
@@ -64,11 +70,6 @@
 
 	<note>
 	  <para>
-	    This document is currently out of date.
-	</note>
-
-	<note>
-	  <para>
 	    Documentation about the new <function>table ()</function>
 	    function can be found here:
 
@@ -86,329 +87,10 @@
 
   <toc></toc>
 
-  <chapter id="macros">
-    <title>Autoconf macros</title>
-
-    <sect1 id="gnome-libgtop-check">
-      <title><filename>macros/gnome-libgtop-check.m4</filename></title>
-
-      <para>
-	Contains all that you need to include libgtop in any Gnome application. It defines
-	<function>GNOME_INIT_LIBGTOP</function> which you can use in the same way like
-	<function>GNOME_INIT</function> to check whether libgtop is installed and to read
-	its <filename>libgtopConf.sh</filename> script. It automatically invokes
-	<function>GNOME_LIBGTOP_SYSDEPS</function>.
-
-      <para>
-	When libgtop can be found, it defines <parameter>HAVE_LIBGTOP</parameter>. There's
-	also an automake conditional <parameter>HAVE_LIBGTOP</parameter> which you can use.
-
-    <sect1 id="gnome-libgtop-sysdeps">
-      <title><filename>macros/gnome-libgtop-sysdeps.m4</filename></title>
-
-      <para>
-	This file defines <function>GNOME_LIBGTOP_SYSDEPS</function> which you can
-	use to check which sysdeps directory <productname>libgtop</productname> should
-	use and whether the <filename>gtop_server</filename> is needed.
-
-      <para>
-	It defines the following variables:
-	
-	<variablelist>
-	      
-	  <varlistentry>
-	    <term><parameter>libgtop_sysdeps_dir</parameter>
-		  
-	    <listitem>
-	      <para>
-		The sysdeps dir <productname>libgtop</productname> uses.
-		    
-	  <varlistentry>
-	    <term><parameter>libgtop_use_machine_h</parameter></term>
-
-	    <listitem>
-	      <para>
-		Some of the system dependent parts of <productname>libgtop</productname>
-		provide a structure <structname>_glibtop_machine</structname> defined in
-		a header file <filename>glibtop_machine.h</filename> they provide. This
-		structure gets inserted into the <structfield>machine</structfield> member
-		of <structname>_glibtop</structname> when <filename>config.h</filename>
-		defines <parameter>HAVE_GLIBTOP_MACHINE_H</parameter>.
-
-	      <para>
-		This variable is either <literal>yes</literal> or <literal>no</literal> and
-		tells you whether this is the case. If it is true, this macro wil automatically
-		define <parameter>HAVE_GLIBTOP_MACHINE_H</parameter>.
-
-	  <varlistentry>
-	    <term><parameter>libgtop_need_server</parameter></term>
-
-	    <listitem>
-	      <para>
-		Is either <literal>yes</literal> or <literal>no</literal> and tells you
-		whether the server is needed. If it is needed, it will automatically
-		define <parameter>NEED_LIBGTOP</parameter>.
-
-	      <para>
-		This macro also provides a conditional <parameter>NEED_LIBGTOP</parameter>
-		which you can use in you <filename>Makefile.am</filename>.
-
-	</variablelist>
-
-    </sect1>
-    
-  <chapter id="configure">
+  <chapter id="autoconf-automake">
     <title>Configuration</title>
 
-    <para>
-      The <filename>configure</filename> script of <productname>libgtop</productname>
-      takes some non-standard options to let you decide which parts of the library
-      should be build.
-
-      <itemizedlist>
-	<listitem>
-
-	  <para>
-	    Normally, <filename>configure</filename> decides whether or not using the
-	    server is required. Depending upon this decision, it adds either
-	    <literal>-lgtop</literal> (when it's needed) or
-	    <literal>-lgtop_systems</literal> (when it's not needed) to
-	    <parameter>LIBGTOP_LIBS</parameter> and <parameter>LIBGTOP_GUILE_LIBS</parameter>.
-
-	  <para>
-	    You can change this behaviour with the following options:
-
-	    <variablelist>
-	      
-	      <varlistentry>
-		<term><parameter>--enable-libgtop-server</parameter>
-		  
-		<listitem>
-		  <para>
-		    Use the server regardless whether or not it is required.
-		    
-	      <varlistentry>
-		<term><parameter>--disable-libgtop-server</parameter></term>
-		
-		<listitem>
-		  <para>
-		    Do not use the server regardless wheter or not it is required.
-		    
-	    </variablelist>
-
-	<listitem>
-
-	  <para>
-	    Normally, the guile interface of <productname>libgtop</productname> is build
-	    when <productname>guile</productname> can be found on the system.
-
-	    <variablelist>
-	      
-	      <varlistentry>
-		<term><parameter>--disable-libgtop-guile</parameter>
-		  
-		<listitem>
-		  <para>
-		    Disables building the guile interface even if you have
-		    <productname>guile</productname> installed.
-		    
-	      <varlistentry>
-		<term><parameter>--enable-libgtop-guile</parameter></term>
-		
-		<listitem>
-		  <para>
-		    Has no effect at all since you cannot build the guile interface without
-		    having <productname>guile</productname> installed on your system.
-		    
-	    </variablelist>
-
-	<listitem>
-
-	  <para>
-	    If you do not need the <filename>names</filename> subdirs, you can disable
-	    their building with the following option:
-
-	    <variablelist>
-	      
-	      <varlistentry>
-		<term><parameter>--disable-libgtop-names</parameter>
-		  
-		<listitem>
-		  <para>
-		    Disables building of the <filename>names</filename> subdirs.
-		    
-	      <varlistentry>
-		<term><parameter>--enable-libgtop-names</parameter></term>
-		
-		<listitem>
-		  <para>
-		    Is the default.
-		    
-	    </variablelist>
-
-	  <para>
-	    If it is enables, <parameter>GLIBTOP_NAMES</parameter> will be defined.
-
-	<listitem>
-
-	  <para>
-	    To disable building of the examples, you can say:
-
-	    <variablelist>
-	      
-	      <varlistentry>
-		<term><parameter>--without-examples</parameter>
-		  
-		<listitem>
-		  <para>
-		    Disables building of the examples.
-		    
-	    </variablelist>
-
-      </itemizedlist>
-    
-  <chapter id="libgtopConf">
-    <title>The <filename>libgtopConf.sh</filename> script</title>
-
-    <para>
-      After a successful build of <productname>libgtop</productname>, a
-      <filename>libgtopConf.sh</filename> script is generated which will later
-      be used to decide how to link a program with <filename>libgtop</filename>.
-
-    <para>
-      It defines the following variables:
-
-      <variablelist>
-	      
-	<varlistentry>
-	  <term><parameter>LIBGTOP_LIBDIR</parameter>
-		  
-	  <listitem>
-	    <para>
-	      Defaults to <literal>$(prefix)/lib</literal>. It is the directory
-	      where the <productname>libgtop</productname> libraries get installed.
-
-	<varlistentry>
-	  <term><parameter>LIBGTOP_INCLUDEDIR</parameter></term>
-		
-	  <listitem>
-	    <para>
-	      Defaults to <literal>$(prefix)/include</literal>. It is the directory
-	      where the <productname>libgtop</productname> header files get installed.
-
-	<varlistentry>
-	  <term><parameter>LIBGTOP_LIBS</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      Contains everything that you need to add to the <parameter>_LDADD</parameter>
-	      variable of <productname>automake</productname> to link a program with
-	      <productname>libgtop</productname>.
-
-	<varlistentry>
-	  <term><parameter>LIBGTOP_INCS</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      Contains everything that you need to add to the <parameter>_INCLUDES</parameter>
-	      variable of <productname>automake</productname> to compile a program that uses
-	      <productname>libgtop</productname>.
-
-	<varlistentry>
-	  <term><parameter>LIBGTOP_GUILE_INCS</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      Contains everything that you need to add to the <parameter>_INCLUDES</parameter>
-	      variable of <productname>automake</productname> to compile a program that uses both
-	      <productname>libgtop</productname> and its guile interface.
-
-	<varlistentry>
-	  <term><parameter>LIBGTOP_BINDIR</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      Defaults to <literal>$(bindir)</literal>. It is the directory where the
-	      <productname>libgtop</productname> binaries get installed.
-
-	<varlistentry>
-	  <term><parameter>LIBGTOP_SERVER</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      Defaults to <literal>$(bindir)/gtop_server</literal>. It is the full pathname
-	      where the server gets installed.
-
-	<varlistentry>
-	  <term><parameter>libgtop_sysdeps_dir</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      The sysdeps directory that is used on your system.
-
-	<varlistentry>
-	  <term><parameter>libgtop_need_server</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      Is either <literal>yes</literal> or <literal>no</literal> and tells you
-	      whether using the server is needed or not.
-
-	<varlistentry>
-	  <term><parameter>libgtop_use_machine_h</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      Is either <literal>yes</literal> or <literal>no</literal> and tells you
-	      whether <filename>glibtop_machine_h</filename> should be included in
-	      <filename>glibtop.h</filename>.
-
-	      The system dependent part of the library may provide an additional header
-	      file, <filename>glibtop_machine_h</filename>. In this case, they define
-	      a structure <structname>_glibtop_machine</structname> in this header file.
-	      This structure represents the <structfield>machine</structfield> member of
-	      <structname>_glibtop</structname>.
-
-	<varlistentry>
-	  <term><parameter>libgtop_guile_found</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      Is either <literal>yes</literal> or <literal>no</literal> and tells you
-	      whether <productname>guile</productname> has been found on your system
-	      (or if building the guile interface was disabled).
-
-	<varlistentry>
-	  <term><parameter>libgtop_want_names</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      Is either <literal>yes</literal> or <literal>no</literal> and tells you
-	      whether the <filename>sysdeps/names</filename> subdirectory was build.
-
-	<varlistentry>
-	  <term><parameter>libgtop_want_guile_names</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      Is either <literal>yes</literal> or <literal>no</literal> and tells you
-	      whether the <filename>sysdeps/guile/names</filename> subdirectory was build.
-
-	<varlistentry>
-	  <term><parameter>libgtop_want_examples</parameter></term>
-	  
-	  <listitem>
-	    <para>
-	      Is either <literal>yes</literal> or <literal>no</literal> and tells you
-	      whether the examples were build.
-
-      </variablelist>
-
-      <example>
-	<title>Sample <filename>libgtopConf.sh</filename></title>
-
-	<programlisting>&libgtopConf.sh;</programlisting>
-      </example>
+    &autoconf.sgml;
 
     
 </book>
@@ -416,6 +98,11 @@
 <!--
   Local Variables:
   mode: sgml
+  sgml-omittag:t
+  sgml-shorttag:t
+  sgml-minimize-attributes:nil
+  sgml-always-quote-attributes:t
+  sgml-indent-step:2
   sgml-indent-data: t
   End:
  -->
diff --git a/doc/libgtopConf.sh b/doc/libgtopConf.sh
new file mode 100644
index 00000000..0fc78273
--- /dev/null
+++ b/doc/libgtopConf.sh
@@ -0,0 +1,35 @@
+#
+# Configuration of the libgtop package
+#
+
+LIBGTOP_LIBDIR="/home/baulig/TEST/lib"
+LIBGTOP_INCLUDEDIR="/home/baulig/TEST/include"
+
+LIBGTOP_LIBS="-L/home/baulig/TEST/lib -lgtop -lgtop_common -lgtop_sysdeps -L/usr/X11R6/lib -lXau"
+LIBGTOP_INCS="-I/home/baulig/TEST/include"
+
+LIBGTOP_NAMES_LIBS="-L/home/baulig/TEST/lib -lgtop -lgtop_common -lgtop_sysdeps -lgtop_names -L/usr/X11R6/lib -lXau"
+LIBGTOP_NAMES_INCS="-I/home/baulig/TEST/include -DGLIBTOP_NAMES"
+
+LIBGTOP_GUILE_LIBS="-L/home/baulig/TEST/lib -lgtop -lgtop_guile -lgtop_common -lgtop_sysdeps -L/usr/X11R6/lib -lXau -L/home/baulig/INSTALL/lib -lguile -ldl -lreadline -ltermcap -lm"
+LIBGTOP_GUILE_INCS="-I/home/baulig/TEST/include -I/home/baulig/INSTALL/include -DGLIBTOP_GUILE"
+
+LIBGTOP_GUILE_NAMES_LIBS="-L/home/baulig/TEST/lib -lgtop -lgtop_guile -lgtop_common -lgtop_sysdeps -lgtop_names -L/usr/X11R6/lib -lXau"
+LIBGTOP_GUILE_NAMES_INCS="-I/home/baulig/TEST/include -I/home/baulig/INSTALL/include -DGLIBTOP_GUILE -DGLIBTOP_NAMES"
+
+LIBGTOP_BINDIR="/home/baulig/TEST/bin"
+LIBGTOP_SERVER="/home/baulig/TEST/bin/libgtop_server"
+
+LIBGTOP_MAJOR_VERSION="0"
+LIBGTOP_MINOR_VERSION="2a"
+LIBGTOP_VERSION="0.2a"
+
+LIBGTOP_SERVER_VERSION="1"
+
+libgtop_sysdeps_dir="linux"
+libgtop_need_server="no"
+libgtop_use_machine_h="no"
+
+libgtop_guile_found="yes"
+
+libgtop_want_examples=""