X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=senf%2FUtils%2FConsole%2FMainpage.dox;h=3cee76732cbbc9d3b52e083056026506187eb23a;hb=6aae6e526573187ece558842e928578e5aa4cc4c;hp=9b25f2ed4dba651bc777f1087d4b02fd85e3d15f;hpb=b8a2a9d30d2c0aa986c6c86f9cc9288ead67ebdb;p=senf.git

diff --git a/senf/Utils/Console/Mainpage.dox b/senf/Utils/Console/Mainpage.dox
index 9b25f2e..3cee767 100644
--- a/senf/Utils/Console/Mainpage.dox
+++ b/senf/Utils/Console/Mainpage.dox
@@ -137,7 +137,8 @@
 
 
     \section intro_commands Implementing console/config commands
-    \seechapter \ref console_commands
+    \seechapter \ref console_commands \n
+    \seechapter \ref senf::console::factory
 
     The console/config language does not define, how arguments are passed to the commands, it just
     tokenizes the input and passes the tokens to the commands which then handle the
@@ -276,9 +277,19 @@
     Options can be abbreviated at each directory boundary: A command <tt>/foo/bar/do</tt> can be
     called as <tt>--f-b-d</tt> as long as this name is unique.
 
-    Everything after the first '=' character is parsed into argument tokens using the normal
-    config/console parser. If the option has no '=' character, the list of argument tokens will be
-    empty.
+    Everything after the first '=' character is passed as arguments to the command. The exact
+    interpretation depends on the command:
+    \li If the command only takes a single token as argument (e.g. a single string or numeric
+        value), everything after the '=' sign is parsed into a single token (e.g. see rows 2 and 3
+        of the following table).
+    \li In all other cases, the string after the '=' sign is parsed into argument tokens using the
+        config/console parser. In this case, quoted strings need to be quoted twice, once for the
+        shell and once for the config/console parser (e.g. see rows 4 and 5 of the following table).
+    \li If the option has no '=' character, the list of argument tokens will be empty (e.g. see row
+        1 of the following table)
+
+    Without these rules, multi-word string arguments would \e always have to be quoted twice (for
+    the shell and the config/console parser).
 
     <table style="font-size:80%" class="senf">
     <tr><th>Command</th><th>File syntax</th><th>Option syntax</th></tr>
@@ -297,8 +308,8 @@
 
     <tr>
       <td><tt>void doo(std::string const &)</tt></td>
-      <td><tt>/path/to/doo "some test";</tt></td>
-      <td><tt>--path-to-doo='"some text"'</tt></td>
+      <td><tt>/path/to/doo "some text";</tt></td>
+      <td><tt>--path-to-doo="some text"</tt></td>
     </tr>
 
     <tr>
@@ -306,10 +317,13 @@
       <td><tt>/path/to/doo take 1;</tt></td>
       <td><tt>--path-to-doo="take 1"</tt></td>
     </tr>
-    </table>
 
-    The last column is additionally quoted using standard \c sh quoting: quotes in arguments need to
-    be additionally quoted for the shell.
+    <tr>
+      <td><tt>void doo(std::string const &, int)</tt></td>
+      <td><tt>/path/to/doo "take two" 1;</tt></td>
+      <td><tt>--path-to-doo='"take two" 1'</tt></td>
+    </tr>
+    </table>
 
     Short options are registered as aliases for long options. They can be registered with or without
     an implied parameter and can optionally take a parameter. so after
@@ -333,7 +347,7 @@
     $ program --mycommand="2 3" --mycommand="4 5"
     </pre>
 
-    (Beware, that the second argument to \c alias() is \e not shell quoted).
+    (Beware, that the second argument to \c alias() must \e not be shell quoted).
 
 
     \subsection console_access_root Changing the root node
@@ -597,15 +611,16 @@
     Depending on the object added, you can also bind to a more specific node type
     (e.g. senf::console::SimpleCommand) if you know the type of node returned.
 
-    Depending on the type of object added, there are additional attributes which can be set. These
-    attributes are always set by calling them on the factory return value. It is \e not guaranteed,
-    you can call these members on the node reference returned by the \c add() call.
+    Nodes are always added using a factory from the senf::console::factory namespace. The factory
+    has additional (type specific) attributes. These attributes are set by calling member functions
+    called 'attributors' on the temporary factory instance. It is \e not guaranteed, you can call
+    these members on the node reference returned by the \c add() call.
     \code
     namespace fty = senf::console::factory;
-    dir.add("name", fty::Command(callback)
-        .doc("The documentation") );
+    dir.add("name", fty::Command(callback) .doc("The documentation") );
     \endcode
     sets the \e doc attribute (if that is available, otherwise this will fail to compile).
+    \see senf::console::factory for a list of all node factories.
 
 
     \section console_manualparse Manually parsing command arguments
@@ -1085,7 +1100,7 @@
         senf::console::ScopedDirectory<Test2> dir;
 
         Test2() : dir(this), var_(0)
-            { dir.add("var", fty::Variabl(var_) ); }
+            { dir.add("var", fty::Variable(var_) ); }
 
     private:
         int var_;
@@ -1443,4 +1458,3 @@
 // compile-command: "scons -u test"
 // mode: auto-fill
 // End:
-