cplusplus · vulder · Sep 20, 2021 · Mar 9, 2021 · Apr 22, 2021 · Apr 23, 2021
diff --git a/.github/workflows/ci.yml b/.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
+    ############################################################
diff --git a/.github/workflows/release.yml b/.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}}
+    ############################################################
diff --git a/LICENSE.txt b/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 admin@isocpp.org 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.
+
diff --git a/Makefile b/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
diff --git a/README.md b/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.
diff --git a/TODO.txt b/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.