From 0ac3a6e702701f6cd46f830cfe4b0a68b71958ed Mon Sep 17 00:00:00 2001
From: Jim Procter <j.procter@dundee.ac.uk>
Date: Fri, 4 Mar 2022 15:26:03 +0000
Subject: [PATCH] JAL-3608 JAL-3830  simplified command line docs a bit

---
 help/help/html/features/commandline.html |   77 ++++++++++++++++++++----------
 1 file changed, 51 insertions(+), 26 deletions(-)

diff --git a/help/help/html/features/commandline.html b/help/help/html/features/commandline.html
index 0159a92..2ffe0bc 100644
--- a/help/help/html/features/commandline.html
+++ b/help/help/html/features/commandline.html
@@ -28,32 +28,52 @@
   </p>
   <p>
     Jalview can be run from the command line, and provides a <a
-      href="clarguments.html">range of arguments</a>. These arguments
-    can also be passed via <strong>.JVL</strong> files, which are opened
-    automatically by the Jalview application when double-clicked in a
-    file browser on Windows and OSX.
+      href="clarguments.html">range of arguments</a>.
   </p>
-
-  <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 a few different ways to do this:</p>
+  <ul>
+    <li>Use the <strong>jalview</strong> command that links to a <strong>launch
+        script</strong>. Launch scripts are available if you are running an up to
+      date version of Jalview (at least 2.11.2.0), or have installed
+      Jalview via a package manager (e.g. conda, homebrew, apt).
+    </li>
+    <li>Embed arguments in a <strong>.JVL</strong> file. These
+      files will be opened automatically by the Jalview application when
+      double-clicked in a file browser on Windows and OSX.
+    </li>
+    <li>Execute the Jalview standalone Jar file with an existing
+      Java installation</li>
+      <li>For older versions of Jalview, call the <a href="#olderinstalls">native launch program directly</a>.
+  </ul>
+  <p>
+    <strong><a name="script">Jalview's command line launch
+        script</a></strong>
+  <p>Since version 2.11.2, the Jalview native application includes a <strong>launching shell script</strong>. This is the easiest way to
+  launch an installed Jalview application from the command line. </p><p>To run the <strong>launch script</strong>, simply open a Terminal (or Command prompt on Windows), and type:<pre>
+  jalview</pre>
+  
   
   <p>There are some important differences between the using the launching script and launching Jalview from its icon:
+  </p>
   <ul>
-  <li>The launching script will NOT look for updates or perform automatic updates.</li>
+  <li>The launching script will NOT perform automatic updates.</li>
   <li>The launching script cannot open or use JVL files.</li>
   </ul>
+
+  <em><strong>Adding the launch script to your path</strong></em>
+  <p>
+    If typing 'jalview' in the terminal prompt (or windows command line)
+    doesn't work then you will need to add the location of the jalview
+    launch script to your
+    <code>PATH</code>.</p><p>
+    How you do this depends on your operating system.
   </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
+  <p>Running the Linux installer will give 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
@@ -66,7 +86,7 @@
   
   <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
+  <p>The Windows installer will give 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
@@ -90,24 +110,29 @@
   <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
+  We don't currently provide a macOS installer program, so you will need to add the command to you path manually. 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>
+    <p>
+      If you cannot see the
+      <code>jalview</code>
+      command in the MacOS directory, then you probably have an older
+      Jalview installation. In that case, you should make a symbolic
+      link directly to the launch script with the command
+    <pre>ln -s /Applications/Jalview.app/Content/Resources/app/bin/jalview.sh jalview</pre>
+    <em>If this doens't work, check your installation is running
+      Jalview 2.11.2.0 or later.</em>
+    </p>
   </li>
- 
-  <li>
-  <p><em>Future</em></p>
+ </ul>
+<!--  <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><strong><a name="olderinstalls">Older versions of Jalview</a></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
@@ -122,7 +147,7 @@
     </li>
     <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>
+    <em>(put all the Jalview arguments <em>after</em> the --args parameter, and note that <strong>all files must be specified with their full paths</strong>)</em>
     <br />
     <br /></li>
     <li>Jalview standalone executable Jar<pre>
-- 
1.7.10.2