r12605: docs patch from Brad Hards <bradh@frogmouth.net>

(This used to be commit 874f16e055ec30bf2ee52a33464b4810a8f8cd89)

2 files changed, 151 insertions, 82 deletions

diff --git a/source4/lib/ldb/man/ldbedit.1.xml b/source4/lib/ldb/man/ldbedit.1.xml
index e2b2fd053f..3cfcce89f1 100644
--- a/source4/lib/ldb/man/ldbedit.1.xml
+++ b/source4/lib/ldb/man/ldbedit.1.xml
@@ -2,130 +2,199 @@
 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
 <refentry id="ldbedit.1">
 
-<refmeta>
+    <refmeta>
 	<refentrytitle>ldbedit</refentrytitle>
 	<manvolnum>1</manvolnum>
-</refmeta>
+    </refmeta>
 
 
-<refnamediv>
+    <refnamediv>
 	<refname>ldbedit</refname>
-	<refpurpose>Edit LDB databases using your favorite editor</refpurpose>
-</refnamediv>
+	<refpurpose>Edit LDB databases using your preferred editor</refpurpose>
+    </refnamediv>
 
-<refsynopsisdiv>
+    <refsynopsisdiv>
 	<cmdsynopsis>
-		<command>ldbedit</command>
-		<arg choice="opt">-h</arg>
-		<arg choice="opt">-s base|one|sub</arg>
-		<arg choice="opt">-b basedn</arg>
-		<arg chioce="opt">-a</arg>
-		<arg choice="opt">-e editor</arg>
-		<arg choice="opt">-H LDB-URL</arg>
-		<arg choice="opt">expression</arg>
-		<arg choice="opt">attributes</arg>
+	    <command>ldbedit</command>
+	    <arg choice="opt">-?</arg>
+	    <arg choice="opt">--usage</arg>
+	    <arg choice="opt">-s base|one|sub</arg>
+	    <arg choice="opt">-b basedn</arg>
+	    <arg choice="opt">-a</arg>
+	    <arg choice="opt">-e editor</arg>
+	    <arg choice="opt">-H LDB-URL</arg>
+	    <arg choice="opt">expression</arg>
+	    <arg rep="repeat" choice="opt">attributes</arg>
 	</cmdsynopsis>
 </refsynopsisdiv>
 
 <refsect1>
 	<title>DESCRIPTION</title>
 
-	<para>ldbedit is a utility that allows you to edit LDB files using 
-		your favorite editor. ldbedit generates an LDIF file based on 
-		your query, allows you to edit it and then merges it back 
-		into the LDB database.
+	<para>ldbedit is a utility that allows you to edit LDB entries (in 
+	    tdb files, sqlite files or LDAP servers) using your preferred editor.
+	    ldbedit generates an LDIF file based on your query, allows you to edit
+	    the LDIF, and then merges that LDIF back into the LDB backend.
 	</para>
 
 </refsect1>
 
 
-<refsect1>
+    <refsect1>
 	<title>OPTIONS</title>
-
+	
 	<variablelist>
-		<varlistentry>
-		<term>-h</term>
-		<listitem><para>
-		Show list of available options.</para></listitem>
-		</varlistentry>
-
-		<varlistentry>
-			<term>-H &lt;ldb-url&gt;</term>
-			<listitem><para>
-				LDB URL to connect to. See ldb(7) for details.
-			</para></listitem>
-		</varlistentry>
-
-		<varlistentry>
-			<term>-s one|sub|base</term>
-			<listitem><para>Search scope to use. One-level, subtree or base.</para></listitem>
-		</varlistentry>
-
-		<varlistentry>
-			<term>-a</term>
-			<listitem><para>Edit all records. </para></listitem>
-		</varlistentry>
-
-		<varlistentry>
-			<term>-e editor</term>
-			<listitem><para>Specify the editor that should be used (overrides 
-					the VISUAL and EDITOR environment variables).</para></listitem>
-		</varlistentry>
-
-		<varlistentry>
-			<term>-b basedn</term>
-			<listitem><para>Specify Base DN to use.</para></listitem>
-		</varlistentry>
+	    <varlistentry>
+		<term>-?</term>
+		<term>--help</term>
+		<listitem>
+		    <para>
+			Show list of available options, and a phrase describing what that option
+			does.
+		    </para>
+		</listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+		<term>--usage</term>
+		<listitem>
+		    <para>
+			Show list of available options. This is similar to the help option, 
+			however it does not provide any description, and is hence shorter.
+		    </para>
+		</listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+		<term>-H &lt;ldb-url&gt;</term>
+		<listitem>
+		    <para>
+			LDB URL to connect to. For a tdb database,
+			this will be of the form
+			tdb://<replaceable>filename</replaceable>.
+			For a LDAP connection over unix domain
+			sockets, this will be of the form
+			ldapi://<replaceable>socket</replaceable>. For
+			a (potentially remote) LDAP connection over
+			TCP, this will be of the form
+			ldap://<replaceable>hostname</replaceable>. For
+			an SQLite database, this will be of the form
+			sqlite://<replaceable>filename</replaceable>.
+		    </para>
+		</listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+		<term>-s one|sub|base</term>
+		<listitem><para>Search scope to use. One-level, subtree or base.</para></listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+		<term>-a</term>
+		<term>-all</term>
+		<listitem>
+		    <para>Edit all records. This allows you to
+			apply the same change to a number of records
+			at once. You probably want to combine this
+			with an expression of the form
+			"objectclass=*".
+		    </para>
+		</listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+		<term>-e editor</term>
+		<term>--editor editor</term>
+		<listitem>
+		    <para>Specify the editor that should be used (overrides 
+			the VISUAL and EDITOR environment
+			variables). If this option is not used, and
+			neither VISUAL nor EDITOR environment variables
+			are set, then the vi editor will be used.
+		    </para>
+		</listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+		<term>-b basedn</term>
+		<listitem><para>Specify Base Distinguished Name to use.</para></listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+		<term>-v</term>
+		<term>--verbose</term>
+		<listitem>
+		    <para>Make ldbedit more verbose about the
+			operations that are being performed. Without
+			this option, ldbedit will only provide a
+			summary change line.
+		    </para>
+		</listitem>
+	    </varlistentry>
 		
 	</variablelist>
 	
-</refsect1>
+    </refsect1>
 
-<refsect1>
+    <refsect1>
 	<title>ENVIRONMENT</title>
 
 	<variablelist>
-		<varlistentry><term>LDB_URL</term>
-			<listitem><para>LDB URL to connect to (can be overrided by using the 
-					-H command-line option.)</para></listitem>
-		</varlistentry>
-		<varlistentry><term>VISUAL and EDITOR</term>
-			<listitem><para>Environment variables used to determine what 
-					editor to use. If VISUAL isn't set, EDITOR is used. 
-			</para></listitem>
-		</varlistentry>
+	    <varlistentry>
+		<term>LDB_URL</term>
+		<listitem>
+		    <para>LDB URL to connect to. This can be
+		    overridden by using the -H command-line option.)
+		    </para>
+		</listitem>
+	    </varlistentry>
+	    <varlistentry>
+		<term>VISUAL and EDITOR</term>
+		<listitem>
+		    <para>
+			Environment variables used to determine what 
+			editor to use. VISUAL takes precedence over
+			EDITOR, and both are overridden by the
+			-e command-line option.
+		    </para>
+		</listitem>
+	    </varlistentry>
 	</variablelist>
 	
-</refsect1>
+    </refsect1>
 
-<refsect1>
+    <refsect1>
 	<title>VERSION</title>
-
+	
 	<para>This man page is correct for version 4.0 of the Samba suite.</para>
-</refsect1>
+    </refsect1>
 
-<refsect1>
+    <refsect1>
 	<title>SEE ALSO</title>
+	
+	<para>ldb(7), ldbmodify(1), ldbdel(1), ldif(5), vi(1)</para>
 
-	<para>ldb(7), ldbmodify, ldbdel, ldif(5)</para>
+    </refsect1>
 
-</refsect1>
-
-<refsect1>
+    <refsect1>
 	<title>AUTHOR</title>
 
-	<para> ldb was written by 
-		 <ulink url="http://samba.org/~tridge/">Andrew Tridgell</ulink>.
+	<para>
+	    ldb was written by 
+	    <ulink url="http://samba.org/~tridge/">Andrew Tridgell</ulink>.
 	</para>
 
 	<para>
-If you wish to report a problem or make a suggestion then please see
-the <ulink url="http://ldb.samba.org/"/> web site for
-current contact and maintainer information.
+	    If you wish to report a problem or make a suggestion then please see
+	    the <ulink url="http://ldb.samba.org/"/> web site for
+	    current contact and maintainer information.
 	</para>
 
-	<para>This manpage was written by Jelmer Vernooij.</para>
+	<para>
+	    This manpage was written by Jelmer Vernooij and updated
+	    by Brad Hards.
+	</para>
 	
-</refsect1>
+    </refsect1>
 
 </refentry>
diff --git a/source4/lib/ldb/tools/ldbedit.c b/source4/lib/ldb/tools/ldbedit.c
index 570179c2e1..4d47cf27c9 100644
--- a/source4/lib/ldb/tools/ldbedit.c
+++ b/source4/lib/ldb/tools/ldbedit.c
@@ -274,7 +274,7 @@ static void usage(void)
 	printf("  -b basedn        choose baseDN\n");
 	printf("  -a               edit all records (expression 'objectclass=*')\n");
 	printf("  -e editor        choose editor (or $VISUAL or $EDITOR)\n");
-	printf("  -v               verbose mode)\n");
+	printf("  -v               verbose mode\n");
 	exit(1);
 }