Doc overhaul

src/7-to-8/caveats.rst

@@ -1,11 +1,11 @@
 Cylc |version| Caveats
 ======================
 
-This is an early release of Cylc, there are some loose ends and features which
+This is a beta release of Cylc. There are some loose ends and features which
 have not yet been (re)implemented.
 
-The documentation has not been fully reviewed and command line information may
-be out of date in some cases.
+The documentation has not been fully reviewed and the command line help may
+be out of date in some places.
 
 
 Cylc Flow
@@ -15,30 +15,19 @@ CLI Change
    We plan to move to a new way of specifying workflow, cycles, tasks and jobs
    on the command line (with back support for the old format).
 
-   This will open up performing operations on multiple workflows in a single
-   command e.g::
+   This will allow targetting of multiple workflows with a single command e.g::
 
       $ cylc stop '*'  # stop everything
 
    * https://github.com/cylc/cylc-flow/pull/3931
-Platform Selection
-   When Cylc needs to perform an action on a platform (e.g. submit a job)
-   it picks a random host from the platform. If this host is down the operation
-   will fail.
-
-   In a later relase Cylc will pick another host in order to provide resilience
-   to system issues.
-
-   * https://github.com/cylc/cylc-flow/issues/3827
 Trigger Edit
    Functionality removed pending reimplementation.
 
    * https://github.com/cylc/cylc-flow/issues/3743
 Reflow
-   The new "reflow" functionality which allows multiple
-   (potentially parallel) executions of the same workflow in a single
-   :term:`scheduler` is not fully supported by all commands and is
-   yet to be documented.
+   The new "reflow" functionality, which allows multiple
+   (potentially concurrent) executions of the same workflow in a single
+   :term:`scheduler`, is not fully supported by all commands or documented.
 
 
 Browser Based UI
@@ -53,8 +42,21 @@ Graph View
 
    * https://github.com/cylc/cylc-ui/issues/74
    * https://github.com/cylc/cylc-ui/issues/82
