X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=help%2Fhelp%2Fhtml%2Ffeatures%2Fclarguments-reference.html;h=b2e29e925f62d2b2deda9cf5e55a31802e911d31;hb=56ce5cb6fd0b54f831cf35859886cd69a7f522a3;hp=334dcaaa27a7d30b1eff61b1af536d2628be1b84;hpb=55be75760a07698418e5c5cf4d84119f19a5ba4d;p=jalview.git

diff --git a/help/help/html/features/clarguments-reference.html b/help/help/html/features/clarguments-reference.html
index 334dcaa..b2e29e9 100644
--- a/help/help/html/features/clarguments-reference.html
+++ b/help/help/html/features/clarguments-reference.html
@@ -35,7 +35,6 @@
   <li><a href="#processingalignments">Processing alignments</a></li>
   <li><a href="#outputtingalignmentfiles">Outputting alignment files</a></li>
   <li><a href="#exportingimagefiles">Exporting image files</a></li>
-  <li><a href="#exporting3dstructureimagefiles">Exporting 3D structure image files</a></li>
   <li><a href="#controllingflowofarguments">Controlling flow of arguments</a></li>
   </ul>
 
@@ -65,16 +64,16 @@
     <tr valign="top"><td><code>&#8209;&#8209;help&#8209;all</code></td><td>Help for all arguments</td></tr>
 
     <tr valign="top">
-    <td><code>&#8209;&#8209;headless / &#8209;&#8209;noheadless</code></td>
-    <td>Run Jalview in headless (/ or not in headless) mode.  In headless mode, no GUI interface will be created and Jalview will quit after all arguments have been processed.
+    <td><code>&#8209;&#8209;headless</code></td>
+    <td>Run Jalview in headless mode.  In headless mode, no GUI interface will be created and Jalview will quit after all arguments have been processed.
     <br/>
