From 33a18c18d0ec58e651de30890437cdf4e6eb542d Mon Sep 17 00:00:00 2001
From: Ben Soares <b.soares@dundee.ac.uk>
Date: Wed, 20 Sep 2023 11:15:57 +0100
Subject: [PATCH] JAL-629 Added/corrected/tidied documentation

---
 help/help/html/features/clarguments-basic.html |   45 +++++++++++++++++++++---
 1 file changed, 40 insertions(+), 5 deletions(-)

diff --git a/help/help/html/features/clarguments-basic.html b/help/help/html/features/clarguments-basic.html
index f3c053d..9de0e08 100644
--- a/help/help/html/features/clarguments-basic.html
+++ b/help/help/html/features/clarguments-basic.html
@@ -340,7 +340,7 @@
   </pre>
   </p>
 
-  <h2><a name="outputtingalignmentfiles"></a>Outputting/converting alignment files and images (<code>--output</code>, <code>--format</code>, <code>--image</code>, <code>--type</code>, <code>--textrenderer</code>, <code>--scale</code>, <code>--backups</code>, <code>--overwrite</code>)</h2>
+  <h2><a name="outputtingalignmentfiles"></a>Outputting/converting alignment files and images (<code>--output</code>, <code>--format</code>, <code>--image</code>, <code>--structureimage</code>, <code>--type</code>, <code>--scale</code>, <code>--width</code>, <code>--height</code>, <code>--imagecolour</code>, <code>--bgcolour</code>, <code>--textrenderer</code>, <code>--overwrite</code>, <code>--backups</code>, <code>--mkdirs</code>)</h2>
 
   <p>
   You can save an alignment as an alignment file, or exported as an image, in different formats.  Jalview's alignment output formats are:
@@ -448,7 +448,7 @@
   </pre>
   </p>
 
-  <h3><a name="image"></a><code>--structureimage</code></h3>
+  <h3><a name="structureimage"></a><code>--structureimage</code></h3>
   <p>
   To export an open structure as an image, use the <code>--structureimage</code> argument, which will give an image of the structure as it appears (or would appear if not in <code>--headless</code> mode) in a Jmol window including colour scheme. <code>--structureimage</code> can currently only be used with structures opened with the <code>jmol</code> structureviewer (the default viewer).
   </p>
@@ -462,6 +462,22 @@
   These by default produce a PNG image of screen or webpage resolution, which you will probably want to improve upon.  There are two ways of doing this with Jalview: increasing the scale of the PNG image, or using a vector based image format (EPS, SVG, HTML).
   <p>
 
+  <h3><a name="type"></a><code>--type</code></h3>
+
+  <p>
+  To specify the type of image file to write (if using an unrecognised file extension) use the <code>--type</code> argument to specify a value (see above).  A sub-value modifier on the <code>--image</code> and <code>--structureimage</code> value can also be used.  Valid values are:
+  <br/>
+  <code>png</code> - A Portable Network Graphics image (bitmap, default),
+  <br/>
+  <code>svg</code> - A Scalable Vector Graphics image (vector),
+  <br/>
+  <code>eps</code> - An Encapsulated PostScript file (vector),
+  <br/>
+  <code>html</code> - An HTML rendition of the alignment with embedded source data (vector/web browser),
+  <br/>
+  <code>biojs</code> - An HTML rendition of the alignment with interactive MSA viewer <a href="biojsmsa.html">BioJS-MSA</a> (vector).
+  </p>
+
   <h3><a name="bitmap"></a>Bitmap image types (<code>png</code>)</h3>
 
   <p>
@@ -512,7 +528,7 @@
   </pre>
   </p>
 
-  <h3><a name="height"></a><code>--imagecolour</code></h3>
+  <h3><a name="imagecolour"></a><code>--imagecolour</code></h3>
 
   <p>
   Specify a colour scheme to use just for this image using the <code>--imagecolour</code> argument:
@@ -521,7 +537,7 @@
   </pre>
   </p>
 
-  <h3><a name="height"></a><code>--bgcolour</code></h3>
+  <h3><a name="bgcolour"></a><code>--bgcolour</code></h3>
 
   <p>
   <strong>Only applies to <code>--structureimage</code>.</strong> Specify a background colour for a structure image.  The colour can be specified as a named colour recognised by Java (e.g. <code>"white"</code>, <code>"cyan"</code>) or as a #RRGGBB hash-6-digit-hex-string as used in web pages (e.g. <code>"#ffffff"</code>, <code>"#00ffff"</code>).  Note that if you're using a hash in a bash-like shell then you should quote the string to avoid problems with it being interpreted as a comment character.
@@ -537,7 +553,7 @@
   Next we look at vector image formats, which maintain detail at all resolutions.
   </p>
 
-  <h3><a name="vector"></a>Vector image export</h3>
+  <h3><a name="vector"></a>Vector image export (<code>svg</code>, <code>eps</code>, <code>html</code>, <code>biojs</code>)</h3>
 
   <p>
   Jalview can export an alignment in Encapsulated PostScript (<code>eps</code>), Scalable Vector Graphics (<code>svg</code>), HTML (<code>html</code>) or BioJSON -- another HTML format (<code>biojs</code>), by using, e.g.
@@ -573,6 +589,25 @@
   </pre>
   </p>
 
+  <h3><a name="outputbehaviour"></a>Output behaviour</h3>
+
+  <h3><a name="overwrite"></a><code>--overwrite</code></h3>
+
+  <p>
+  By default, Jalview will refuse to overwrite an output file (alignment or image) unless backups are in operation (alignment files only).  To force overwriting files, use the <code>--overwrite</code> argument.
+  </p>
+
+  <h3><a name="backups"></a><code>--backups / --nobackups</code></h3>
+
+  <p>
+  Jalview should honour your preferences for backup files of output alignment files.  Using <code>--backups</code> or <code>--nobackups</code> forces the behaviour.  With no backups set, you will need to use <code>--overwrite</code> to overwrite an existing file.  Note that Jalview does not make backup files of exported images.
+  </p>
+
+  <h3><a name="mkdirs"></a><code>--mkdirs</code></h3>
+
+  <p>
+  If you want to output a file into a folder that doesn't yet exist (this might happen particularly when using <code>{dirname}</code> substitutions -- see below), then Jalview will fail to write the file since the parent directory doesn't exist.  You can use <code>--mkdirs</code> to tell Jalview to make the new directory (or directories, it will create several nested directories if necessary) before writing the file.  <code>--mkdirs</code> is cautious and will generally refuse to make a new directory using a relative path with <code>..</code> in.
+  </p>
 
   <h2><a name="filenamesubstitutionsandbatchprocessing"></a>Filename substitutions and batch processing (<code>--substitutions</code>, <code>--close</code>, <code>--all</code>)</h2>
 
-- 
1.7.10.2