[3/3] Update lxterminal.xml: multiple --command=, run multiple comman…

…ds from the command line

The reader is kindly asked to pay attention for the s letter, or absent of, and to the = character, or absent of, in the seemingly no difference --command, --command= and --commands= terms. In what follows, these 3 different terms are totally different. 
With the current stable implementation, with multiple --command= command line options, only the last one was used. It override the previous occurrences of --command=. As promised at lxde#98 (comment), this code modifies that. With it, all the commands specified with --command= option will run. Each one at a different tab. Each command is automatically paired with a tab. After exhausting existing tabs, new tabs will be automatically created.

This feature does not lift the basic limitation of commands in lxterminal command line. Which is, that short lived processes makes the tab they ran within, or the whole window in case of only short lived processes, to get closed as soon as the short lived processes have terminated. This limitation is shortly described in the modified man page.

This patch constitutes of modifying 3 files:
1. src/lxterminal.h
2. src/lxterminal.c
3. man/lxterminal.xml

Lightly tested.

The modification of lxterminal.xml, beside describing the new behavior of the --command= option, also describes, in some length, some pitfalls of lxterminal.

man/lxterminal.xml

@@ -24,8 +24,7 @@
   </refsynopsisdiv>
   <refsect1>    <title>DESCRIPTION</title>
 
-    <para>This manual page documents briefly the
-      <command>lxterminal</command> command.</para>
+    <para>This manual page documents the <command>lxterminal</command> command.</para>
 
     <para><command>lxterminal</command> is a program that provides a terminal
     emulator
@@ -42,37 +41,87 @@
     </para>
 
     <variablelist>      <varlistentry>        <term>	  <option>-e <replaceable>STRING</replaceable></option>
-          <option>--command=<replaceable>STRING</replaceable></option>
           <option>--command <replaceable>STRING</replaceable></option>
+          <option>--command=<replaceable>STRING</replaceable></option>
 
         </term>
-        <listitem>          <para>This option specifies the program (and its command line arguments) to be run in the terminal.
-Except in the <option>--command=</option> form, this must be the last option on the command line.</para>
+	<listitem>          <para>These options specifies the program (and its command line arguments) to be run in the terminal. Except in the <option>--command=</option> form, this must be the last option on the command line, since the following arguments, if there are any, will be considered related to the program to be run. Multiple <option>command=</option> options, each specify a single program (and its command line arguments), create multiple tabs, each running the respective program. New tabs will be created as necessary, after all the explictly requested <option>tabs=</option> will be exhausted.</para>
         </listitem>
       </varlistentry>
       <varlistentry>	<term>	  <option>--geometry=<replaceable>CHARACTERS</replaceable>x<replaceable>LINES</replaceable></option>
 	</term>
 	<listitem>	  <para>Set the terminal's size in characters and lines.</para>
 	</listitem>
       </varlistentry>
+      <varlistentry>	<term>	  <option>-h</option>
+	  <option>--help</option>
+	</term>
+	<listitem>	  <para>Prints a short help message, and exit.</para>
+	</listitem>
+      </varlistentry>
       <varlistentry>	<term>	  <option>-l</option>
 	  <option>--loginshell</option>
 	</term>
 	<listitem>	  <para>Executes login shell.</para>
 	</listitem>
       </varlistentry>
-      <varlistentry>	<term>	  <option>-t <replaceable>NAME[,NAME[,NAME[...]]]</replaceable></option>
-	  <option>--title=<replaceable>NAME[,NAME[,NAME[...]]]</replaceable></option>
-	  <option>--tabs=<replaceable>NAME[,NAME[,NAME[...]]]</replaceable></option>
+      <varlistentry>	<term>	  <option>-T <replaceable>NAME</replaceable></option>
+	  <option>-t <replaceable>NAME</replaceable></option>
+	  <option>--title=<replaceable>NAME</replaceable></option>
+	  <option>--tabs=<replaceable>[NAME[,NAME[...]]]</replaceable></option>
 	</term>