-    If you use a command line argument to specify an output file of some kind (<code>--output</code>, <code>--image</code> or <code>--structureimage</code>) then <strong>headless mode will be assumed</strong>.  If you don't want this behaviour use <code>--noheadless</code> or <code>--gui</code>.
+    If you use a command line argument to specify an output file of some kind (<code>&#8209;&#8209;output</code>, <code>&#8209;&#8209;image</code> or <code>&#8209;&#8209;structureimage</code>) then <strong>headless mode will be assumed</strong>.  If you don't want this behaviour use <code>&#8209;&#8209;gui</code>.
     </td>
     </tr>
 
     <tr valign="top">
     <td><code>&#8209;&#8209;gui</code></td>
-    <td>Force Jalview to run in graphical mode.  This can be used to counter the assumption of headless mode when an argument that creates an output file is used.  <code>--gui</code> takes precedence over <code>--headless</code>.</td>
+    <td>Force Jalview to run in graphical mode.  This can be used to counter the assumption of headless mode when an argument that creates an output file is used.  <code>&#8209;&#8209;gui</code> takes precedence over <code>&#8209;&#8209;headless</code>.</td>
     </tr>
 
     <tr valign="top">
@@ -103,6 +102,11 @@
     </tr>
 
     <tr valign="top">
+    <td><code>&#8209;&#8209;nostartupfile</code></td>
+    <td>Don't show the default startup file.</td>
+    </tr>
+
+    <tr valign="top">
     <td><code>&#8209;&#8209;webservicediscovery / &#8209;&#8209;nowebservicediscovery</code></td>
     <td>Attempt (/ or don't attempt) to connect to JABAWS web services.</td>
     </tr>
@@ -124,6 +128,13 @@
 
 <!--
     <tr valign="top">
+    <td><code>&#8209;&#8209;P<em>PREFERENCE=VALUE</em></code></td>
+    <td>Set a Jalview preference for this session only.  Experimental.</td>
+    </tr>
+-->
+
+<!--
+    <tr valign="top">
     <td><code>&#8209;&#8209;initsubstitutions / &#8209;&#8209;noinitsubstitutions</code></td>
     <td>Set <code>&#8209;&#8209;substitutions</code> to be initially enabled (or initially disabled).</td>
     </tr>
@@ -509,6 +520,8 @@
     <code>phylip</code> (<code>phy</code>),
     <br/>
     <code>jalview</code> (<code>jvp, jar</code>).
+    <br/>
+    To output directly to STDOUT (console output) use the filename <code>-</code> (a single hyphen).  In this case all STDOUT messages will instead go to STDERR.  If no <code>format</code> is supplied then Fasta will be assumed.
     </td>
     <td><code>format=<em>name</em></code></td>
     <td align="center">&#x2713;</td>
@@ -560,6 +573,16 @@
     <td align="center">&#x2713;</td>
     </tr>
 
+    <tr valign="top">
+    <td><code>&#8209;&#8209;mkdirs</code></td>
+    <td>Enable automatic creation of new directories and parent directories for filenames given, or created through substitutions, in <code>&#8209;&#8209;output</code>, <code>&#8209;&#8209;image</code> or <code>&#8209;&#8209;structureimage</code> arguments.
+    <td></td>
+    <td align="center">&#x2713;</td>
+    </tr>
+
+
+
+Automatically create directories when outputting a file to a new directory
   </table>
 
 
@@ -588,18 +611,56 @@
     <code>biojs</code>.
     </td>
     <td>
-      <code>type=<em>name</em>,
-      <code>textrenderer=<em>name</em>,
-      <code>scale=<em>number</em>,
-      <code>width=<em>number</em>,
-      <code>height=<em>number</em>
+      <code>
+      type=<em>name</em>,
+      <br/>
+      textrenderer=<em>name</em>,
+      <br/>
+      scale=<em>number</em>,
+      <br/>
+      width=<em>number</em>,
+      <br/>
+      height=<em>number</em>,
+      <br/>
+      imagecolour=<em>name</em>
+      </code>
+    </td>
+    <td align="center">&#x2713;</td>
+    </tr>
+
+    <tr valign="top">
+    <td><code>&#8209;&#8209;structureimage&nbsp;<em>filename</em></code></td>
+    <td>Export an image of a 3D structure opened in JMOL (currently jmol only).  Each <code>&#8209;&#8209;structureimage</code> filename will output a file for each <code>&#8209;&#8209;structureimage</code> that has been applied to the open alignment window.  In this situation, to avoid overwriting the same file with each structure, additional substitutions <code>{structuredirname}</code>, <code>{structurebasename}</code> and <code>{structureextname}</code> are available being substituted with the directory path, file basename and file extension of each structure file.    Image formats can be:
+    <br/>
+    <code>svg</code>,
+    <br/>
+    <code>png</code>,
+    <br/>
+    <code>eps</code>.
+    </td>
+    <td>
+      <code>
+      type=<em>name</em>,
+      <br/>
+      textrenderer=<em>name</em>,
+      <br/>
+      scale=<em>number</em>,
+      <br/>
+      width=<em>number</em>,
+      <br/>
+      height=<em>number</em>,
+      <br/>
+      imagecolour=<em>name</em>
+      <br/>
+      bgcolour=<em>name</em>
+      </code>
     </td>
     <td align="center">&#x2713;</td>
     </tr>
 
     <tr valign="top">
     <td><code>&#8209;&#8209;type&nbsp;<em>name</em></code></td>
-    <td>Set the image format for the preceding <code>&#8209;&#8209;image</code> to <em>name</em>.  Valid values for <em>name</em> are:
+    <td>Set the image format for the preceding <code>&#8209;&#8209;image</code> or <code>&#8209;&#8209;structureimage</code> to <em>name</em>.  Valid values for <em>name</em> are:
     <br/>
     <code>svg</code>,
     <br/>
@@ -617,7 +678,7 @@
 
     <tr valign="top">
     <td><code>&#8209;&#8209;textrenderer&nbsp;<em>name</em></code></td>
-    <td>Sets whether text in a vector image format (SVG, HTML, EPS) should be rendered as text or vector line-art.  Valid values for <em>name</em> are:
+    <td>Sets whether text in a vector image format (SVG, HTML, EPS) should be rendered as text or vector line-art.  Applies to the preceding <code>&#8209;&#8209;image</code> or <code>&#8209;&#8209;structureimage</code>.  Valid values for <em>name</em> are:
     <br/>
     <code>text</code>,
     <br/>
@@ -629,7 +690,7 @@
 
     <tr valign="top">
     <td><code>&#8209;&#8209;scale&nbsp;<em>number</em></code></td>
-    <td>Sets a scaling for bitmap image format (PNG).  Should be given as a floating point number.  This can also be set as a sub-value modifier to the <code>--image</code> value.  If used in conjunction with <code>--width</code> and <code>--height</code> then the smallest scaling will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).
+    <td>Sets a scaling for bitmap image format (PNG).  Should be given as a floating point number.  Applies to the preceding <code>&#8209;&#8209;image</code> or <code>&#8209;&#8209;structureimage</code>.  This can also be set as a sub-value modifier to the <code>&#8209;&#8209;image</code> or <code>&#8209;&#8209;structureimage</code> value.  If used in conjunction with <code>&#8209;&#8209;width</code> and <code>&#8209;&#8209;height</code> then the smallest size will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).
     </td>
     <td></td>
     <td align="center">&#x2713;</td>
@@ -637,7 +698,7 @@
 
     <tr valign="top">
     <td><code>&#8209;&#8209;width&nbsp;<em>number</em></code></td>
-    <td>Sets a width for bitmap image format (PNG) with the height maintaining the aspect ratio.  Should be given as a positive integer.  This can also be set as a sub-value modifier to the <code>--image</code> value.  If used in conjunction with <code>--scale</code> and <code>--height</code> then the smallest scaling will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).
+    <td>Sets a width for bitmap image format (PNG) with the height maintaining the aspect ratio.  Applies to the preceding <code>&#8209;&#8209;image</code> or <code>&#8209;&#8209;structureimage</code>.  Should be given as a positive integer.  This can also be set as a sub-value modifier to the <code>&#8209;&#8209;image</code> or <code>&#8209;&#8209;structureimage</code> value.  If used in conjunction with <code>&#8209;&#8209;scale</code> and <code>&#8209;&#8209;height</code> then the smallest size will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).
     </td>
     <td></td>
     <td align="center">&#x2713;</td>
