From dd0aacc45f9b0afb9031b0808797961e05a42b5d Mon Sep 17 00:00:00 2001
From: Ben Soares <b.soares@dundee.ac.uk>
Date: Fri, 4 Mar 2022 13:38:29 +0000
Subject: [PATCH] JAL-3830 Added new command line usage to docs

---
 help/help/html/features/commandline.html |   97 +++++++++++++++++++++++++++---
 1 file changed, 87 insertions(+), 10 deletions(-)

diff --git a/help/help/html/features/commandline.html b/help/help/html/features/commandline.html
index ac462e0..0159a92 100644
--- a/help/help/html/features/commandline.html
+++ b/help/help/html/features/commandline.html
@@ -33,20 +33,97 @@
     automatically by the Jalview application when double-clicked in a
     file browser on Windows and OSX.
   </p>
-  The way that you launch Jalview from the command line depends on the
-  platform you are on, and how it has been installed.
 
+  <p>From version 2.11.2, Jalview includes a <strong>launching shell script</strong> which is the recommended way to
+  launch an installed Jalview application from the command line.  It supports all the <a href="clarguments.html">command line arguments</a>
+  that Jalview has previously supported, but makes it easier to launch directly from the command line.</p>
+  
+  <p>There are some important differences between the using the launching script and launching Jalview from its icon:
   <ul>
-    <li>Standard installation on Linux/Unix:<pre>
-       /PATH_TO_JALVIEW/Jalview -open https://www.jalview.org/examples/jpred_msa.fasta -annotations https://www.jalview.org/examples/jpred_msa.seq.concise -colour Clustal</pre>
+  <li>The launching script will NOT look for updates or perform automatic updates.</li>
+  <li>The launching script cannot open or use JVL files.</li>
+  </ul>
+  </p>
+  
+  <p>If you installed Jalview prior to version 2.11.2 you will not have had the option to add the launching shell script to your PATH.
+  If your application has updated to 2.11.2 then the scripts will now be there, but not in your <code>PATH</code>.
+  There are instructions below to add the launching shell script to your <code>PATH</code> if you want to do so.</p>
+
+  <ul>
+  
+  <li>
+  <p><em>In <strong>Linux</strong> or <strong>Unix</strong> (<code>jalview.sh</code>)</em></p>
+  <p>The installer gives you the option of adding a symbolic link to
+  that script in your <code>$PATH</code>, if it finds a suitable place that your user can add such a
+  link (e.g. <code>~/bin</code>, <code>~/.local/bin</code>, <code>~/local/bin</code>, <code>~/opt/bin</code>).  If you chose that option then
+  you should be able to launch Jalview on the command line with the simple command
+  <pre>jalview</pre>
+  If you didn't choose that option during installation (or used an earlier version installer), or wish to make another symbolic link, you can link to the
+  launching shell script with the command
+  <pre>ln -s /PATH_TO_JALVIEW/bin/jalview.sh jalview</pre>
+  or you could add <code>/PATH_TO_JALVIEW/bin</code> to your own <code>$PATH</code> as it already contains a symbolic link <code>jalview</code>.
+  </li>
+  
+  <li>
+  <p><em>In <strong>Windows</strong> (<code>jalview.bat</code>, <code>jalview.ps1</code>)</em></p>
+  <p>The installer gives you the option of adding Jalview's script folder to your <code>%PATH%</code> allowing you to launch Jalview
+  in a Command Prompt simply with the command
+  <pre>jalview</pre>
+  If you didn't choose that option during installation (or used an earlier version installer), you can either
+  </p>
+  <ul>
+  <li>
+  add the <code>\PATH_TO_JALVIEW\bin</code> folder to your <code>%PATH%</code>, or
+  </li>
+  <li>
+  run the launcher script on the command line with its full path
+  <pre>\PATH_TO_JALVIEW\bin\jalview.bat</pre>
+  (you can leave off the <code>.bat</code> extension if you want).
+  </li>
+  </ul>
+  The <code>jalview.bat</code> file is a generic wrapper around the
+  PowerShell script <code>jalview.ps1</code> in the same folder.  This PowerShell script should work with both
+  PowerShell 5.x (which is installed by default on all modern Windows machines), and also PowerShell 6.0+
+  which might have been installed afterwards.
+  </li>
+  
+  <li>
+  <p><em>In <strong>macOS</strong> (<code>jalview</code>)</em></p>
+  <p>
+  The script you should use to launch Jalview is linked to as
+  <pre>/Applications/Jalview.app/Contents/MacOS/jalview</pre>
+  so you can run that command with its full path, or make your own symbolic link to there, or add that folder to your <code>$PATH</code>.
+  </p>
+  <p>
+  <em>If Jalview automatically updated from a version before 2.11.2</em> you will have to make a symbolic link to <code>/Applications/Jalview.app/Content/Resources/app/bin/jalview.sh</code> with the command
+  <pre>ln -s /Applications/Jalview.app/Content/Resources/app/bin/jalview.sh jalview</pre>
+  </p>
+  </li>
+ 
+  <li>
+  <p><em>Future</em></p>
+  A future version of Jalview will include a tool to allow adding these "<code>jalview</code>" links to your <code>PATH</code> automatically.
+  </li>
+  
+  </ul>
+
+  <p><strong>Older versions of Jalview</strong></p>
+  
+  <p>
+  If you are using a version of Jalview prior to 2.11.2, you can still launch from the command line, but you will have to
+  use a more platform specific way to launch and use command line arguments.
+
+  <ul>
+    <li>Standard installation on Linux/Unix:
+    <pre>/PATH_TO_JALVIEW/Jalview -open https://www.jalview.org/examples/jpred_msa.fasta -annotations https://www.jalview.org/examples/jpred_msa.seq.concise -colour Clustal</pre>
     </li>
-    <li>Standard installation on Windows:<pre>
-      \PATH_TO_JALVIEW\Jalview.exe -open %HOMEPATH%\myalignment.fa</pre>
+    <li>Standard installation on Windows:
+    <pre>\PATH_TO_JALVIEW\Jalview.exe -open %HOMEPATH%\myalignment.fa</pre>
     </li>
-    <li>OSX Application:<pre>
-open /Applications/Jalview.app --args -open ~/myalignment.fa</pre><em>(put
-        all the Jalview arguments <em>after</em> the --args parameter)
-    </em><br />
+    <li>OSX Application:
+    <pre>open /Applications/Jalview.app --args -open /FULL/PATH/TO/myalignment.fa</pre>
+    <em>(put all the Jalview arguments <em>after</em> the --args parameter, and note that paths to files should be full paths from <code>/</code>)</em>
+    <br />
     <br /></li>
     <li>Jalview standalone executable Jar<pre>
         &lt;Path to Java home&gt;/bin/java -jar &lt;Path to Jalview Jar&gt;/jalview-all-1.8.jar -open myalignment.fa</pre></li>
-- 
1.7.10.2