Various low-hanging documentation updates.

ChangeLog

@@ -1,3 +1,16 @@
+Thu May 6 23:23:10 BST 2004 Scott James Remnant <scott@netsplit.com>
+
+  * utils/md5sum.1, man/es/md5sum.1, man/de/md5sum.1, men/ja/md5sum.1:
+  Correct "et al" to "et al."
+  * main/main.c, man/en/dpkg.8.sgml: Correct description of
+  --compare-versions command to describe versions as "empty" rather
+  than "missing" or "no version" as "" has to be passed.
+  * man/en/dpkg.8.sgml: Add dpkg-reconfigure(8) to SEE ALSO section.
+  * utils/start-stop-daemon.8: Move documentation of --retry to the
+  paragraph about --stop where it belongs.
+  * scripts/update-alternatives.8: Remove strange &quot; usage and
+  replace with appropriate .BR.
+
 Sun May  2 10:22:25 CEST 2004 Tollef Fog Heen <tfheen@debian.org>
 
   * scripts/dpkg-scanpackages.pl: Give proper case for Origin and

debian/changelog

@@ -2,14 +2,21 @@ dpkg (1.10.22) unstable; urgency=low
 
   * Add amd64 support. Closes: #238483, #241938.
   * Add i?86-gnu support.  Closes: #216695, #236331.
-  * Stop hardcoding the list of manual page languages in debian/rules,
-    so we include Spanish, Russian and Brazilian Portugese.  Closes: #245994.
-  * Correct dpkg manpage to refer to --force-remove-reinstreq instead of
-    non-existant --force-reinstreq option.  Closes: #232831.
   * Fix dpkg-source (actually controllib.pl) to output the field name
     properly again.  Closes: #246595.
   * Make dpkg-scanpackages output Origin and Bugs fields with proper
     casing.  Closes: #154422.
+  * Stop hardcoding the list of manual page languages in debian/rules,
+    so we include Spanish, Russian and Brazilian Portugese.  Closes: #245994.
+  * Correct dpkg manpage to refer to --force-remove-reinstreq instead of
+    non-existant --force-reinstreq option.  Closes: #232831.
+  * Correct usage of "et al" to "et al.".  Closes: #230751.
+  * Correct documentation of --compare-versions arguments.  Closes: #232317.
+  * Correct documentation of start-stop-daemon manpage to refer to --retry
+    alongside --stop.  Closes: #204691.
+  * Correct invalid use of " within update-alternatives(8) with .BR.
+    Closes: #244624.
+  * Add dpkg-reconfigure(8) to SEE ALSO section of dpkg(8).  Closes: #233282.
   * Updated Translations:
     - Catalan (Jordi Mallach).
     - Spanish manpages (Ruben Porras).  Closes: #246158, #246159, #246160,

main/main.c

@@ -107,8 +107,8 @@ Options:\n\
   --abort-after <n>              Abort after encountering <n> errors\n\
 \n\
 Comparison operators for --compare-versions are:\n\