@@ -645,97 +706,21 @@
 
     <tr valign="top">
     <td><code>&#8209;&#8209;height&nbsp;<em>number</em></code></td>
-    <td>Sets a height for bitmap image format (PNG) with the width maintaining the aspect ratio.  Should be given as a positive integer.  This can also be set as a sub-value modifier to the <code>--image</code> value.  If used in conjunction with <code>--scale</code> and <code>--width</code> then the smallest scaling will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).</td>
-    <td></td>
-    <td align="center">&#x2713;</td>
-    </tr>
-
-    <tr valign="top">
-    <td><code>&#8209;&#8209;groovy&nbsp;<em>filename</em></code></td>
-    <td>Process a groovy script in the file for the open alignment.</td>
-    <td></td>
-    <td align="center">&#x2713;</td>
-    </tr>
-
-  </table>
-
-
-  <h2><a name="exporting3dstructureimagefiles"></a>Exporting 3D structure image files (<code>jmol</code> only)</h2>
-
-  <table border="1" cellpadding="3">
-    <tr valign="top">
-    <td><strong>argument</strong></td>
-    <td><strong>action</strong></td>
-    <td><strong>sub-value modifiers</strong> (optional)</td>
-    <td><strong>linked</strong> (optional)</td>
-    </tr>
-
-    <tr valign="top">
-    <td><code>&#8209;&#8209;structureimage&nbsp;<em>filename</em></code></td>
-    <td>Export an image of a 3D structure opened in JMOL.  Image formats can be:
-    <br/>
-    <code>svg</code>,
-    <br/>
-    <code>png</code>,
-    <br/>
-    <code>eps</code>.
-    </td>
-    <td>
-      <code>structureimagetype=<em>name</em>,
-      <code>structureimagetextrenderer=<em>name</em>,
-      <code>structureimagescale=<em>number</em>,
-      <code>structureimagewidth=<em>number</em>,
-      <code>structureimageheight=<em>number</em>
-    </td>
-    <td align="center">&#x2713;</td>
-    </tr>
-
-    <tr valign="top">
-    <td><code>&#8209;&#8209;structureimagetype&nbsp;<em>name</em></code></td>
-    <td>Set the structure image format for the preceding --structureimage. Valid values are:
-    <br/>
-    <code>svg</code>,
-    <br/>
-    <code>png</code>,
-    <br/>
-    <code>eps</code>.
-    </td>
+    <td>Sets a height for bitmap image format (PNG) with the width maintaining the aspect ratio.  Applies to the preceding <code>&#8209;&#8209;image</code> or <code>&#8209;&#8209;structureimage</code>.  Should be given as a positive integer.  This can also be set as a sub-value modifier to the <code>&#8209;&#8209;image</code> or <code>&#8209;&#8209;structureimage</code> value.  If used in conjunction with <code>&#8209;&#8209;scale</code> and <code>&#8209;&#8209;width</code> then the smallest size will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).</td>
     <td></td>
     <td align="center">&#x2713;</td>
     </tr>
 
     <tr valign="top">
