Make the User's Guide DocBook XML 4.2 conformant again

diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index 5f38b37..d82127d 100644 (file)
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -966,7 +966,7 @@ $ ghci -lm
           <literal>:continue</literal> 
           <indexterm><primary><literal>:continue</literal></primary></indexterm>
         </term>
           <literal>:continue</literal> 
           <indexterm><primary><literal>:continue</literal></primary></indexterm>
         </term>

-       <listitem> Shortcut to <literal>:breakpoint continue </literal>
+       <listitem><para>Shortcut to <literal>:breakpoint continue</literal></para>

        </listitem>
       </varlistentry>
 
        </listitem>
       </varlistentry>
 

@@ -1623,7 +1623,7 @@ Local bindings in scope:
 qsort2.hs:2:15-46>   
 </programlisting>
       What is happening here is that GHCi has interrupted the evaluation of 
 qsort2.hs:2:15-46>   
 </programlisting>
       What is happening here is that GHCi has interrupted the evaluation of 

-      <code>qsort</code> at the breakpoint set in line 2, as the prompt indicates.
+      <literal>qsort</literal> at the breakpoint set in line 2, as the prompt indicates.

       At this point you can freely explore the contents of the bindings in scope,
       but with two catches. </para><para>
       First, take into account that due to the lazy nature of Haskell, some of
       At this point you can freely explore the contents of the bindings in scope,
       but with two catches. </para><para>
       First, take into account that due to the lazy nature of Haskell, some of

@@ -1631,9 +1631,9 @@ qsort2.hs:2:15-46>
       trigger a computation. </para><para>
       Second: look at the types of the things in scope.
       GHCi has left its types parameterised by a variable!
       trigger a computation. </para><para>
       Second: look at the types of the things in scope.
       GHCi has left its types parameterised by a variable!

-      Look at the type of <code>qsort</code>, which is 
+      Look at the type of <literal>qsort</literal>, which is 

       polymorphic on the type of its argument. It does not 
       polymorphic on the type of its argument. It does not 

-      tell us really what the types of <code>x</code> and <code>xs</code> can be. 
+      tell us really what the types of <literal>x</literal> and <literal>xs</literal> can be. 

       In general, polymorphic programs deal with polymorphic values,
       and this means that some of the bindings available in a breakpoint site
       will be parametrically typed.
       In general, polymorphic programs deal with polymorphic values,
       and this means that some of the bindings available in a breakpoint site
       will be parametrically typed.

@@ -1644,11 +1644,11 @@ qsort2.hs:2:15-46>
       This is useful because you cannot just type <literal>x</literal> in the 
       prompt and expect GHCi to return you its value. Perhaps you know for 
       sure that 
       This is useful because you cannot just type <literal>x</literal> in the 
       prompt and expect GHCi to return you its value. Perhaps you know for 
       sure that 

-      <literal>x</literal> is of type <code>Int</code>, which is an instance of 
-      <code>Show</code>, but GHCi does not have this information. 
-      <code>:print</code> however is fine, because it does not need to know the 
+      <literal>x</literal> is of type <literal>Int</literal>, which is an instance of 
+      <literal>Show</literal>, but GHCi does not have this information. 
+      <literal>:print</literal> however is fine, because it does not need to know the 

       type to do its work. </para>
       type to do its work. </para>

-      <para> Let's go on with the debugging session of the <code>qsort</code>
+      <para> Let's go on with the debugging session of the <literal>qsort</literal>

       example:
 <example id="debuggingEx"><title>A short debugging session</title>
 <programlisting>
       example:
 <example id="debuggingEx"><title>A short debugging session</title>
 <programlisting>

@@ -1674,22 +1674,22 @@ x :: Int
          <para>GHCi reminds us that this value is untyped, and instructs us to force its evaluation </para>
        </callout>
        <callout arearefs="seq2">
          <para>GHCi reminds us that this value is untyped, and instructs us to force its evaluation </para>
        </callout>
        <callout arearefs="seq2">

-         <para>This line forces the evaluation of <code>x</code> </para>
+         <para>This line forces the evaluation of <literal>x</literal> </para>

        </callout>
        <callout arearefs="seq3">
          <para>Even though x has been evaluated, we cannot simply use its name to see its value! 
          This is a bit counterintuitive, but currently in GHCi the type of a binding
        </callout>
        <callout arearefs="seq3">
          <para>Even though x has been evaluated, we cannot simply use its name to see its value! 
          This is a bit counterintuitive, but currently in GHCi the type of a binding

-         cannot be a type variable <code>a</code>. 
-         Thus, the binding <code>x</code> gets assigned the concrete type Unknown.</para>
+         cannot be a type variable <literal>a</literal>. 
+         Thus, the binding <literal>x</literal> gets assigned the concrete type Unknown.</para>

        </callout>
        <callout arearefs="seq4">
        </callout>
        <callout arearefs="seq4">