- lt le eq ne ge gt       (treat no version as earlier than any version);\n\
- lt-nl le-nl ge-nl gt-nl (treat no version as later than any version);\n\
+ lt le eq ne ge gt       (treat empty version as earlier than any version);\n\
+ lt-nl le-nl ge-nl gt-nl (treat empty version as later than any version);\n\
  < << <= = >= >> >       (only for compatibility with control file syntax).\n\
 \n\
 Use `dselect' for user-friendly package management.\n"),

man/de/md5sum.1

@@ -1,6 +1,6 @@
 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
 .hw ge-knackt
-.TH MD5SUM 1 "29. November 1995" "Lankester et al" "Debian GNU/Linux"
+.TH MD5SUM 1 "29. November 1995" "Lankester et al." "Debian GNU/Linux"
 .SH NAME
 md5sum \- generiert oder überprüft MD5-Prüfsummen
 

man/en/dpkg.8.sgml

@@ -10,7 +10,7 @@
 
   <refnamediv>
     <refname>dpkg</refname>
-    <refpurpose>medium-level package manager for Debian</refpurpose>
+    <refpurpose>a medium-level package manager for Debian</refpurpose>
   </refnamediv>
 
 
@@ -37,11 +37,6 @@
       packages. The descriptions of what <command>dpkg</command> does when
       installing and removing packages are particularly inadequate.
     </para>
-
-    <para>
-      For information about this, please refer to sections regarding the
-      Debian packaging system in the Debian FAQ or in the Debian Reference.
-    </para>
   </refsect1>
 
 
@@ -50,7 +45,10 @@
 
     <para>
       <command>dpkg</command> is a medium-level tool to install, build, remove
-      and manage Debian packages. <command>dpkg</command>
+      and manage Debian packages. The primary and more user-friendly front-end
+      for <command>dpkg</command> is <command>dselect</command> (see
+      <citerefentry><refentrytitle>dselect</refentrytitle>
+      <manvolnum>8</manvolnum></citerefentry>). <command>dpkg</command> itself
       is controlled entirely via command line parameters, which consist of
       exactly one action and zero or more options. The action-parameter tells
       <command>dpkg</command> what to do and options control the behavior of
@@ -82,17 +80,6 @@
       <manvolnum>1</manvolnum> </citerefentry> for information about these
       actions.
     </para>
-
-    <note>
-      <para>
-	The primary and more user-friendly front-end for
-	<command>dpkg</command> is <command>dselect</command> (see
-	<citerefentry><refentrytitle>dselect</refentrytitle>
-	<manvolnum>8</manvolnum></citerefentry>). There are other front-ends
-	such as those based on <citerefentry><refentrytitle>apt</refentrytitle>
-	<manvolnum>8</manvolnum></citerefentry>.
-      </para>
-    </note>
   </refsect1>
 
   <refsect1>
@@ -699,10 +686,11 @@
 	  operator. <command>dpkg</command> returns success (zero result) if
 	  the specified condition is satisfied, and failure (nonzero result)
 	  otherwise.  There are two groups of operators, which differ in how
-	  they treat a missing <option>ver1</option> or <option>ver2</option>.
-	  These treat no version as earlier than any version:
-	  <emphasis>lt le eq ne ge gt</emphasis>. These treat no version as
-	  later than any version: <emphasis>lt-nl le-nl ge-nl gt-nl</emphasis>.
+	  they treat an empty <option>ver1</option> or <option>ver2</option>.
+	  These treat an empty version as earlier than any version:
+	  <emphasis>lt le eq ne ge gt</emphasis>. These treat an empty version
+	  as later than any version:
+	  <emphasis>lt-nl le-nl ge-nl gt-nl</emphasis>.
 	  These are provided only for compatibility with
 	  <filename>control</filename> file syntax: <emphasis>&lt; &lt;&lt;
 	  &lt;= = &gt;= &gt;&gt; &gt;</emphasis>.
@@ -734,7 +722,7 @@
 	</term>
 
 	<listitem><para>
-	  Display the usage instructions.
+	  Display a brief help message.
 	</para></listitem>
       </varlistentry>
 
@@ -777,14 +765,14 @@
 	    <arg choice="plain">
 	      <group choice="req">
 		<arg>--licence</arg>
-		<arg>--license</arg>
+		<arg>--license </arg>
 	      </group>
 	    </arg>
 	  </cmdsynopsis>
 	</term>
 
 	<listitem><para>
-	  Display <command>dpkg</command> copyright and licence information.
+	  Display <command>dpkg</command> licence.
 	</para></listitem>
       </varlistentry>
 
@@ -956,13 +944,13 @@
 	    <screen>(*)</screen> are forced by default.
 	  </para>
 
-	  <warning>
+	  <note>
 	    <para>
-	      These options are mostly intended to be used by experts only.
-	      Using them without fully understanding their effects may break
-	      your whole system.
+	      <emphasis>Warning: These options are mostly intended to be used
+	      by experts only. Using them without fully understanding their
+	      effects may break your whole system.</emphasis>
 	    </para>
-	  </warning>
+	  </note>
 
 	  <variablelist>
 	    <varlistentry>
@@ -1228,7 +1216,7 @@
 	    (e.g.  <screen>dpkg --purge foo --no-act</screen> will first
 	    purge package foo and then try to <command>purge</command>
 	    package --no-act, even though you probably expected it to
-	    actually do nothing!)
+	    actually do nothing)
 	  </para>
 	</listitem>
       </varlistentry>
@@ -1445,20 +1433,26 @@
     <title>Examples</title>
 
     <para>
-      To list packages containing the string `vi' in their name:
+      To list packages related to the editor vi:
 
       <Screen><command>dpkg</command> <option>-l</option> '*vi*'</Screen>
     </para>
 
     <para>
