From 4ccb1103e2ac2a0e588cc12cf8cae28bbe48bd2c Mon Sep 17 00:00:00 2001
From: Ben Soares <b.soares@dundee.ac.uk>
Date: Tue, 30 May 2023 11:36:12 +0100
Subject: [PATCH] JAL-629 JAL-4121 Added documentation to Help docs and Usage
 statement

---
 help/help/html/features/clarguments-basic.html     |    4 ++++
 help/help/html/features/clarguments-reference.html |   24 ++++++++++++++------
 help/help/html/features/clarguments.html           |   24 +++++++++++++++++---
 src/jalview/bin/argparser/Arg.java                 |    2 +-
 4 files changed, 43 insertions(+), 11 deletions(-)

diff --git a/help/help/html/features/clarguments-basic.html b/help/help/html/features/clarguments-basic.html
index 626fb8c..7a87602 100644
--- a/help/help/html/features/clarguments-basic.html
+++ b/help/help/html/features/clarguments-basic.html
@@ -408,6 +408,10 @@
   </pre>
   </p>
 
+  <p>
+  <em>Important!</em> If you use <code>--output</code> or any other argument that outputs a file, then it will be assumed you want to run Jalview in headless mode (as if you had specified <code>--headless</code>).  To use Jalview with <code>--output</code> and not assume headless mode, use the <code>--gui</code> or <code>--noheadless</code> argument (the order doesn't matter).
+  </p>
+
   <h3><a name="format"></a><code>--format</code></h3>
 
   <p>
diff --git a/help/help/html/features/clarguments-reference.html b/help/help/html/features/clarguments-reference.html
index 6d65033..6b98b7c 100644
--- a/help/help/html/features/clarguments-reference.html
+++ b/help/help/html/features/clarguments-reference.html
@@ -65,8 +65,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</code></td>
-    <td>Run Jalview in headless mode.  No GUI interface will be created and Jalview will quit after all arguments have been processed.</td>
+    <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.
+    <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>.
+    </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>
     </tr>
 
     <tr valign="top">
@@ -76,27 +84,27 @@
 
     <tr valign="top">
     <td><code>&#8209;&#8209;news / &#8209;&#8209;nonews</code></td>
-    <td>Show (or don't show) the news feed.</td>
+    <td>Show (/ or don't show) the news feed.</td>
     </tr>
 
     <tr valign="top">
     <td><code>&#8209;&#8209;splash / &#8209;&#8209;nosplash</code></td>
-    <td>Show (or don't show) the About Jalview splash screen.</td>
+    <td>Show (/ or don't show) the About Jalview splash screen.</td>
     </tr>
 
     <tr valign="top">
     <td><code>&#8209;&#8209;questionnaire / &#8209;&#8209;noquestionnaire</code></td>
-    <td>Show (or don't show) the questionnaire if one is available.</td>
+    <td>Show (/ or don't show) the questionnaire if one is available.</td>
     </tr>
 
     <tr valign="top">
     <td><code>&#8209;&#8209;usagestats / &#8209;&#8209;nousagestats</code></td>
-    <td>Send (or don't send) initial launch usage stats. <em>Note: usage stats are useful for future funding for Jalview!</em></td>
+    <td>Send (/ or don't send) initial launch usage stats. <em>Note: usage stats are useful for future funding for Jalview!</em></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>
+    <td>Attempt (/ or don't attempt) to connect to JABAWS web services.</td>
     </tr>
 
     <tr valign="top">
@@ -114,10 +122,12 @@
     <td>Stop all output to STDOUT (after the Java Virtual Machine has started).  Use <code>&#8209;&#8209;quiet</code> a second time to stop all output to STDERR.</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>
+-->
 
 <!--
     <tr valign="top">
diff --git a/help/help/html/features/clarguments.html b/help/help/html/features/clarguments.html
index 20bcd10..b763a81 100644
--- a/help/help/html/features/clarguments.html
+++ b/help/help/html/features/clarguments.html
@@ -32,6 +32,7 @@
   <ul>
   <li><a href="#introduction">Introduction</a></li>
   <li><a href="#syntax">Syntax</a></li>
+  <li><a href="#headlessmode">Headless mode</a></li>
   </ul>
 
   <h2><a name="introduction"></a>Introduction</h2>
@@ -105,9 +106,9 @@
         <br/>
         <code>--arg file1.fa otherfile.stk</code>
         <br/>
-        <code>--arg filename*.fa</code> <em>(expanded by shell)</em>
+        <code>--arg filename*.fa</code> <em>(filenames expanded by shell)</em>
         <br/>
-        <code>--arg=filename*.fa</code> <em>(expanded by Jalview)</em>
+        <code>--arg=filename*.fa</code> <em>(filenames expanded by Jalview)</em>
     </li>
     <li>
         For arguments that act as a switch, most can be negated by preceding the argument name with <code>no</code>.
@@ -149,9 +150,26 @@
   </p>
 
   <p>
-  This may sound complicated, but nearly everything can be done just with plain command line arguments, though in this case the ordering of the arguments is more important.
+  This may sound complicated, but nearly everything can be done just with plain command line arguments (see <a href="clarguments-basic.html">Command Line: basic usage</a>), though in this case the ordering of the arguments is more important.
   </p>
 
+
+  <h2><a name="headlessmode"></a>Headless mode</h2>
+
+  <p>
+  Jalview can be run in headless mode, i.e. without the usual graphical user interface (GUI), by specifying the <code>--headless</code> argument.  With command line arguments you can specify operations for Jalview to perform on one or more files and then stop running.  Most likely you will want to output another file, either an alignment for image file.
+  </p>
+  <p>
+  <strong>If you specify an argument for an output file</strong> (one or more of <code>--output</code>, <code>--image</code> or <code>--structureimage</code>) then it will be assumed that you wish to <strong>run in headless mode</strong>.
+  </p>
+  <p>
+  You can force Jalview to run in graphical mode using the <code>--gui</code> or <code>--noheadless</code> arguments.
+  </p>
+
+  <p>
+  </p>
+
+
   <hr/>
   Continue to <a href="clarguments-basic.html">Command Line: basic usage</a>.
   <br/>
diff --git a/src/jalview/bin/argparser/Arg.java b/src/jalview/bin/argparser/Arg.java
index 6c97ebc..0d6e3b1 100644
--- a/src/jalview/bin/argparser/Arg.java
+++ b/src/jalview/bin/argparser/Arg.java
@@ -374,7 +374,7 @@ public enum Arg
      * An OUTPUTFILE Arg provides an output filename. With Opt.ALLOWALL *.ext is shorthand for
      * --all --output={basename}.ext
      */
-    OUTPUTFILE("value is an output file"),
+    OUTPUTFILE("output file --headless will be assumed unless --gui used"),
     /*
      * A STORED Arg resets and creates a new set of "opened" linkedIds
      */
-- 
1.7.10.2