-         <para>We can explore <code>x</code> using the <literal>:print</literal> 
-         command, which does find out that <code>x</code> is of type Int and prints
+         <para>We can explore <literal>x</literal> using the <literal>:print</literal> 
+         command, which does find out that <literal>x</literal> is of type Int and prints

          its value accordingly.</para>
        </callout>
        <callout arearefs="seq5">
          its value accordingly.</para>
        </callout>
        <callout arearefs="seq5">

-          <literal>:print</literal> also updates the type of <code>x</code> with
-          the most concrete type information available.
+          <para><literal>:print</literal> also updates the type of <literal>x</literal> with
+          the most concrete type information available.</para>

        </callout>
       </calloutlist>
       The example shows the standard way to proceeed with polymorphic values in a breakpoint. 
        </callout>
       </calloutlist>
       The example shows the standard way to proceeed with polymorphic values in a breakpoint. 

@@ -1784,7 +1784,7 @@ x :: Int
      <para>
       <itemizedlist>
        <listitem><para>
      <para>
       <itemizedlist>
        <listitem><para>

-         <xref linkend="implicit-parameters" xrefstyle="select: title"/> are only available 
+         Implicit parameters (see <xref linkend="implicit-parameters"/>) are only available 

          at the scope of a breakpoint if there is a explicit type signature.
        </para></listitem>
       </itemizedlist>
          at the scope of a breakpoint if there is a explicit type signature.
        </para></listitem>
       </itemizedlist>

