[nautilus-actions] Update NACT user's manual

[Pierre Wieser <pwieser src gnome org>]

commit f2cfcad051bf1193aaa477f2d71f6d8d575e4119
Author: Pierre Wieser <pwieser trychlos org>
Date:   Tue Aug 17 09:08:38 2010 +0200

    Update NACT user's manual

 doc/nact/C/figures/sort-buttons-frame.png |  Bin 0 -> 14202 bytes
 doc/nact/C/nact-execution.xml             |   59 ++++++++++++++++++++++++-----
 doc/nact/C/nact-profiles.xml              |    8 +++-
 doc/nact/C/nact-save.xml                  |   19 +++++++++
 doc/nact/C/nact-sorting.xml               |   16 ++++++++
 doc/nact/C/nact-starting.xml              |    2 +-
 doc/nact/Makefile.am                      |    1 +
 7 files changed, 93 insertions(+), 12 deletions(-)
---
diff --git a/doc/nact/C/figures/sort-buttons-frame.png b/doc/nact/C/figures/sort-buttons-frame.png
new file mode 100644
index 0000000..884e875
Binary files /dev/null and b/doc/nact/C/figures/sort-buttons-frame.png differ
diff --git a/doc/nact/C/nact-execution.xml b/doc/nact/C/nact-execution.xml
index 2258686..defbe0c 100644
--- a/doc/nact/C/nact-execution.xml
+++ b/doc/nact/C/nact-execution.xml
@@ -518,38 +518,77 @@
           <filename>pierre</filename>, <filename>paul</filename>
           and <filename>jacques</filename>.
         </para>
-        <para>
-          If we have requested <literal>echo %b</literal>,
-          then the following commands will be run:
-        </para>
+        <formalpara>
+          <title>
+            If we have requested <command>echo %b</command>,
+          </title>
+          <para>
+            then the following commands will be successively run:
+          </para>
+        </formalpara>
         <simplelist>
           <member><command>echo pierre</command></member>
           <member><command>echo paul</command></member>
           <member><command>echo jacques</command></member>
         </simplelist>
         <para>
-          Contrarily, if we have requester <literal>echo %B</literal>,
-          then the following command will be run:
+          This is because <literal>%b</literal> marks a <emphasis>singular</emphasis>
+          parameter. The command is the run once for each of the selected items.
         </para>
+        <formalpara>
+          <title>
+            Contrarily, if we have requester <command>echo %B</command>,
+          </title>
+          <para>
+            then the following command will be run:
+          </para>
+        </formalpara>
         <simplelist>
           <member><command>echo pierre paul jacques</command></member>
         </simplelist>
         <para>
-          If we have requested <literal>echo %b %B</literal>,
-          then the following commands will be run:
+          This is because <literal>%B</literal> marks a a <emphasis>plural</emphasis>
+          parameter. The command is then run only once, with the list of selected
+          items as arguments.
         </para>
+        <formalpara>
+          <title>
+            If we have requested <command>echo %b %B</command>,
+          </title>
+          <para>
+            then the following commands will be successively run:
+          </para>
+        </formalpara>
         <simplelist>
           <member><command>echo pierre pierre paul jacques</command></member>
           <member><command>echo paul pierre paul jacques</command></member>
           <member><command>echo jacques pierre paul jacques</command></member>
         </simplelist>
         <para>
-          And if we have requested <literal>echo %B %b</literal>,
-          then the following commands will be run:
+          This is because the first <emphasis>relevant</emphasis> parameter
+          is <literal>%b</literal>, and so the command is run once for each
+          selected item, replacing at each occurrence the <literal>%b</literal>
+          parameter with the corresponding item. The second parameter is
+          computed and added as arguments to the executed command.
         </para>
+        <formalpara>
+          <title>
+            And if we have requested <literal>echo %B %b</literal>,
+          </title>
+          <para>
+            then the following commands will be run:
+          </para>
+        </formalpara>
         <simplelist>
           <member><command>echo pierre paul jacques pierre</command></member>
         </simplelist>
