[WIP] Review Docs in light of config changes

src/tutorial/scheduling/graphing.rst

@@ -13,7 +13,7 @@ The :cylc:conf:`flow.cylc` File Format
 
 .. ifnotslides::
 
-   We refer to a Cylc workflow as a :term:`Cylc suite`. A Cylc suite is a
+   We refer to a Cylc workflow as a :term:`Cylc workflow`. A Cylc suite is a
    directory containing a :cylc:conf:`flow.cylc` file. This configuration file is where
    we define our workflow. The :cylc:conf:`flow.cylc` file uses a nested `INI`_-based
    format:
@@ -243,7 +243,7 @@ Cylc Graphs
 
 .. ifnotslides::
 
-   In a :term:`Cylc suite` the :term:`graph` is stored under the
+   In a :term:`Cylc workflow` the :term:`graph` is stored under the
    ``[scheduling][graph]R1`` setting, i.e:
 
 .. code-block:: cylc
@@ -259,7 +259,7 @@ Cylc Graphs
 
 .. ifnotslides::
 
-   This is a minimal :term:`Cylc suite`, in which we have defined a
+   This is a minimal :term:`Cylc workflow`, in which we have defined a
    :term:`graph` representing a workflow for Cylc to run.
    We have not yet provided Cylc with the scripts or binaries to run for
    each task. This will be covered later in the

src/tutorial/scheduling/integer-cycling.rst

@@ -404,7 +404,7 @@ Recurrence Sections
 
 .. practical::
 
-   .. rubric:: In this practical we will take the :term:`suite <Cylc suite>`
+   .. rubric:: In this practical we will take the :term:`workflow <Cylc workflow>`
       we wrote in the previous section and turn it into a
       :term:`cycling suite <cycling>`.
 

src/user-guide/external-triggers.rst

@@ -153,13 +153,13 @@ the ``cylc suite-state`` command - see
 As a simple example, consider the following "upstream"
 suite (which we want to trigger off of):
 
-.. literalinclude:: ../suites/xtrigger/suite_state/upstream/flow.cylc
+.. literalinclude:: ../workflows/xtrigger/suite_state/upstream/flow.cylc
    :language: cylc
 
 It must be registered and run under the name *up*, as referenced in the
 "downstream" suite that depends on it:
 
-.. literalinclude:: ../suites/xtrigger/suite_state/downstream/flow.cylc
+.. literalinclude:: ../workflows/xtrigger/suite_state/downstream/flow.cylc
    :language: cylc
 
 Try starting the downstream suite first, then the upstream, and
@@ -380,7 +380,7 @@ the appropriate string templates in the suite configuration for this).
 
 An example xrandom trigger suite:
 
-.. literalinclude:: ../suites/xtrigger/xrandom/flow.cylc
+.. literalinclude:: ../workflows/xtrigger/xrandom/flow.cylc
    :language: cylc
 
 .. _Current Trigger Function Limitations:
@@ -485,7 +485,7 @@ the new event. The suite passphrase must be installed on triggering account.
 
 Here is a working example of a simulated satellite processing suite:
 
-.. literalinclude:: ../suites/satellite/ext-trigger/flow.cylc
+.. literalinclude:: ../workflows/satellite/ext-trigger/flow.cylc
    :language: cylc
 
 External triggers are not normally needed in date-time cycling suites driven

src/user-guide/index.rst

@@ -6,8 +6,8 @@ User Guide
    :maxdepth: 2
 
    workflows
-   writing-suites/index
-   running-suites
+   writing-workflows/index
+   running-workflows
    suite-name-reg
    suite-storage-etc
    task-implementation

src/user-guide/running-suites.rst → src/user-guide/running-workflows.rst

@@ -571,7 +571,7 @@ queue. The *queues* example suite illustrates how queues work by
 running two task trees side by side each
 limited to 2 and 3 tasks respectively:
 
-.. literalinclude:: ../suites/queues/flow.cylc
+.. literalinclude:: ../workflows/queues/flow.cylc
    :language: cylc
 
 
@@ -602,7 +602,7 @@ Task Event Handling
 * Task events (e.g. task succeeded/failed) are configured by
   :cylc:conf:`task events <[runtime][<namespace>][events]>`.
 * Suite events (e.g. suite started/stopped) are configured by