+
+Static Graph Visualization
+   Not yet been reimplemented for Cylc 8. As an interim measure the
+   ``cylc graph``` command can generate a basic PNG image of a workflow
+   graph if Graphviz is installed in the Cylc environment.
+
 Log Files
-   The ability to view job log and other files is yet to be implemented.
+   The ability to view job logs and other files in the web UI is yet to be
+   implemented. For the moment:
+
+   * use ``cylc cat-log``
+   * look in your ``cylc-run`` directory
+   * use Cylc Review from Cylc 7.9.5/7.8.10 (the latest version is compatible
+     with Cylc 8)
+
 Multiple Selection
    Multiple selection is yet to be implemented, however, it is possible
    to issue action for multiple tasks (e.g. ``kill``) without using
@@ -67,9 +69,8 @@ Multiple Selection
 
    * https://github.com/cylc/cylc-ui/issues/434
 Installing Workflows
-   At present there is no way to view non-installed workflows (a.k.a.
+   At present there is no way to view or install non-installed workflows (a.k.a.
    :term:`source workflows <source directory>`) in the UI.
-   We will add the ability to view and install source workflows from the UI.
 Rose Edit
    Rose Edit is awaiting reimplementation in the UI.
 Trigger Edit
@@ -101,7 +102,7 @@ Performance
 
    * https://github.com/cylc/cylc-flow/issues/3527
 GScan
-   The old ``cylc gscan`` command has been removed. You can now find the gscan
+   The old ``cylc gscan`` GUI has been removed. You can now find the gscan
    display on the left-hand side of the Cylc UI.
 
    In a future release ``cylc tui`` will be able to list workflows in a similar
@@ -114,10 +115,9 @@ UI Server
 ---------
 
 Authorisation
-   Only "binary" authorisation (i.e. no access / full control) is currently
-   supported.
+   A full-featured authorization system has been implemented for Cylc 8, but
+   the UI doesn't yet provide easy access to other users' UI Servers
 
-   * https://github.com/cylc/cylc-uiserver/issues/10
 CLI Via UIS
    The ability to route Cylc commands via the UIS is planned for a future relase
 

src/7-to-8/cheat-sheet.rst

@@ -16,7 +16,7 @@ Check the workflow configuration for errors:
 
    * - **Cylc 7**
      - **Rose 2019**
-     - **Cylc8** (Rose 2)
+     - **Cylc 8** (Rose 2)
    * - ::
 
          cylc validate <name/path>
@@ -38,7 +38,7 @@ Install a workflow from source and run it:
 
    * - **Cylc 7**
      - **Rose 2019**
-     - **Cylc8** (Rose 2)
+     - **Cylc 8** (Rose 2)
    * - ::
 
          # no installation capability
@@ -66,7 +66,7 @@ Tell a workflow not to submit any new jobs:
    :class: grid-table
 
    * - **Cylc 7** & Rose 2019
-     - **Cylc8** (Rose 2)
+     - **Cylc 8** (Rose 2)
    * - ::
 
          cylc hold <name>
@@ -95,7 +95,7 @@ Restart a stopped workflow and pick up where it left off:
 
    * - **Cylc 7**
      - **Rose 2019**
-     - **Cylc8** (Rose 2)
+     - **Cylc 8** (Rose 2)
    * - ::
 
          # no installation capability
@@ -128,7 +128,7 @@ Delete the workflow :term:`run directory` (leave source files untouched):
 
    * - **Cylc 7**
      - **Rose 2019**
-     - **Cylc8** (Rose 2)
+     - **Cylc 8** (Rose 2)
    * - ::
 
          rm -rf ~/cylc-run/<name>
@@ -160,7 +160,7 @@ View the parsed workflow configuration:
 
    * - **Cylc 7**
      - **Rose 2019**
-     - **Cylc8** (Rose 2)
+     - **Cylc 8** (Rose 2)
    * - ::
 
          cylc get-config --sparse \
@@ -188,7 +188,7 @@ for monitoring / controling running workflows:
 
    * -
      - **Cylc 7** & Rose 2019
-     - **Cylc8** (Rose 2)
+     - **Cylc 8** (Rose 2)
    * - Terminal
      - ::
 
@@ -200,13 +200,19 @@ for monitoring / controling running workflows:
      - ::
 
          cylc gui <name>
-     - * Open the Cylc Hub's URL in a web browser.
+     - * Run your own Cylc UI Server::
 
-       * Or alternatively run your own hub::
+           cylc gui
+
+         then open the printed URL in a web browser
+
+       * Or open your site's Cylc Hub URL in a web browser
+
+       * Or run your own Hub::
 
            cylc hub
 
-         Then open the URL ``0.0.0.0:8000`` in a web browser.
+         then open the URL ``0.0.0.0:8000`` in a web browser
 
 Static Graph Visualisation
 --------------------------
@@ -217,43 +223,17 @@ Generate a visualisation for a workflow without running it:
    :class: grid-table
 
    * - **Cylc 7** & Rose 2019
-     - **Cylc8** (Rose 2)
+     - **Cylc 8** (Rose 2)
    * - ::
 
          cylc graph <name>
-     - Not yet implemented. As a temporary workaround Graphviz can be used
-       to render ``cylc graph --reference`` output like so:
-
-       .. code-block:: bash
-
-          #!/usr/bin/env bash
-
-          set -eu
-
-          SUITE="$1"
-          FMT="$2"
-
-          TMP=dotfile
-
-          cylc graph --reference "$SUITE" 2>/dev/null > "$TMP.ref"
-
-          sed \
-              -e 's/node "\(.*\)" "\(.*\)"/"\1" [label="\2"]/' \
-              -e 's/edge "\(.*\)" "\(.*\)"/"\1" -> "\2"/' \
-              -e '1i digraph {' \
-              -e '$a}' \
-              -e '/^graph$/d' \
-              -e '/^stop$/d' \
-              "$TMP.ref" \
-              > "$TMP.dot"
+     - ::
 
-          dot \
-              "$TMP.dot" \
-              -T$FMT \
-              -o "$TMP.$FMT"
+         cylc graph <name>
+
+       This generates a basic image file if Graphviz is installed.
 
-          rm "$TMP.ref" "$TMP.dot"
-          echo "$TMP.$FMT"
+       The web UI will have full graph vis. in a future release.
 
 Rose Stem
 ---------
@@ -264,7 +244,7 @@ Run a :ref:`rose:Rose Stem` test suite.
    :class: grid-table
 
    * - **Rose 2019**
-     - **Rose 2** (Cylc8)
+     - **Rose 2** (Cylc 8)
    * - ::
 
          # install and start

src/7-to-8/major-changes/before-you-start.rst

@@ -13,7 +13,8 @@ Overview
 --------
 
 Cylc has a built in configuration upgrader. **Cylc 8** can upgrade Cylc 7
-workflows at runtime, but not if validation with Cylc 7 gives deprecation warnings.
+workflows on the fly if they use up-to-date Cylc 7 syntax, but *not
+if validation with Cylc 7 gives deprecation warnings*.
 
 Solution
 --------
@@ -113,7 +114,7 @@ Host to platform upgrade logic
    .. TODO reference to how to write platforms page
 
 If you have a Cylc 7 workflow where tasks submit jobs to remote hosts
-Cylc 8 will attempt to find a platform which matches the task specfication.
+Cylc 8 will attempt to find a platform which matches the task specification.
 
 .. important::
 

src/7-to-8/major-changes/cylc-install.rst

@@ -14,10 +14,10 @@ Cylc Install
 
    This change will affect you:
 
-   - If you usually develop your Cylc workflows in the ``~/cylc-run`` directory.
-   - If you develop your code outside the ``~/cylc-run`` directory and manually
-     copied to ``~/cylc-run``.
-   - If you use ``rose suite-run``.
+   - If you usually develop Cylc workflows in the ``~/cylc-run`` directory.
+   - If you develop Cylc workflows outside of the ``~/cylc-run`` directory and manually
+     copy the files to ``~/cylc-run``.
+   - If you use ``rose suite-run`` to install and run Cylc workflows.
 
 Overview
 --------
@@ -26,7 +26,7 @@ Cylc 7 ran workflows in ``~/cylc-run/``. You could develop your
 workflow in ``~/cylc-run`` or copy it after developing it elsewhere.
 If you developed in the ``~/cylc-run`` directory there was a risk that
 Cylc might alter your files. If you developed elsewhere you needed to
-install your workflow with another tool.
+install your workflows manually or with another tool.
 
 We designed Cylc 8 to help you keep your development and
 running copies separate. By default you can now develop workflows in the
@@ -48,21 +48,21 @@ You can install from inside the development directory:
 
    > cd ~/cylc-src/my-workflow
    > cylc install
-   INSTALLED my-workflow/run1 from /home/me/cylc-src/my-wf
+   INSTALLED my-workflow/run1 from /home/me/cylc-src/my-workflow
 
 You can install by workflow name if the workflow is in ``~/cylc-src``.
 
 .. code-block:: bash
 
    > cylc install my-workflow
-   INSTALLED my-workflow/run2 from /home/me/cylc-src/my-wf
+   INSTALLED my-workflow/run2 from /home/me/cylc-src/my-workflow
 
 .. note::
 
    Each time you run ``cylc install`` a new copy of the workflow is installed
-   in a new directory,
-   in the previous case this directory is ``run2``. ``cylc install`` also creates
-   a symlink from the most recently installed run directory to ``~/cylc-run/<my_workflow>/runN``.
+   to a new run directory. In the previous case this is the ``run2`` directory.
+   ``cylc install`` also creates a symlink from the most recently installed run
+   directory to ``~/cylc-run/<my_workflow>/runN``.
 
 You can also use ``-C`` (or ``--directory``) to set a source path:
 

src/7-to-8/major-changes/platforms.rst

@@ -91,7 +91,7 @@ Examples
 Showing how the global config changes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-At Cylc 7:
+This Cylc 7 workflow:
 
 .. code-block:: cylc
 
@@ -103,15 +103,15 @@ At Cylc 7:
            [[[remote]]]
                host = login_node01
 
-Would, at Cylc 8 become:
+Would, at Cylc 8, become:
 
 .. code-block:: cylc
 
    [runtime]
        [[mytask]]
            platform = our_cluster
 
-While at Cylc 8 the global config might contain:
+And the Cylc 8 global config might contain:
 
 .. code-block:: cylc
 
@@ -155,7 +155,7 @@ This will result in Cylc running:
 - ``mytask_login_to_hpc_and_submit`` on a host set by the subshelled
   script using Slurm.
 
-In Cylc 8 the equivalent might be:
+At Cylc 8 the equivalent might be:
 
 .. code-block:: cylc
 
@@ -172,7 +172,7 @@ In Cylc 8 the equivalent might be:
            # This is still legal, but you could also use host selection.
            platform = $(supercomputer_login_node_selector_script)
 
-The platform settings for these examples might be:
+And the platform settings for these examples might be:
 
 .. code-block:: cylc
 

src/7-to-8/major-changes/suicide-triggers.rst

@@ -16,7 +16,7 @@ Overview
 --------
 
 In Cylc 7 :term:`suicide triggers <suicide trigger>` are used to remove
-tasks from the graph automatically whilst a workflow is running.
+tasks from the graph automatically at runtime.
 
 Cylc 8 handles :term:`graphs <graph>` in an event-driven manner which means
 that a workflow can follow different paths in different eventualities without