@@ -1804,13 +1804,13 @@ x :: Int
            <programlisting>{-# OPTIONS_GHC -fdebugging #-}</programlisting>
          </listitem>
        </varlistentry>
            <programlisting>{-# OPTIONS_GHC -fdebugging #-}</programlisting>
          </listitem>
        </varlistentry>

-       <varlistentry> <term>* Repeated use of <code>seq</code> and 
+       <varlistentry> <term>* Repeated use of <literal>seq</literal> and 

            <literal>:print</literal> may be necessary to observe unevaluated
            untyped bindings</term> 
          <listitem><para>see <xref linkend="debuggingEx"/> 
          </para></listitem>
        </varlistentry>
            <literal>:print</literal> may be necessary to observe unevaluated
            untyped bindings</term> 
          <listitem><para>see <xref linkend="debuggingEx"/> 
          </para></listitem>
        </varlistentry>

-       <varlistentry> <term> * <code>GHC.Exts.unsafeCoerce</code> can help if you are positive about the type of a binding</term> 
+       <varlistentry> <term> * <literal>GHC.Exts.unsafeCoerce</literal> can help if you are positive about the type of a binding</term> 

          <listitem><para><programlisting>
 type MyLongType a = [Maybe [Maybe a]]
 
          <listitem><para><programlisting>
 type MyLongType a = [Maybe [Maybe a]]
 

@@ -1828,8 +1828,8 @@ Main.hs:15> x'
        <varlistentry> <term> * The undocumented (and unsupported) &colon;force command </term>
          <listitem><para> 
              equivalent to <literal> :print</literal> with automatic 
        <varlistentry> <term> * The undocumented (and unsupported) &colon;force command </term>
          <listitem><para> 
              equivalent to <literal> :print</literal> with automatic 

-             <code>seq</code> forcing, 
-             may prove useful to replace sequences of <code>seq</code> and 
+             <literal>seq</literal> forcing, 
+             may prove useful to replace sequences of <literal>seq</literal> and 

              <literal>&colon;print</literal> in some situations. 
          </para></listitem>
        </varlistentry> 
              <literal>&colon;print</literal> in some situations. 
          </para></listitem>
        </varlistentry> 

@@ -1975,7 +1975,7 @@ Main.hs:15> x'
        <term>I can't use Control-C to interrupt computations in
           GHCi on Windows.</term>
         <listitem>
        <term>I can't use Control-C to interrupt computations in
           GHCi on Windows.</term>
         <listitem>

-          <para>See <xref linkend="ghci-windows">.</xref></para>
+          <para>See <xref linkend="ghci-windows"/></para>

         </listitem>
       </varlistentry>
     </variablelist>
         </listitem>
       </varlistentry>
     </variablelist>

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 8bca485..e680d6c 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -1226,7 +1226,7 @@ that collection of packages in a uniform manner.  You can express
 quite a bit of object-oriented-like programming this way.
 </para>
 
 quite a bit of object-oriented-like programming this way.
 </para>
 

-<sect4 id="existential">
+<sect3 id="existential">

 <title>Why existential?
 </title>
 
 <title>Why existential?
 </title>
 

@@ -1249,9 +1249,9 @@ But Haskell programmers can safely think of the ordinary
 adding a new existential quantification construct.
 </para>
 
 adding a new existential quantification construct.
 </para>
 

-</sect4>
+</sect3>

 
 

-<sect4>
+<sect3>

 <title>Type classes</title>
 
 <para>
 <title>Type classes</title>
 
 <para>

@@ -1311,9 +1311,9 @@ Notice the way that the syntax fits smoothly with that used for
 universal quantification earlier.
 </para>
 
 universal quantification earlier.
 </para>
 

-</sect4>
+</sect3>

 
 

-<sect4 id="existential-records">
+<sect3 id="existential-records">

 <title>Record Constructors</title>
 
 <para>
 <title>Record Constructors</title>
 
 <para>

@@ -1376,10 +1376,10 @@ setTag obj t = obj{ tag = t }
 
 </para>
 
 
 </para>
 

-</sect4>
+</sect3>

 
 
 
 

-<sect4>
+<sect3>

 <title>Restrictions</title>
 
 <para>
 <title>Restrictions</title>
 
 <para>

@@ -1530,7 +1530,7 @@ declarations.  Define your own instances!
 
 </para>
 
 
 </para>
 

-</sect4>
+</sect3>

 </sect2>
 
 <!-- ====================== Generalised algebraic data types =======================  -->
 </sect2>
 
 <!-- ====================== Generalised algebraic data types =======================  -->

@@ -3492,7 +3492,6 @@ including an operational type class context, is legal:
 <itemizedlist>
 <listitem> <para> On the left or right (see <literal>f4</literal>, for example)
 of a function arrow </para> </listitem>
 <itemizedlist>
 <listitem> <para> On the left or right (see <literal>f4</literal>, for example)
 of a function arrow </para> </listitem>

-<listitem> <para> On the right of a function arrow (see <xref linkend="hoist"/>) </para> </listitem>

 <listitem> <para> As the argument of a constructor, or type of a field, in a data type declaration. For
 example, any of the <literal>f1,f2,f3,g1,g2</literal> above would be valid
 field type signatures.</para> </listitem>
 <listitem> <para> As the argument of a constructor, or type of a field, in a data type declaration. For
 example, any of the <literal>f1,f2,f3,g1,g2</literal> above would be valid
 field type signatures.</para> </listitem>

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index f6afa3c..72f53b7 100644 (file)
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -343,10 +343,11 @@ module X where
       <varlistentry>
        <term>
           <cmdsynopsis>
       <varlistentry>
        <term>
           <cmdsynopsis>

-          <command>ghc --version</command> <command>ghc -V</command> 
+            <command>ghc --version</command>
+            <command>ghc -V</command>
+          </cmdsynopsis>

           <indexterm><primary><option>-V</option></primary></indexterm>
           <indexterm><primary><option>&ndash;&ndash;version</option></primary></indexterm>
           <indexterm><primary><option>-V</option></primary></indexterm>
           <indexterm><primary><option>&ndash;&ndash;version</option></primary></indexterm>

-           </cmdsynopsis>

         </term>
        <listitem>
          <para>Print a one-line string including GHC's version number.</para>
         </term>
        <listitem>
          <para>Print a one-line string including GHC's version number.</para>

@@ -356,9 +357,9 @@ module X where
       <varlistentry>
        <term>
           <cmdsynopsis>
       <varlistentry>
        <term>
           <cmdsynopsis>

-          <command>ghc --numeric-version</command>
+            <command>ghc --numeric-version</command>
+          </cmdsynopsis>

           <indexterm><primary><option>&ndash;&ndash;numeric-version</option></primary></indexterm>
           <indexterm><primary><option>&ndash;&ndash;numeric-version</option></primary></indexterm>

-           </cmdsynopsis>

         </term>
        <listitem>
          <para>Print GHC's numeric version number only.</para>
         </term>
        <listitem>
          <para>Print GHC's numeric version number only.</para>

@@ -368,9 +369,9 @@ module X where
       <varlistentry>
        <term>
          <cmdsynopsis>
       <varlistentry>
        <term>
          <cmdsynopsis>

-          <command>ghc --print-libdir</command>
+            <command>ghc --print-libdir</command>
+          </cmdsynopsis>

           <indexterm><primary><option>&ndash;&ndash;print-libdir</option></primary></indexterm>
           <indexterm><primary><option>&ndash;&ndash;print-libdir</option></primary></indexterm>

-           </cmdsynopsis>

         </term>
        <listitem>
          <para>Print the path to GHC's library directory.  This is
         </term>
        <listitem>
          <para>Print the path to GHC's library directory.  This is

@@ -630,8 +631,8 @@ ghc -c Foo.hs</screen>
     <indexterm><primary>help options</primary></indexterm>
     <indexterm><primary>verbosity options</primary></indexterm>
 
     <indexterm><primary>help options</primary></indexterm>
     <indexterm><primary>verbosity options</primary></indexterm>
 

-    See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>,
-    and <option>--print-libdir</option> modes in <xref linkend="modes"/>.
+    <para>See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>,
+    and <option>--print-libdir</option> modes in <xref linkend="modes"/>.</para>

     <variablelist>
       <varlistentry>
        <term>
     <variablelist>
       <varlistentry>
        <term>