+        <para>
+          This is because the first <emphasis>relevant</emphasis> parameter here
+          is <literal>%B</literal>. The command is then run only once, replacing
+          <literal>%B</literal> with the space-separated list of basenames. As
+          the command is only run once, the <literal>%b</literal> is substituted
+          only once with the (first) basename. 
+        </para>
       </example>
    </sect4>
   </sect3>
diff --git a/doc/nact/C/nact-profiles.xml b/doc/nact/C/nact-profiles.xml
index 6356529..7a596b9 100644
--- a/doc/nact/C/nact-profiles.xml
+++ b/doc/nact/C/nact-profiles.xml
@@ -21,10 +21,16 @@
       terminal will open in the parent of the targeted directory.
     </para>
     <para>
-      The solution is to define a new profile to your action,
+      One solution is to define a new profile to your action,
       configuring this profile to open the terminal in the
       targeted directory.
     </para>
+    <para>
+      At runtime, &prodname; will successively examine each profile
+      attached to your action. If the first profile targets a file
+      while you have selected a directory, then &prodname; will just
+      try with your second profile.
+    </para>
   </example>
   <para>
     To create a new profile, first select the action in the items list,
diff --git a/doc/nact/C/nact-save.xml b/doc/nact/C/nact-save.xml
index 0864aca..f9150fb 100644
--- a/doc/nact/C/nact-save.xml
+++ b/doc/nact/C/nact-save.xml
@@ -1,5 +1,24 @@
 <sect2 id="usage-save">
   <title>Saving your modifications</title>
   <para>
+    To save your modifications, choose
+    <menuchoice>
+      <shortcut>
+        <keycombo>
+          <keycap>Ctrl</keycap>
+          <keycap>S</keycap>
+        </keycombo>
+      </shortcut>
+      <guimenu>File</guimenu>
+      <guisubmenu>Save</guisubmenu>
+    </menuchoice>.
+  </para>
+  <para>
+    All your pending modifications will be saved.
+    New items will be created by the first available writable I/O provider.
+  </para>
+  <para>
+    &prodname; also has an Auto-save feature which is configurable in 
+    <guimenuitem>Preferences</guimenuitem> dialog box.
   </para>
 </sect2>
diff --git a/doc/nact/C/nact-sorting.xml b/doc/nact/C/nact-sorting.xml
index c01ce89..bc50b60 100644
--- a/doc/nact/C/nact-sorting.xml
+++ b/doc/nact/C/nact-sorting.xml
@@ -29,6 +29,22 @@
       In these modes, actions and menus are sorted depending of their label,
       inside of their parent. 
     </para>
+    <figure id="nact-FIG-sort-buttons">
+      <title>Sort buttons in the main window</title>
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="figures/sort-buttons-frame.png" format="PNG" />
+          </imageobject>
+          <textobject>
+            <phrase>Shows the three sort buttons in the main window.</phrase>
+          </textobject>
+          <caption>
+            <para>Sort buttons in the main window</para>
+          </caption>
+        </mediaobject>
+      </screenshot>
+    </figure>
     <para>
       You may sort your actions by:
     </para>
diff --git a/doc/nact/C/nact-starting.xml b/doc/nact/C/nact-starting.xml
index d36ebc0..ffc1919 100644
--- a/doc/nact/C/nact-starting.xml
+++ b/doc/nact/C/nact-starting.xml
@@ -624,7 +624,7 @@
             </listitem>
           </itemizedlist>
           <para>
-            If the cmmand you enter does not have an absolute path,
+            If the command you enter does not have an absolute path,
             then it will be searched for in the <envar>PATH</envar>
             variable at execution time.
           </para>
diff --git a/doc/nact/Makefile.am b/doc/nact/Makefile.am
index 4b65b9a..9625a10 100644
--- a/doc/nact/Makefile.am
+++ b/doc/nact/Makefile.am
@@ -86,6 +86,7 @@ DOC_FIGURES = \
 	figures/nact-working-directory-frame.png		\
 	figures/remove.png								\
 	figures/sort-asc.png							\
+	figures/sort-buttons-frame.png					\
 	figures/sort-desc.png							\
 	figures/sort-manual.png							\
 	figures/start-context-menu.png					\