-      To see the entries in <filename>/var/lib/dpkg/available</filename> on
-      several packages:
+      To see the entries in <filename>/var/lib/dpkg/available</filename> on two
+      packages
+
+      <Screen><command>dpkg</command> <option>--print-avail</option> elvis vim</Screen>
+    </para>
+
+    <para>
+      To search the listing of packages yourself:
 
-      <Screen><command>dpkg</command> <option>--print-avail</option> base-files login xfree86-common | pager</Screen>
+      <Screen><command>less</command> <filename>/var/lib/dpkg/available</filename></Screen>
     </para>
 
     <para>
-      To remove an installed package named "emacs":
+      To remove an installed emacs package:
 
       <Screen><command>dpkg</command> <option>-r</option> emacs</Screen>
     </para>
@@ -1493,6 +1487,11 @@
     <title>See Also</title>
 
     <para>
+      <citerefentry>
+        <refentrytitle>dselect</refentrytitle>
+	<manvolnum>8</manvolnum>
+      </citerefentry>,
+
       <citerefentry>
         <refentrytitle>dpkg-deb</refentrytitle>
 	<manvolnum>1</manvolnum>
@@ -1506,17 +1505,12 @@
       <citerefentry>
 	<refentrytitle>deb-control</refentrytitle>
 	<manvolnum>5</manvolnum>
-      </citerefentry>,
-
-      <citerefentry>
-        <refentrytitle>dselect</refentrytitle>
-	<manvolnum>8</manvolnum>
-      </citerefentry>,
+      </citerefentry>
 
       <citerefentry>
-        <refentrytitle>apt</refentrytitle>
+	<refentrytitle>dpkg-reconfigure</refentrytitle>
 	<manvolnum>8</manvolnum>
-      </citerefentry>.
+      </citerefentry>
     </para>
   </refsect1>
 </refentry>

man/es/md5sum.1

@@ -1,5 +1,5 @@
 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
-.TH MD5SUM 1 "29 de Noviembre de 1995" "Lankester et al" "Debian GNU/Linux"
+.TH MD5SUM 1 "29 de Noviembre de 1995" "Lankester et al." "Debian GNU/Linux"
 .SH NOMBRE
 md5sum \- genera o comprueba las sumas de control MD5
 

man/ja/md5sum.1

@@ -3,7 +3,7 @@
 .\"WORD:  checksum		チェックサム
 .\"WORD:  check			照合
 .\"original revision: 1.2
-.TH MD5SUM 1 "29th November 1995" "Lankester et al" "Debian GNU/Linux"
+.TH MD5SUM 1 "29th November 1995" "Lankester et al." "Debian GNU/Linux"
 .SH 名前
 md5sum \- MD5 メッセージダイジェストを作成・照合する。
 

scripts/update-alternatives.8

@@ -233,7 +233,9 @@ There are several packages which provide a text editor compatible
 with
 .BR vi ,
 for example
-.BR nvi " and " vim .
+.BR nvi
+and
+.BR vim .
 Which one is used is controlled by the link group
 .BR vi ,
 which includes links for the program itself and the associated manpage.

utils/md5sum.1

@@ -1,5 +1,5 @@
 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
-.TH MD5SUM 1 "29th November 1995" "Lankester et al" "Debian GNU/Linux"
+.TH MD5SUM 1 "29th November 1995" "Lankester et al." "Debian GNU/Linux"
 .SH NAME
 md5sum \- generates or checks MD5 message digests
 

utils/start-stop-daemon.8

@@ -42,11 +42,7 @@ instance, using either the executable specified by
 Any arguments given after
 .BR --
 on the command line are passed unmodified to the program being
-started.  If
-.B --retry
-is specified then 
-.B start-stop-daemon
-will check that the process(es) have terminated.
+started.
 
 With 
 .BR --stop ,
@@ -62,7 +58,11 @@ If such a process does not exist,
 exits with error status 1
 (0 if
 .BR --oknodo
-is specified).
+is specified).  If
+.B --retry
+is specified then 
+.B start-stop-daemon
+will check that the process(es) have terminated.
 
 .SH OPTIONS