travis: update and improve documentation

travis/.travis.yml.example-full

@@ -1,6 +1,8 @@
-# .travis.xml for use with EPICS Base ci-scripts
+# .travis.yml for use with EPICS Base ci-scripts
 # (see: https://github.com/epics-base/ci-scripts)
 
+# This is YAML - indentation levels are crucial
+
 language: cpp
 compiler: gcc
 dist: xenial
@@ -24,6 +26,7 @@ addons:
     - clang
     # for mingw builds (32bit and 64bit)
     - g++-mingw-w64-i686
+    - g++-mingw-w64-x86-64
     # for RTEMS cross builds
     - qemu-system-x86
 
@@ -40,13 +43,20 @@ script:
 # Define build jobs
 
 # Well-known variables to use
-# BASE     branch or release tag name of the EPICS Base to use
+# SET      source setup file
 # EXTRA    content will be added to make command line
 # STATIC   set to YES for static build (default: NO)
 # TEST     set to NO to skip running the tests (default: YES)
 # VV       set to make build scripts verbose (default: unset)
 
-matrix:
+# Usually from setup files, but may be specified or overridden
+#  on a job line
+# MODULES  list of dependency modules
+# BASE     branch or release tag name of the EPICS Base to use
+# <MODULE> branch or release tag for a specific module
+# ...      see README for setup file syntax description
+
+jobs:
   include:
 
 # Different configurations of default gcc and clang
@@ -69,7 +79,7 @@ matrix:
   - env: BASE=7.0 EXTRA="CMD_CXXFLAGS=-std=c++11"
     dist: trusty
 
-# Cross-compilation to Windows using MinGW and WINE
+# Cross-compilations to Windows using MinGW and WINE
     
   - env: BASE=7.0 WINE=32 TEST=NO STATIC=YES
     compiler: mingw
@@ -83,7 +93,7 @@ matrix:
 
   - env: BASE=7.0 RTEMS=4.9 TEST=NO
 
-# Other gcc versions (adding as an extra package)
+# Other gcc versions (added as an extra package)
 
   - env: BASE=7.0
     compiler: gcc-6
@@ -99,8 +109,3 @@ matrix:
     os: osx
     compiler: clang
     addons: { homebrew: { packages: ["re2c"], update: true } }
-
-# All above jobs can be defined for other branches or releases of EPICS Base
-# by setting BASE to the branch name or release tag name, e.g.
-# BASE=3.15      (to use the 3.15 branch of Base)
-# BASE=R7.0.3    (to use the 7.0.3 release of Base)

travis/.travis.yml.example-mini

@@ -22,7 +22,7 @@ script:
 
 # Build using default gcc for Base branches 7.0 and 3.15
 
-matrix:
+jobs:
   include:
   - env: BASE=7.0
   - env: BASE=3.15

travis/README.md

@@ -31,7 +31,15 @@
     ```
 	
  5. Edit the `.travis.yml` configuration to include the jobs you want
-    Travis to run. (The examples are commented.)
+    Travis to run.
+
+    Build jobs are declared in the list following the `jobs: include:`
+    declaration. Each element (starting with `-` in column 3) defines the
+    settings for one build job. `env:` controls the setting of environment
+    variables,`dist:` specifies the Linux distribution,
+    `os:` the operating system.
+    Also see the comments in the examples for more hints, and the Travis-CI
+    documentation for more options and more details.
 	
  6. Push your changes and check
     [travis-ci.org](https://travis-ci.org/) for your build results.