Update install docs. Close #2250.

CHANGES.md

@@ -71,6 +71,8 @@ suite daemons.
 [#2265](https://github.com/cylc/cylc/pull/2265): `cylc gpanel` - restored
 sorting of items by suite name.
 
+[#2250](https://github.com/cylc/cylc/issues/2250): Updated installation docs
+for HTTPS-related requirements.
 
 -------------------------------------------------------------------------------
 ## __cylc-7.3.0 (2017-04-10)__

INSTALL.md

@@ -18,13 +18,13 @@ These can be installed once on suite hosts updated infrequently.
 Download the latest tarball from https://github.com/cylc/cylc/releases.
 
 Successive Cylc releases should be installed side-by-side under a location such
-as `/opt/cylc/`:
+as `/opt`:
 
 ```bash
-cd /opt/cylc/
-tar xzf cylc-7.2.1.tar.gz
+cd /opt
+tar xzf cylc-7.4.0.tar.gz
 # DO NOT CHANGE THE NAME OF THE UNPACKED CYLC SOURCE DIRECTORY.
-cd cylc-7.2.1
+cd cylc-7.4.0
 export PATH=$PWD/bin:$PATH
 make
 ```
@@ -41,10 +41,16 @@ long-running suites (and their task jobs) to stick with older versions if
 necessary. The wrapper should be edited to point to the Cylc install location:
 
 ```bash
-cp /opt/cylc/cylc-7.2.1/admin/cylc-wrapper /usr/local/bin/cylc
+cp /opt/cylc-7.4.0/admin/cylc-wrapper /usr/local/bin/cylc
 # (now edit '/usr/local/bin/cylc' as per in-file instructions...)
 ```
 
+Finally, make a symlink to the latest installed version:
+```bash
+ln -s /opt/cylc-7.4.0 /opt/cylc
+```
+(This will be the default version invoked by the wrapper if a specific version is not requested via \lstinline=$CYLC_VERSION=.
+
 ### Installing The Documentation
 
 After running `make` you can copy the entire `doc/install` directory to a

doc/src/cylc-user-guide/cug.tex

@@ -388,13 +388,22 @@ \subsection{External Software Packages}
 {\bf Python \lstinline@>=@ 2.6} is required (but not yet Python 3). Python
 should already be installed in your Linux system. \url{https://python.org}.
 
+For Cylc's HTTPS communications layer:
+\begin{myitemize}
+  \item {\bf OpenSSL} - \url{https://www.openssl.org/}
+  \item {\bf pyOpenSSL} - \url{http://www.pyopenssl.org/}
+  \item {\bf python-requests} - \url{http://docs.python-requests.org/}
+  \item ({\bf python-urllib3} - should be bundled with python-requests)
+\end{myitemize}
+
 The following packages are highly recommended, but are technically optional as
 you can construct and run suites without dependency graph visualisation or
 the Cylc GUIs:
 
 \begin{myitemize}
-  \item {\bf PyGTK} - GUI toolkit (should be in your system Python):
-    \url{http://www.pygtk.org}.
+  \item {\bf PyGTK} - GUI toolkit \url{http://www.pygtk.org}.  {\em Note PyGTK
+    typically comes with your system Python. It is alledgedly quite
+    difficult to install if you need to do so for another Python version.}
     \item {\bf Graphviz} - graph layout engine (tested 2.36.0):
       \url{http://www.graphviz.org}.
     \item {\bf Pygraphviz} - Python Graphviz interface (tested 1.2):
@@ -455,7 +464,7 @@ \subsection{Software Bundled With Cylc}
     (recommended) or else pure Python via {\bf urllib2}.
 \newline \url{http://www.cherrypy.org/}
 \newline \url{http://docs.python-requests.org/}
-  \item {\bf Jinja2 2.8}: a full featured template engine for Python, and its
+  \item {\bf Jinja2 2.9.6}: a full featured template engine for Python, and its
     dependency {\bf MarkupSafe 0.23}; both BSD licensed.
 \newline \url{http://jinja.pocoo.org/}
 \newline \url{http://www.pocoo.org/projects/markupsafe/}
@@ -469,18 +478,24 @@ \subsection{Installing Cylc Itself}
 Cylc releases can be downloaded from from \url{https://cylc.github.io/cylc}.
 
 The wrapper script \lstinline=admin/cylc-wrapper= should be installed as
-\lstinline=cylc= somewhere in the system executable search path (e.g.\
+\lstinline=cylc= in the system executable search path (e.g.\
 \lstinline=/usr/local/bin/=) and modified slightly to point to a location
-such as \lstinline=/opt/cylc/= where successive Cylc releases will be unpacked
+such as \lstinline=/opt= where successive Cylc releases will be unpacked
 side by side.
 
 To install Cylc for the first time simply unpack the release tarball in that
-location, type \lstinline=make= in it, and set your site defaults in a
-site config file (below).
+location, e.g.\ \lstinline=/opt/cylc-7.4.0=, type \lstinline=make= inside
+the unpacked release directory, and set site defaults - if necessary - in a
+site global config file (below).
+
+In the installed location, make a symbolic link from \lstinline=cylc= to the
+latest installed version: \lstinline=ln -s /opt/cylc-7.4.0 cylc=. This is the
+version of Cylc that will be invoked by the central wrapper if a specific
+version is not requested e.g.\ by \lstinline@CYLC_VERSION=7.4.0@.
 
 Installing subsequent releases is just a matter of unpacking the new tarballs
 next to the previous releases, running \lstinline=make= in them, and copying
-in (possibly with modifications) the previous site config file.
+in (possibly with modifications) the previous site global config file.
 
 \subsubsection{Local User Installation}
 \label{LocalInstall}