-  :cylc:conf:`suite events <[cylc][events]>`
+  :cylc:conf:`suite events <[scheduler][events]>`
 
 .. cylc-scope:: flow.cylc[runtime][<namespace>]
 
@@ -644,14 +644,13 @@ These can be configured using the settings:
 
 - :cylc:conf:`[mail]to` (list of email addresses)
 - :cylc:conf:`[mail]from`
-- :cylc:conf:`[mail]smtp`
 
 .. cylc-scope::
 
 By default, a cylc suite will send you no more than one task event email every
 5 minutes - this is to prevent your inbox from being flooded by emails should a
 large group of tasks all fail at similar time. This is configured by
-:cylc:conf:`[cylc][mail]task event batch interval`.
+:cylc:conf:`[scheduler][mail]task event batch interval`.
 
 Event handlers can be located in the suite ``bin/`` directory;
 otherwise it is up to you to ensure their location is in ``$PATH`` (in
@@ -694,7 +693,7 @@ Event handler arguments can be constructed from various templates
 representing suite name; task ID, name, cycle point, message, and submit
 number name; and any :cylc:conf:`suite <[meta]>` or
 :cylc:conf:`task <[runtime][<namespace>][meta]>` item.
-See :cylc:conf:`suite events <[cylc][events]>` and
+See :cylc:conf:`suite events <[scheduler][events]>` and
 :cylc:conf:`task events <[runtime][<namespace>][events]>` for options.
 
 If no template arguments are supplied the following default command line
@@ -811,12 +810,12 @@ Job submission commands, event handlers, and job poll and kill commands, are
 executed by the :term:`scheduler` in a "pool" of asynchronous
 subprocesses, in order to avoid holding the suite up. The process pool is
 actively managed to limit it to a configurable size
-:cylc:conf:`global.cylc|process pool size`
+:cylc:conf:`global.cylc[scheduler]process pool size`
 Custom event handlers should be light-weight and quick-running because they
 will tie up a process pool member until they complete, and the suite will
 appear to stall if the pool is saturated with long-running processes. Processes
 are killed after a configurable timeout
-:cylc:conf:`global.cylc|process pool timeout`
+:cylc:conf:`global.cylc[scheduler]process pool timeout`
 , however,
 to guard against rogue commands that hang indefinitely. All process kills are
 logged by the :term:`scheduler`. For killed job submissions the associated

src/user-guide/writing-suites/configuration.rst → src/user-guide/writing-workflows/configuration.rst

@@ -3,9 +3,9 @@
 Workflow Configuration
 ======================
 
-Cylc suites are defined in structured, validated, :cylc:conf:`flow.cylc`
+Cylc workflows are defined in structured, validated, :cylc:conf:`flow.cylc`
 files that concisely specify the properties of, and the relationships
-between, the various tasks managed by the suite.
+between, tasks managed by the workflow.
 
 Here we will look at:
 
@@ -14,12 +14,12 @@ Here we will look at:
 - How to configure workflows.
 
 
-.. _SuiteDefinitionDirectories:
+.. _WorkflowDefinitionDirectories:
 
-Suite Configuration Directories
--------------------------------
+Workflow Configuration Directories
+----------------------------------
 
-A Cylc :term:`suite directory` contains:
+A Cylc :term:`workflow directory` contains:
 
 :cylc:conf:`flow.cylc`
    The file which configures the workflow.
@@ -38,7 +38,7 @@ A Cylc :term:`suite directory` contains:
    - Custom :ref:`job submission modules <CustomJobSubmissionMethods>`.
    - Custom :ref:`Jinja2 Filters<CustomJinja2Filters>`).
 
-Other files and folders may be placed in the :term:`suite directory` e.g.
+Other files and folders may be placed in the :term:`workflow directory` e.g.
 documentation, configuration files, etc.
 
 
@@ -86,19 +86,19 @@ The following defines legal :cylc:conf:`flow.cylc` syntax:
 - **Include-files** ``%include inc/foo.cylc`` can be
   used as a verbatim inlining mechanism.
 