-    <td><code>&#8209;&#8209;structureimagetextrenderer&nbsp;<em>name</em></code></td>
-    <td>Sets whether text in a vector structure image format (SVG, EPS) should be rendered as text or vector line-art. Possible values are:
-    <br/>
-    <code>text</code>,
-    <br/>
-    <code>lineart</code>.
-    </td>
+    <td><code>&#8209;&#8209;bgcolour&nbsp;<em>name</em></code></td>
+    <td>Only applies to structure images (opened with <code>jmol</code> structure viewer).  Sets the background colour of the preceding <code>&#8209;&#8209;structureimage</code>.  <em>name</em> should be either a named colour (e.g. <code>white</code>, <code>cyan</code>) known to Jmol, or can be given as a six digit RGB hex string (e.g. <code>ffffff</code>, <code>00ffff</code>).  This can also be set as a sub-value modifier to the <code>&#8209;&#8209;structureimage</code> value.</td>
     <td></td>
     <td align="center">&#x2713;</td>
     </tr>
 
     <tr valign="top">
-    <td><code>&#8209;&#8209;structureimagescale&nbsp;<em>number</em></code></td>
-    <td>Sets a scaling for bitmap structure image format (PNG). Should be given as a floating point number. If used in conjunction with --structureimagewidth and --structureimageheight then the smallest scaling will be used (structureimagescale, structureimagewidth and structureimageheight provide bounds for the structure image).
-    </td>
-    <td></td>
-    <td align="center">&#x2713;</td>
-    </tr>
-
-    <tr valign="top">
-    <td><code>&#8209;&#8209;structureimagewidth&nbsp;<em>number</em></code></td>
-    <td>Sets a width for bitmap structure image format (PNG) with the height maintaining the aspect ratio. Should be given as a positive integer. If used in conjunction with --structureimagescale and --structureimageheight then the smallest scaling will be used (structureimagescale, structureimagewidth and structureimageheight provide bounds for the structure image).
-    </td>
-    <td></td>
-    <td align="center">&#x2713;</td>
-    </tr>
-
-    <tr valign="top">
-    <td><code>&#8209;&#8209;structureimageheight&nbsp;<em>number</em></code></td>
-    <td>Sets a height for bitmap structure image format (PNG) with the width maintaining the aspect ratio. Should be given as a positive integer. If used in conjunction with --structureimagescale and --structureimagewidth then the smallest scaling will be used (structureimagescale, structureimagewidth and structureimageheight provide bounds for the structure image).
-    </td>
+    <td><code>&#8209;&#8209;groovy&nbsp;<em>filename</em></code></td>
+    <td>Process a groovy script in the file for the open alignment.</td>
     <td></td>
     <td align="center">&#x2713;</td>
     </tr>
