diff --git a/doc/xmlcatalog.1 b/doc/xmlcatalog.1
index cd91ec03..103d7f07 100644
--- a/doc/xmlcatalog.1
+++ b/doc/xmlcatalog.1
@@ -124,7 +124,8 @@ super catalog.
 .TP
 \fB\-\-shell\fR
 Run a shell allowing interactive queries on catalog file
-\fICATALOGFILE\fR.
+\fICATALOGFILE\fR. For the set of available commands see
+the section called \(lqSHELL COMMANDS\(rq.
 .TP
 \fB\-\-sgml\fR
 Uses
@@ -204,7 +205,22 @@ default catalog.
 .SH "DIAGNOSTICS"
 .PP
 \fBxmlcatalog\fR's return codes provide information that can be used when calling it from scripts.
-Errorcode: \fB0\fRError: No errorErrorcode: \fB1\fRError: Failed to remove an entry from the catalogErrorcode: \fB2\fRError: Failed to save to the catalog, check file permissionsErrorcode: \fB3\fRError: Failed to add an entry to the catalogErrorcode: \fB4\fRError: Failed to lookup and entry in the catalog.SH "SEE ALSO"
+.TP
+\fB0\fR
+No error
+.TP
+\fB1\fR
+Failed to remove an entry from the catalog
+.TP
+\fB2\fR
+Failed to save to the catalog, check file permissions
+.TP
+\fB3\fR
+Failed to add an entry to the catalog
+.TP
+\fB4\fR
+Failed to lookup an entry in the catalog
+.SH "SEE ALSO"
 .PP
 \fBlibxml\fR(3)
 .SH "AUTHOR"
diff --git a/doc/xmlcatalog_man.xml b/doc/xmlcatalog_man.xml
index ce9c2330..088cc233 100644
--- a/doc/xmlcatalog_man.xml
+++ b/doc/xmlcatalog_man.xml
@@ -232,7 +232,8 @@
 	<listitem>
 		<para>
 			Run a shell allowing interactive queries on catalog
-			file <replaceable>CATALOGFILE</replaceable>.
+			file <replaceable>CATALOGFILE</replaceable>. For the set of available
+			commands see <xref linkend="shell"/>.
 		</para>
 	</listitem>
 		</varlistentry>
@@ -393,31 +394,44 @@
 		&xmlcatalog;'s return codes provide information that can be used when
 		calling it from scripts.
 	</para>
-	<segmentedlist>
-		<!-- <title>Error codes</title> -->
-		<segtitle>Errorcode</segtitle>
-		<segtitle>Error</segtitle>
-		<seglistitem>
-			<seg><errorcode>0</errorcode></seg>
-			<seg>No error</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>1</errorcode></seg>
-			<seg>Failed to remove an entry from the catalog</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>2</errorcode></seg>
-			<seg>Failed to save to the catalog, check file permissions</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>3</errorcode></seg>
-			<seg>Failed to add an entry to the catalog</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>4</errorcode></seg>
-			<seg>Failed to lookup and entry in the catalog</seg>
-		</seglistitem>
-	</segmentedlist>
+	<variablelist>
+
+		<varlistentry>
+	<term><errorcode>0</errorcode></term>
+	<listitem>
+		<para>No error</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>1</errorcode></term>
+	<listitem>
+		<para>Failed to remove an entry from the catalog</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>2</errorcode></term>
+	<listitem>
+		<para>Failed to save to the catalog, check file permissions</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>3</errorcode></term>
+	<listitem>
+		<para>Failed to add an entry to the catalog</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>4</errorcode></term>
+	<listitem>
+		<para>Failed to lookup an entry in the catalog</para>
+	</listitem>
+		</varlistentry>
+
+	</variablelist>
 </refsect1>
 
 <refsect1 id="seealso">
diff --git a/doc/xmllint.1 b/doc/xmllint.1
index 84eb10d5..13e38f53 100644
--- a/doc/xmllint.1
+++ b/doc/xmllint.1
@@ -364,7 +364,42 @@ to be written ...
 On the completion of execution,
 \fBxmllint\fR
 returns the following error codes:
-Errorcode: \fB0\fRError: No errorErrorcode: \fB1\fRError: UnclassifiedErrorcode: \fB2\fRError: Error in DTDErrorcode: \fB3\fRError: Validation errorErrorcode: \fB4\fRError: Validation errorErrorcode: \fB5\fRError: Error in schema compilationErrorcode: \fB6\fRError: Error writing outputErrorcode: \fB7\fRError: Error in pattern (generated when \fB\-\-pattern\fR option is used)Errorcode: \fB8\fRError: Error in reader registration (generated when \fB\-\-chkregister\fR option is used)Errorcode: \fB9\fRError: Out of memory.SH "SEE ALSO"
+.TP
+\fB0\fR
+No error
+.TP
+\fB1\fR
+Unclassified
+.TP
+\fB2\fR
+Error in
+DTD
+.TP
+\fB3\fR
+Validation error
+.TP
+\fB4\fR
+Validation error
+.TP
+\fB5\fR
+Error in schema compilation
+.TP
+\fB6\fR
+Error writing output
+.TP
+\fB7\fR
+Error in pattern (generated when
+\fB\-\-pattern\fR
+option is used)
+.TP
+\fB8\fR
+Error in Reader registration (generated when
+\fB\-\-chkregister\fR
+option is used)
+.TP
+\fB9\fR
+Out of memory error
+.SH "SEE ALSO"
 .PP
 \fBlibxml\fR(3)
 .SH "AUTHOR"
diff --git a/doc/xmllint.xml b/doc/xmllint.xml
index a899bb37..904e706a 100644
--- a/doc/xmllint.xml
+++ b/doc/xmllint.xml
@@ -813,51 +813,86 @@
 	<para>
 		On the completion of execution, &xmllint; returns the following error codes:
 	</para>
-	<segmentedlist>
-		<!-- <title>Error codes</title> -->
-		<segtitle>Errorcode</segtitle>
-		<segtitle>Error</segtitle>
-		<seglistitem>
-			<seg><errorcode>0</errorcode></seg>
-			<seg>No error</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>1</errorcode></seg>
-			<seg>Unclassified</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>2</errorcode></seg>
-			<seg>Error in DTD</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>3</errorcode></seg>
-			<seg>Validation error</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>4</errorcode></seg>
-			<seg>Validation error</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>5</errorcode></seg>
-			<seg>Error in schema compilation</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>6</errorcode></seg>
-			<seg>Error writing output</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>7</errorcode></seg>
-			<seg>Error in pattern (generated when <option>--pattern</option> option is used)</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>8</errorcode></seg>
-			<seg>Error in reader registration (generated when <option>--chkregister</option> option is used)</seg>
-		</seglistitem>
-		<seglistitem>
-			<seg><errorcode>9</errorcode></seg>
-			<seg>Out of memory</seg>
-		</seglistitem>
-	</segmentedlist>
+	<!-- better use segmentedlist element later,
+	     which is currently only supported in snapshots -->
+	<variablelist>
+
+		<varlistentry>
+	<term><errorcode>0</errorcode></term>
+	<listitem>
+		<para>No error</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>1</errorcode></term>
+	<listitem>
+		<para>Unclassified</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>2</errorcode></term>
+	<listitem>
+		<para>Error in <acronym>DTD</acronym></para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>3</errorcode></term>
+	<listitem>
+		<para>Validation error</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>4</errorcode></term>
+	<listitem>
+		<para>Validation error</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>5</errorcode></term>
+	<listitem>
+		<para>Error in schema compilation</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>6</errorcode></term>
+	<listitem>
+		<para>Error writing output</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>7</errorcode></term>
+	<listitem>
+		<para>
+			Error in pattern (generated when <option>--pattern</option> option is used)
+		</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>8</errorcode></term>
+	<listitem>
+		<para>
+			Error in Reader registration (generated
+			when <option>--chkregister</option> option is used)
+		</para>
+	</listitem>
+		</varlistentry>
+
+		<varlistentry>
+	<term><errorcode>9</errorcode></term>
+	<listitem>
+		<para>Out of memory error</para>
+	</listitem>
+		</varlistentry>
+
+	</variablelist>
 </refsect1>
 
 <refsect1 id="seealso">