-Suites that embed templating code (see :ref:`User Guide Jinja2` and
+Workflows that embed templating code (see :ref:`User Guide Jinja2` and
 :ref:`User Guide EmPy`) must process to raw :cylc:conf:`flow.cylc` syntax.
 
 
 Include-Files
 ^^^^^^^^^^^^^
 
 Cylc has native support for :cylc:conf:`flow.cylc` include-files, which may help to
-organize large suites. Inclusion boundaries are completely arbitrary -
+organize large workflows. Inclusion boundaries are completely arbitrary -
 you can think of include-files as chunks of the :cylc:conf:`flow.cylc` file simply
 cut-and-pasted into another file. Include-files may be included
 multiple times in the same file, and even nested. Include-file paths
-can be specified portably relative to the suite configuration directory,
+can be specified portably relative to the workflow configuration directory,
 e.g.:
 
 .. code-block:: cylc
@@ -118,18 +118,18 @@ e.g.:
 
    .. code-block:: bash
 
-      $ cylc edit --inline SUITE
+      $ cylc edit --inline WORKFLOW
 
-   The suite will be split back into its constituent include-files when you
+   The workflow will be split back into its constituent include-files when you
    exit the edit session. While editing, the inlined file becomes the
-   official suite configuration so that changes take effect whenever you save
+   official workflow configuration so that changes take effect whenever you save
    the file. See ``cylc prep edit --help`` for more information.
 
 
 .. _SyntaxHighlighting:
 
-Syntax Highlighting For Suite Configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax Highlighting For Workflow Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Cylc provides syntax plugins for the following editors:
 
@@ -173,11 +173,11 @@ WebStorm
 Gross File Structure
 ^^^^^^^^^^^^^^^^^^^^
 
-Cylc :cylc:conf:`flow.cylc` files consist of a suite title and description followed by
+Cylc :cylc:conf:`flow.cylc` files consist of a workflow title and description followed by
 configuration items grouped under several top level section headings:
 
-:cylc:conf:`[cylc]`
-   Non task-specific suite configuration.
+:cylc:conf:`[scheduler]`
+   Non task-specific workflow configuration.
 :cylc:conf:`[scheduling]`
    Determines when tasks are ready to run.
 
@@ -189,11 +189,11 @@ configuration items grouped under several top level section headings:
    Determines how, where, and what to execute when tasks are ready
 
    - script, environment, job submission, remote hosting, etc.
-   - suite-wide defaults in the *root* namespace
+   - workflow-wide defaults in the *root* namespace
    - a nested family hierarchy with common properties
      inherited by related tasks
 :cylc:conf:`[visualization]`
-   Suite graph styling
+   Workflow graph styling
 
 .. _Validation:
 
@@ -210,6 +210,6 @@ These checks are also performed by ``cylc run`` before starting a workflow.
 All legal entries are documented in :cylc:conf:`flow.cylc`.
 
 If the :cylc:conf:`flow.cylc` file uses include-files ``cylc view`` will
-show an inlined copy of the suite with correct line numbers
-(you can also edit suites in a temporarily inlined state with
+show an inlined copy of the workflow with correct line numbers
+(you can also edit workflows in a temporarily inlined state with
 ``cylc edit --inline``).

src/user-guide/writing-suites/empy.rst → src/user-guide/writing-workflows/empy.rst

@@ -30,7 +30,7 @@ An example suite ``empy.cities`` demonstrating its use is shown below.
 It is a translation of ``jinja2.cities`` example from
 :ref:`User Guide Jinja2` and can be directly compared against it.
 
-.. literalinclude:: ../../suites/empy/cities/flow.cylc
+.. literalinclude:: ../../workflows/empy/cities/flow.cylc
    :language: cylc
 
 For basic usage the difference between Jinja2 and EmPy amounts to a different

src/user-guide/writing-suites/jinja2.rst → src/user-guide/writing-workflows/jinja2.rst

@@ -91,7 +91,7 @@ suite. To add a new city and associated tasks and dependencies simply
 add the city name to list at the top of the file. Here is the suite graphed,
 with the New York City task family expanded:
 
-.. literalinclude:: ../../suites/jinja2/cities/flow.cylc
+.. literalinclude:: ../../workflows/jinja2/cities/flow.cylc
    :language: cylc
 
 .. _fig-jinja2-cities:
@@ -246,7 +246,7 @@ The values of Jinja2 variables can be passed in from the Cylc command
 line rather than hardwired in the suite configuration.
 Here's an example:
 
-.. literalinclude:: ../../suites/jinja2/defaults/flow.cylc
+.. literalinclude:: ../../workflows/jinja2/defaults/flow.cylc
    :language: cylc
 
 Here's the result: