Merge of work to build and deploy teaching guidelines document in mul…

…tiple formats (cplusplus#70)

* Added a new attempt at a revised "Guidelines for Teaching C++" document.

* Added some information to the README document and made some corrections
to the main document.

* Document:
Revised some of the information in the introductory sections.
Added the information for the topic on static_assert.
Fixed a few places in the document that were using incorrect terminology.
Changed some of the symbols used in the module/topic tables.

* Fixed some labelling-related issues in the document.

* Made a few minor wording changes to the section on contributing.

* Added two WG21 papers to the references section.

* Added a logo to the document title and made a few other minor changes
to the document.
Performed some clean up on the makefile and added a few comments to it
as well.
Added some comments and better error messages to the document build script.
Made numerous improvements to the document deploy script (e.g., added
usage information and added a few comments).
Added some comments to the GitHub workflow files.

* Added some examples to the usage information for the document
build and deploy scripts.
Fixed a bug in the deploy script introduced by earlier changes.

* Changed the document deploy script so that it no longer creates a
top-level index.html file in the target repository.

* Changed the target of the symlink for the latest version of the
document in the document deploy script.

* Removed an outdated link from the document.

* Made a few improvements to the document deploy script.

* Added the creation of a top-level index.html file for the GitHub Pages
site.

* Added the deployment of built document to the same repository.

* Corrected some typos in a workflow file.

* Fixed a bug in the deploy script associated with the handling of the
case that the gh-pages branch does not yet exist.

* Fix a bug in the deploy script.

* Fix bug in deploy script.

* Testing.

* Testing.

* Testing.

* Testing.

* Made changes to file layout.

* More reorganizing.

* Testing.

* Testing.

* Revised README.

* Replaced HTML markup for tables with the corresponding Markdown markup
in several document source files.

* Added the missing license text.

* Pulled contributor names from the Git repository revision history.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Testing.

* Add missing files.

* Added a description of the repository organization to the top-level
README document.

* Made some minor editorial changes to the top-level README.

* Fixed a typo in the README.

* Fixed wording/spelling in README document.

* Added preliminary support for the use of an access token for
authentication during deployment.

* Fixed a typo in the deploy script.

* Made more changes to the deploy script.

* Made another change to the deploy script.

* Made some editorial changes to the GitHub Actions workflow files.

* Commented out some obsolete/unused lines in the release workflow file.

* Added mention of some new links in the teaching guidelines document.

* Added mention of a new link in the teaching guidelines document.

* Removed the copy elision module that is neither complete nor approved
for inclusion in the guidelines document.

* Removed an obsolete entry in the knowledge areas file.

* Moved some files around in order to facilitate easier merging.

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+# This action is used to perform a test build of the document that includes
+# performing spell checking.
+
+name: ci
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    ############################################################
+    - name: Prepare to build the document.
+      shell: bash
+      run: tools/build/prebuild
+    ############################################################
+    - name: Build the document.
+      shell: bash
+      run: |
+        tools/build/build \
+          -d ${{runner.temp}}/output \
+          -z ${{github.ref}} \
+          -s
+    ############################################################

.github/workflows/release.yml

@@ -0,0 +1,79 @@
+# This is an action that builds the document and deploys the build document
+# to its associated GitHub pages site.
+
+name: release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    ############################################################
+    - name: Prepare to build the document.
+      shell: bash
+      run: tools/build/prebuild
+    ############################################################
+    # The following builds the document in multiple formats for deployment.
+    - name: Build the document.
+      shell: bash
+      run: |
+        tools/build/build \
+          -d ${{runner.temp}}/output \
+          -z ${{github.ref}}
+    ############################################################
+    # The following deploys to a different branch of the same repository
+    # using an access token for authentication.
+    # Note: It is recommended that this approach not be used.
+    #- name: Deploy the built document to a GitHub Pages branch.
+    #  env:
+    #    DEPLOY_TOKEN: ${{secrets.DEPLOY_TOKEN}}
+    #  shell: bash
+    #  run: |
+    #    tools/build/deploy \
+    #      -f \
+    #      -m token \
+    #      -t ${{runner.temp}}/deploy_tmp \
+    #      -i ${{runner.temp}}/output \
+    #      -r mdadams/SG20 \
+    #      -b gh-pages \
+    #      -z ${{github.ref}}
+    ############################################################
+    # The following deploys to a different branch of the same repository
+    # using a deploy (i.e., SSH) key for authentication.
+    - name: Deploy the built document to a GitHub Pages branch.
+      env:
+        DEPLOY_KEY: ${{secrets.DEPLOY_KEY}}
+      shell: bash
+      run: |
+        tools/build/deploy \
+          -f \
+          -m key \
+          -t ${{runner.temp}}/deploy_tmp \
+          -i ${{runner.temp}}/output \
+          -r mdadams/SG20 \
+          -b gh-pages \
+          -z ${{github.ref}}
+    ############################################################
+    # The following deploys to a branch of a different repository
+    # using a deploy (i.e., SSH) key authentication.
+    - name: Deploy the built document to a GitHub Pages branch.
+      env:
+        DEPLOY_KEY: ${{secrets.ALT_DEPLOY_KEY}}
+      shell: bash
+      run: |
+        tools/build/deploy \
+          -f \
+          -m key \
+          -t ${{runner.temp}}/deploy_tmp_2 \
+          -i ${{runner.temp}}/output \
+          -r mdadams/sg20_guidelines_for_teaching_cpp \
+          -b gh-pages \
+          -z ${{github.ref}}
+    ############################################################

LICENSE.txt

@@ -0,0 +1,41 @@
+Copyright (c) Standard C++ Foundation and its contributors
+
+Standard C++ Foundation grants you a worldwide, nonexclusive, royalty-free,
+perpetual license to copy, use, modify, and create derivative works from this
+project for your personal or internal business use only. The above copyright
+notice and this permission notice shall be included in all copies or
+substantial portions of the project. This license does not grant permission
+to use the trade names, trademarks, service marks, or product names of the
+licensor, except as required for reasonable and customary use in describing
+the origin of the project.
+
+Standard C++ Foundation reserves the right to accept contributions to the
+project at its discretion.
+
+By contributing material to this project, you grant Standard C++ Foundation,
+and those who receive the material directly or indirectly from Standard C++
+Foundation, a perpetual, worldwide, non-exclusive, royalty-free, irrevocable,
+transferrable license to reproduce, prepare derivative works of, publicly
+display, publicly perform, and distribute your contributed material and such
+derivative works, and to sublicense any or all of the foregoing rights to third
+parties for commercial or non-commercial use.  You also grant Standard C++
+Foundation, and those who receive the material directly or indirectly from
+Standard C++ Foundation, a perpetual, worldwide, non-exclusive, royalty-free,
+irrevocable license under your patent claims that directly read on your
+contributed material to make, have made, use, offer to sell, sell and import
+or otherwise dispose of the material. You warrant that your material is your
+original work, or that you have the right to grant the above licenses.
+
+THE PROJECT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE PROJECT OR THE USE OR OTHER DEALINGS IN THE
+PROJECT.
+
+If you believe that anything in the project infringes your copyright, please
+contact us at [email protected] with your contact information and a detailed
+description of your intellectual property, including a specific URL where you
+believe your intellectual property is being infringed.
+

Makefile

@@ -0,0 +1,8 @@
+SUBDIRS = \
+  sources \
+
+.PHONY: all world clean install
+all world clean install:
+	for subdir in $(SUBDIRS); do \
+		( cd $$subdir && make -$(MAKEFLAGS) $@ ) || exit 1; \
+	done

README.md

@@ -0,0 +1,112 @@
+Guidelines for Teaching C++
+===========================
+
+This repository contains the source for the document:
+
+  - Guidelines for Teaching C++
+
+When the repository is tagged, this document is automatically built
+and made available via GitHub Pages at:
+
+  - <https://cplusplus.github.io/SG20/latest> (soon)
+  - <https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/latest>
+    (currently)
+  - <https://mdadams.github.io/SG20/latest> (currently)
+
+# Prerequisites for Building the Document
+
+The following software is needed to build the document:
+
+  - pandoc
+  - aspell
+  - various basic POSIX utilities, including (amongst others):
+      - make
+      - awk
+      - sed
+
+If one would like to build the document in PDF format, the
+following software is also required:
+
+  - LaTex
+
+# Building the Document
+
+To build the document, simply type:
+
+  1. make clean
+  2. make all
+  3. make install
+
+(Strictly speaking, step 2 can be skipped, since the install target
+has a dependency on the all target.)
+
+The above commands will build the document in several formats:
+
+  - HTML format as a single HTML document:
+    install/html/index.html
+  - EPUB format:
+    guidelines.epub
+  - HTML format split across multiple HTML documents:
+    install/html_split/index.html
+
+A make target called world is also defined.  Building this target (i.e.,
+"make world") will generate the document in additional formats, including
+PDF format, but requires that LaTeX be installed.
+
+The build process performs spell checking.
+The build will fail if any spelling errors are detected.
+
+# Spell Checking
+
+Words that are flagged as having spelling errors can be classified
+into two categories:
+
+  1. valid English words (such as technical terms) that are not in
+     the spell checker's dictionary
+  2. words that are not really "proper" English words but are also not
+     really errors either (e.g., people's names)
+
+Words in category 1 should be added to the file
+config/spellcheck/wordlist.
+Words in category 2 should be added to the file
+config/spellcheck/ignored_words.txt
+
+# Repository Organization
+
+The files in this repository are organized into directories as follows:
+
+- config:
+  This directory contains configuration files that control various
+  aspects of how the guidelines document is built.
+    - pandoc_templates:
+      This directory contains document templates used by pandoc during
+      the document build process.
+    - spellcheck:
+      The directory contains lists of additional words and ignorable errors
+      for spell checking.
+- sources:
+  This directory hierarchy contains the source files for the document.
+    - css:
+      This directory contains CSS files used by the document when built
+      in HTML format.
+    - images:
+      This directory contains images used in the document.
+    - modules:
+      The directory hierarchy contains the information for individual modules
+      and topics.  There is one directory per module and one file per topic.
+- tools:
+  The directory hierarchy contains various scripts and other tools used for
+  building and deploying the document to GitHub pages site.
+    - build:
+      This directory contains scripts used for building and deploying the
+      document.
+    - old:
+      This directory hierachy needs to be reorganized.  This directory
+      should probably be renamed and its contents possibly reorganized
+      or relocated elsewhere.
+        - tools
+            - tests
+                - TEST_INPUTS
+    - pandoc_filters:
+      This directory contains various filters needed for pandoc.  These
+      filters do things such as allow markdown-aware spell checking.

TODO.txt

@@ -0,0 +1,7 @@
+Some topics listed on GitHub are unclear as to their meaning.
+e.g.  Heterogeneous Compiling
+[Is "Heterogeneous Computing" intended or "Cross Compiling"?]
+There are others too.
+
+More thought is needed on naming conventions for labels for
+knowledge areas/units.