Added suite design guide, tidied doc directories.

.gitignore

@@ -2,16 +2,20 @@
 # python bytecode
 *.pyc
 
-# generated documentation
-doc/commands/
-doc/categories/
-doc/cylc.txt
-doc/commands.tex
-doc/graphics/png-scaled/
-doc/html/
-doc/pdf/
-doc/index.html
-doc/cylc-version.txt
+# Generated documentation files.
+# - User Guide.
+doc/src/cylc-user-guide/pdf
+doc/src/cylc-user-guide/html
+doc/src/cylc-user-guide/commands.tex
+doc/src/cylc-user-guide/cylc-version.txt
+# - Suite Design Guide.
+*.aux
+*.out
+*.pdf
+*.log
+*.toc
+# Installed docs.
+doc/install/
 
 # VERSION FILE
 VERSION

INSTALL.md

@@ -3,51 +3,57 @@
 **See [The Cylc User Guide](https://cylc.github.io/cylc/documentation.html) for
 detailed instructions.**
 
-Note: *to run distributed suites cylc must be installed on task hosts as well as suite
-hosts.*
+Cylc must be installed on task job hosts as well as suite hosts.
 
-### External Software Packages.
+### Required External Software Packages
 
-Several external packages required on suite hosts are not needed on task hosts:
-*graphviz*, and *pygraphviz*.  These should only need to be installed
-once, and then updated infrequently.
+These are only needed on suite hosts (not job hosts). They can be installed
+once and updated infrequently.
 
-### Installing Cylc Releases
+ * graphviz
+ * pygraphviz
 
-Download the latest release tarball from https://github.com/cylc/cylc/releases.
+### Installing Cylc
 
-Cylc releases should be installed in parallel under a top level `cylc`
-directory such as `/opt/cylc/` or `/home/admin/cylc/`.
+Download the latest tarball from https://github.com/cylc/cylc/releases.
 
 ```bash
 cd /home/admin/cylc/
-tar xzf ~/Downloads/cylc-6.10.0.tar.gz
-cd cylc-6.10.0
+tar xzf ~/Downloads/cylc-7.2.1.tar.gz
+# DO NOT CHANGE THE NAME OF THE UNPACKED CYLC SOURCE DIRECTORY.
+cd cylc-7.2.1
 export PATH=$PWD/bin:$PATH
 make  # (see below)
 ```
 
-Cylc is accessed via a central wrapper script can select between installed
-versions. This allows long-running suites to stick with older cylc versions
-if necessary. The wrapper should be modified slightly to point to your
-local installation (see comments in-script) and then installed (once) in
-`$PATH` for users, e.g.:
+Successive Cylc versions should be installed side-by-side under a location such
+as `/opt/cylc/` and invoked via a central wrapper that selects between the
+available versions. This allows long-running suites (and their task jobs) to
+stick with older Cylc versions if necessary. The wrapper should be edited to
+point to your Cylc install location made available to users, e.g. if
+`/usr/local/bin/` is in `$PATH`:
+
 ```bash
 cp admin/cylc-wrapper /usr/local/bin/cylc
+# (now edit 'cylc' as per in-file instructions...)
 ```
 
-When you type `make`: 
-  * A file called VERSION will be created to hold the cylc version string,
-  e.g. "6.10.0".  This is taken from the name of the parent directory: *do not
-  change the name of the unpacked cylc source directory*.
-  * The Cylc User Guide will be generated from LaTeX source files (in PDF if
-  `pdflatex` is installed, and HTML if `tex4ht` and *ImageMagick* are
-  installed).
+When you type `make`:
+  * A file called VERSION is created, containing the Cylc version number
+    * The version number is taken from the name of the parent directory: DO NOT
+      CHANGE THE NAME OF THE UNPACKED CYLC SOURCE DIRECTORY
+  * The Cylc documentation is generated from source and put in doc/install/
+
+### Installing The Documentation
+
+After running `make` you can copy the entire `doc/install` directory to a
+convenient location such as `/var/www/html/`, and update your Cylc site config 
+file to point to the intranet location.
 
 ### Cloning The Cylc Repository
 
-To get the latest bleeding-edge cylc version and participate in cylc
-development, fork [cylc on GitHub](https://github.com/cylc/cylc), clone your
-fork locally, develop changes locally in a new branch, then push the branch to
-your fork and issue a Pull Request to the cylc development team.  Please
-discuss proposed changes before you begin work, however.
+To participate in Cylc development fork [Cylc on
+GitHub](https://github.com/cylc/cylc) and clone it locally.  Changes should be
+developed in feature branches then pushed to your GitHub fork before issuing a
+Pull Request to the team. Please discuss proposed changes before you begin
+work.

Makefile

@@ -14,12 +14,12 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-all: version docs
+all: version documentation
 
 version:
 	admin/create-version-file
 
-docs:
+documentation:
 	cd doc && $(MAKE)
 
 clean:

doc/Makefile

@@ -16,63 +16,37 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-CYLC=$(dir $(abspath $(lastword $(MAKEFILE_LIST))))../bin/cylc
+.PHONY: all cug sdg cug-pdf cug-html clean install installclean
 
-.PHONY: all index clean html html-multi html-single pdf
+all: sdg cug install
 
-DEPS := $(shell ./scripts/get-deps.sh)
+sdg: src/suite-design-guide/document.pdf
 
-all: index
+cug: cug-pdf cug-html
+
+cug-pdf: src/cylc-user-guide/pdf/cug-pdf.pdf
 
-index: $(DEPS)
-	./scripts/make-index.sh
+cug-html: src/cylc-user-guide/html/single/cug-html.html \
+          src/cylc-user-guide/html/multi/cug-html.html
 
-html: html-multi html-single
+src/suite-design-guide/document.pdf:
+	cd src/suite-design-guide && $(MAKE)
 
-html-multi: html/multi/cug-html.html
+src/cylc-user-guide/pdf/cug-pdf.pdf:
+	cd src/cylc-user-guide && $(MAKE) pdf
 
-html-single: html/single/cug-html.html
+src/cylc-user-guide/html/single/cug-html.html:
+	cd src/cylc-user-guide && $(MAKE) html-single
 
-pdf: pdf/cug-pdf.pdf
+src/cylc-user-guide/html/multi/cug-html.html:
+	cd src/cylc-user-guide && $(MAKE) html-multi
 
+install:
+	./src/make-index.sh
 
-cylc.txt: ../bin/cylc
-	$< --help > $@
-
-cats = $(shell ../bin/cylc categories) 
-catx = $(cats:%=categories/%.txt)
-
-cmds = $(shell ../bin/cylc commands)
-cmdx = $(cmds:%=commands/%.txt)
-
-$(cmdx): commands/%.txt: ../bin/cylc-%
-	if test ! -d commands; then mkdir -p commands/; fi
-	$(patsubst ../bin/cylc-%,../bin/cylc %,$<) --help > $@
-
-$(catx): categories/%.txt: ../bin/cylc
-	if test ! -d categories; then mkdir -p categories/; fi
-	cylc $(subst .txt,,$(subst categories/,,$@)) --help > $@
-
-commands.tex: $(cmdx) $(catx) cylc.txt
-	./scripts/make-commands.sh
-
-html/multi/cug-html.html: commands.tex cug-html.tex cug.tex suiterc.tex siterc.tex gcylcrc.tex cug-html.cfg
-	./scripts/make-html.sh multi
-
-html/single/cug-html.html: commands.tex cug-html.tex cug.tex suiterc.tex siterc.tex gcylcrc.tex cug-html.cfg
-	./scripts/make-html.sh single
-
-pdf/cug-pdf.pdf: commands.tex cug-pdf.tex cug.tex suiterc.tex siterc.tex gcylcrc.tex
-	./scripts/make-pdf.sh
-
-# delete all generated files:
 clean:
-	rm -r pdf \
-	html \
-	cylc.txt \
-	commands \
-	categories \
-	commands.tex \
-	index.html \
-	cylc-version.txt
+	cd src/suite-design-guide && $(MAKE) clean
+	cd src/cylc-user-guide && $(MAKE) clean
 
+installclean:
+	rm -r install

doc/README

@@ -1,15 +1,23 @@
+------------------------------------------
+Cylc document generation from LaTeX source
+------------------------------------------
 
-To generate pdf and html (single and multi-page) Cylc User Guides:
+cug = Cylc User Guide
+sdg = Suite Design Guide
 
- | cd $CYLC_DIR/doc
- | make
+make all - create cug and sdg, and install to 'doc/install/'
 
-The following make targets are also avaialable:
- | make pdf
- | make html
- | make html-single
- | make html-multi
+make sdg - just create sdg (PDF)
 
-This will generate the documents under pdf/ and html/ sub-directories,
-and an index.html file at the top level that links to them.
+make cug - just create cug (PDF and HTML)
+make cug-pdf - just create cug-pdf
+make cug-html - just create cug-html (single and multi-page versions)
 
+make install - install created docs to 'doc/install/', create index.html
+make clean - remove all generated files (except those in 'doc/install/')
+make installclean - remove the 'doc/install/' directory
+
+-----------------------------------------------------------------------
+NOTE 'doc/install/' can be moved wholesale to another location (add the
+new location to your global.rc so that 'cylc doc' works properly).
+-----------------------------------------------------------------------