@@ -756,24 +741,36 @@
     <td>
     Move on to a new alignment window.  This will ensure <code>&#8209;&#8209;append</code> will start a new alignment window and other linked arguments will apply to the new alignment window.
     <br/>
-    <em>Note</em> that <code>--open</code> already starts a new alignment window for each file it opens.
+    <em>Note</em> that <code>&#8209;&#8209;open</code> already starts a new alignment window for each file it opens.
     </td>
     </tr>
 
     <tr valign="top">
     <td><code>&#8209;&#8209;substitutions / &#8209;&#8209;nosubstitutions</code></td>
     <td>The following argument values allow (or don't allow) subsituting filename parts.  This is initially true.  Valid substitutions are
+    <br/>
     <code>{basename}</code> - the filename-without-extension of the currently <code>&#8209;&#8209;open</code>ed file (or first <code>&#8209;&#8209;append</code>ed file),
     <br/>
     <code>{dirname}</code>, - the directory (folder) name of the currently <code>&#8209;&#8209;open</code>ed file (or first <code>&#8209;&#8209;append</code>ed file),
+    <code>{extension}</code>, - the extension of the filename of the currently <code>&#8209;&#8209;open</code>ed file (or first <code>&#8209;&#8209;append</code>ed file),
     <br/>
     <code>{argfilebasename}</code> - the filename-without-extension of the current <code>&#8209;&#8209;argfile</code>,
     <br/>
     <code>{argfiledirname}</code> - the directory (folder) name of the current <code>&#8209;&#8209;argfile</code>,
     <br/>
+    <code>{structurebasename}</code> - the filename-without-extension of the <code>&#8209;&#8209;structure</code> file.  Only available to <code>&#8209;&#8209;structureimage</code> .
+    <br/>
+    <code>{structuredirname}</code>, - the directory (folder) name of the <code>&#8209;&#8209;structure</code> file.  Only available to <code>&#8209;&#8209;structureimage</code> .
+    <br/>
+    <code>{structureextension}</code>, - the extension of the filename of the <code>&#8209;&#8209;structure</code> file.  Only available to <code>&#8209;&#8209;structureimage</code> .
+    <br/>
     <code>{n}</code> - the value of the index counter (starting at 0).
     <br/>
-    <code>{++n}</code> - increase and substitute the value of the index counter,
+    <code>{++n}</code> - increase and substitute the value of the index counter.
+    <br/>
+    <code>{m}</code> - the value of the on-the-fly counter (starting at 0).  Only available to <code>&#8209;&#8209;structureimage</code> .
+    <br/>
+    <code>{++m}</code> - increase and substitute the (incremented) value of the on-the-fly counter.  Only available to <code>&#8209;&#8209;structureimage</code> .
     <br/>
     <code>{}</code> - the value of the current alignment window <em>default</em> index.
     </td>
@@ -803,7 +800,7 @@
     <tr valign="top">
     <td><code>&#8209;&#8209;allstructures / &#8209;&#8209;noallstructures</code></td>
     <td>
-        Apply (or stop applying) the following 3D structure formatting arguments to all structures <em>within the current open alignment</em>.  Whilst <code>--allstructures</code> will continue to operate for a <code>--new</code> alignment, the structure formatting arguments must be set again for each new alignment.
+        Apply (or stop applying) the following 3D structure formatting arguments to all structures <em>within the current open alignment</em>.  Whilst <code>&#8209;&#8209;allstructures</code> will continue to operate for a <code>&#8209;&#8209;new</code> alignment, the structure formatting arguments must be set again for each new alignment.
     </td>
     </tr>