From 2712075ebeee7db39143fa8a6c8b52feca212a7e Mon Sep 17 00:00:00 2001
From: Giorgos Keramidas <keramida@FreeBSD.org>
Date: Mon, 16 Oct 2006 11:31:06 +0000
Subject: [PATCH] Fix a few nits and expand the "p4 describe" description.

---
 .../articles/p4-primer/article.sgml           | 67 ++++++++++++++++---
 1 file changed, 56 insertions(+), 11 deletions(-)

diff --git a/en_US.ISO8859-1/articles/p4-primer/article.sgml b/en_US.ISO8859-1/articles/p4-primer/article.sgml
index 042256ff14..ea6cc8436a 100644
--- a/en_US.ISO8859-1/articles/p4-primer/article.sgml
+++ b/en_US.ISO8859-1/articles/p4-primer/article.sgml
@@ -229,12 +229,12 @@
 
 	<programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/...</programlisting>
 
-	<para>The <literal>...</literal> should taken literally.  It
+	<para>The <literal>...</literal> should be taken literally.  It
 	  is a <application>Perforce</application> idiom for saying
 	  <quote>this directory and all files and directories below
 	  it.</quote></para>
 
-	<para>A View can contain multiple mappings.  Let's say you
+	<para>A Perforce <quote>view</quote> can contain multiple mappings.  Let's say you
 	  want to map in both the SMPng tree and the NFS tree.  Your
 	  View might look like:</para>
 
@@ -533,7 +533,7 @@
 
   <screen>&prompt.user; <userinput>p4 edit <replaceable>filename</replaceable></userinput></screen>
 
-  <para>This marks the file on the server as being in the edit state,
+  <para>This marks the file on the server as being in the <emphasis>edit</emphasis> state,
     which then allows it to be submitted after changes are made, or
     marks it for special handling when doing an integration or sync
     operation.  Note that editing is not exclusive in
@@ -582,10 +582,46 @@
     change, and what its change number was.  A change can be examined
     in detail via the <command>p4 describe
     <replaceable>changenumber</replaceable></command> command.  This
-    will provide the submit log and the diffs of the actual change.
-    It is common to use the <option>-du</option> or
-    <option>-dc</option> flags to produce unified or context diffs
-    instead of the native diff format.</para>
+    will provide the submit log and the diffs of the actual change.</para>
+
+  <para>Commonly, the <command>p4&nbsp;describe</command> command is used in one
+    of three ways:</para>
+
+  <variablelist>
+    <varlistentry>
+      <term><command>p4 describe -s <replaceable>CHANGE</replaceable></command></term>
+
+      <listitem>
+	<para>List a short description of
+	  changeset <emphasis>CHANGE</emphasis>, including the commit log of
+	  the particular changeset and a list of the files it affected.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><command>p4 describe -du <replaceable>CHANGE</replaceable></command></term>
+
+      <listitem>
+	<para>List a description of changeset <emphasis>CHANGE</emphasis>,
+	  including the commit log of the particular changeset, a list of the
+	  files it affected and a patch for each modified file, in a format
+	  similar to <quote>unified diff</quote> patches (but not exactly the
+	  same).</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><command>p4 describe -dc <replaceable>CHANGE</replaceable></command></term>
+
+      <listitem>
+	<para>List a description of changeset <emphasis>CHANGE</emphasis>,
+	  including the commit log of the particular changeset, a list of the
+	  files it affected and a patch for each modified file, in a format
+	  similar to <quote>context diff</quote> patches (but not exactly the
+	  same).</para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
 
   <para>The <command>p4 filelog
     <replaceable>filename</replaceable></command> command will show
@@ -664,7 +700,16 @@
   <para>If you want to add a whole tree of files, run a command
     like:</para>
 
-  <screen>&prompt.user; <userinput>find . -type f |xargs p4 add</userinput></screen>
+  <screen>&prompt.user; <userinput>find . -type f | xargs p4 add</userinput></screen>
+
+  <note>
+    <para><application>Perforce</application> can track UNIX symlinks too, so
+      you can probably
+      use <quote><command>\!&nbsp;-type&nbsp;d</command></quote> as the
+      matching expression in &man.find.1; above.  We don't commit symlinks
+      into the source tree of &os; though, so this should not be
+      necessary.</para>
+  </note>
 
   <para>Doing a <command>p4 submit</command> will then copy the file
     to the Depot on the server.  It is very important to only add
@@ -704,9 +749,9 @@
     coerce the permissions on the files if needed.  Then run the
     following commands:</para>
 
-  <screen>&prompt.user; <userinput>p4 diff -se ... |xargs p4 edit</userinput>
-&prompt.user; <userinput>p4 diff -sd ... |xargs p4 delete</userinput>
-&prompt.user; <userinput>find . -type f |xargs p4 add</userinput></screen>
+  <screen>&prompt.user; <userinput>p4 diff -se ... | xargs p4 edit</userinput>
+&prompt.user; <userinput>p4 diff -sd ... | xargs p4 delete</userinput>
+&prompt.user; <userinput>find . -type f | xargs p4 add</userinput></screen>
 
   <para>The first command tells <application>Perforce</application> to
     look for files that have changed, even if they are not open.  The