-	<listitem>	  <para>Set the terminal's title. Use comma for multiple tabs.</para>
+	<listitem>	  <para>Set the terminal's title. Comma separated multiple titles create multiple tabs only with the <option>--tabs=</option> form.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>        <term>          <option>--working-directory=<replaceable>DIRECTORY</replaceable></option>
         </term>
         <listitem>          <para>Set the terminal's working directory.</para>
         </listitem>
       </varlistentry>
+      <varlistentry>	<term>	  <option>-v</option>
+	  <option>--version</option>
+	</term>
+	<listitem>	  <para>Prints the program version, and exit.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>    <title>EXAMPLES, AND MORE DETAILS</title>
+
+    <variablelist>       <varlistentry>	<term>	  <option>The hidden tab</option>
+        </term>
+	<listitem>	  <para>A hidden tab is created when <option>--tabs</option>, or any <option>--command</option> variant, is requested, with no more than one command, or no more than one tab, is specified. For example,</para>
+		<para><command>lxterminal</command> --tabs= --no-remote</para>
+		<para>This hidden tab can be revealed when the <command>lxterminal</command> is running. For example, when requesting a new tab with the Shift+Ctrl+T combination keys.</para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>	<term>	  <option>The command examples</option> 	</term><listitem>
+<para>For display puposes, the command examples might be broken into more than one line. When actually using the examples, commands should be entered in a single line. Or have line breaks according to the usual shell conventions.</para>
+		    <para>All command examples here use <option>--no-remote</option> to avoid interaction with possibly running <command>lxterminal</command>s.</para>
+	</listitem>
+      </varlistentry>
+	    <varlistentry>	<term>	  <option>A short lived process is requested in the command line</option> 	</term>
+		    <listitem>      <para>Consider</para>
+			    <para><command>lxterminal</command> --no-remote --command=&apos;/bin/bash -c &quot;echo This window will be closed after you will press enter. ; read -p \&quot;Do press the &lt;enter&gt; key.\&quot; &quot; &apos;</para>
+			    <para>This example emphasizes a limitaion of running commands from the <command>lxterminal</command> command line. As a result, the feature to run a command from the <command>lxterminal</command> command line is much more useful for processes that exit by the user explicit request. Such as an interactive shell. A short lived process does work. Only that it is fast enough to make the window, or the tab, closed before the user can pay attention. For a short lived process, such as</para>
+			    <para><command>lxterminal</command> --no-remote --tabs=ls,"Midnight Commander" --command=ls --command=mc</para><para>
+					    , the user must have indirect means to inspect the outcome of the <option>ls</option> command, if he wishes to. Such as redirecting the output to a file.</para>
+	</listitem>
+      </varlistentry>
+	    <varlistentry>	<term>	  <option>Multiple occurences of the same option</option> 	</term>
+		    <listitem>  
+			    <para><command>lxterminal</command> --no-remote --tabs=&apos;1st tab&apos;,&quot;2nd tab&quot; --tabs= --no-remote</para>
+			    <para>In contrast to many other applications, repeating a command line <option>option</option> is not an error. With some <option>option</option>s, the right most occurence overrides previous ocuurences. But there are exceptions. The left most <option>--command=</option> will always be executed in the 1st tab. Unless <option>-e</option>, or <option>command</option>, was specified. As stated earlier, multiple <option>command=</option> are commulative in the sense that each will be executed. Just try out if it is a concern for you. The behaviour is deterministic.</para> 
+	</listitem>
+      </varlistentry>
+	    <varlistentry>	<term>	  <option>Comma is a separator for --tabs=</option> 	</term>
+		    <listitem>  
+			    <para>The comma character, &apos;,&apos;, is used as the separator for the titles to the <option>--tabs=</option> option.</para>
+			    <para><command>lxterminal</command> --tabs=&quot;midnight commander,2nd tab&quot; --command=mc --no-remote</para>
+			    <para>There is no way to insert a comma character in the titles to be displayed by <option>--tabs=</option>. The comma character can be used for the similar options for giving a title, such as <option>-T</option>. But these other options do not offer mutltiple tabs.</para>
+	</listitem>
+      </varlistentry>
     </variablelist>
   </refsect1>