From 5a2262d6fb593edcf8c674d37c4b6fae33b0dd01 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 9 Mar 2021 15:02:02 -0800 Subject: [PATCH 01/64] Added a new attempt at a revised "Guidelines for Teaching C++" document. --- .github/workflows/ci.yml | 15 + .github/workflows/release.yml | 23 + LICENSE.txt | 41 + Makefile | 148 ++ README.md | 19 + TODO.txt | 7 + bin/aspell_frontend | 15 + bin/make_markdown | 114 ++ bin/preprocessor | 61 + build/build | 62 + build/deploy | 155 ++ build/prebuild | 10 + compile-time-programming/concepts.md | 3 - .../function-templates.md | 3 - compile-time-programming/requires-clause.md | 3 - css/default-pandoc.css | 327 ++++ css/elegant_bootstrap.css | 329 ++++ css/epub.css | 1540 +++++++++++++++++ css/github-pandoc.css | 424 +++++ .../requires-expressions.md | 28 +- .../areas/functions}/defaulted-parameters.md | 30 +- .../areas/functions}/user-defined-literals.md | 30 +- .../areas/object-model}/copy-semantics.md | 30 +- doc/areas/object-model/copy_elision.md | 33 + doc/contributing.md | 38 + doc/course_examples.md | 5 + doc/disclaimer.md | 6 + doc/glossary.md | 6 + doc/introduction.md | 95 + doc/knowledge_areas.dat | 76 + doc/main.md | 73 + doc/obtaining_document.md | 25 + doc/references.md | 36 + filters/spellcheck.lua | 70 + functions/calling-functions.md | 3 - functions/member-functions.md | 3 - object-model/constant-objects.md | 3 - object-model/constructors.md | 3 - object-model/declarations.md | 3 - object-model/move-semantics.md | 3 - object-model/objects.md | 3 - object-model/rule-of-five.md | 3 - object-model/rule-of-zero.md | 3 - object-model/special-member-functions.md | 3 - object-model/types.md | 3 - Readme.md => old/Readme.md | 0 gen_readme.py => old/gen_readme.py | 0 skeleton.md => old/skeleton.md | 0 {tools => old/tools}/pytest.ini | 0 {tools => old/tools}/requirements.txt | 0 .../tests/TEST_INPUTS/fix_wrong_sections.md | 0 .../tests/TEST_INPUTS/missing_sections.md | 0 .../tools}/tests/TEST_INPUTS/test_skeleton.md | 0 .../TEST_INPUTS/user_content_heading_topic.md | 0 .../tools}/tests/topic_updater_test.py | 0 topic_updater.py => old/topic_updater.py | 0 program-design/concepts.md | 1 - spellcheck/spellcheck_expected.txt | 34 + spellcheck/wordlist | 12 + templates/bootstrap_menu.html | 127 ++ templates/clean_menu.html | 129 ++ templates/easy_template.html | 128 ++ templates/elegant_bootstrap_menu.html | 128 ++ templates/uikit.html | 115 ++ user-defined-types/user-defined-literals.md | 1 - 65 files changed, 4485 insertions(+), 103 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/release.yml create mode 100644 LICENSE.txt create mode 100644 Makefile create mode 100644 README.md create mode 100644 TODO.txt create mode 100755 bin/aspell_frontend create mode 100755 bin/make_markdown create mode 100755 bin/preprocessor create mode 100755 build/build create mode 100755 build/deploy create mode 100755 build/prebuild delete mode 100644 compile-time-programming/concepts.md delete mode 100644 compile-time-programming/function-templates.md delete mode 100644 compile-time-programming/requires-clause.md create mode 100644 css/default-pandoc.css create mode 100644 css/elegant_bootstrap.css create mode 100644 css/epub.css create mode 100644 css/github-pandoc.css rename {compile-time-programming => doc/areas/compile-time-programming}/requires-expressions.md (90%) rename {functions => doc/areas/functions}/defaulted-parameters.md (86%) rename {functions => doc/areas/functions}/user-defined-literals.md (88%) rename {object-model => doc/areas/object-model}/copy-semantics.md (91%) create mode 100644 doc/areas/object-model/copy_elision.md create mode 100644 doc/contributing.md create mode 100644 doc/course_examples.md create mode 100644 doc/disclaimer.md create mode 100644 doc/glossary.md create mode 100644 doc/introduction.md create mode 100644 doc/knowledge_areas.dat create mode 100644 doc/main.md create mode 100644 doc/obtaining_document.md create mode 100644 doc/references.md create mode 100644 filters/spellcheck.lua delete mode 100644 functions/calling-functions.md delete mode 100644 functions/member-functions.md delete mode 100644 object-model/constant-objects.md delete mode 100644 object-model/constructors.md delete mode 100644 object-model/declarations.md delete mode 100644 object-model/move-semantics.md delete mode 100644 object-model/objects.md delete mode 100644 object-model/rule-of-five.md delete mode 100644 object-model/rule-of-zero.md delete mode 100644 object-model/special-member-functions.md delete mode 100644 object-model/types.md rename Readme.md => old/Readme.md (100%) rename gen_readme.py => old/gen_readme.py (100%) rename skeleton.md => old/skeleton.md (100%) rename {tools => old/tools}/pytest.ini (100%) rename {tools => old/tools}/requirements.txt (100%) rename {tools => old/tools}/tests/TEST_INPUTS/fix_wrong_sections.md (100%) rename {tools => old/tools}/tests/TEST_INPUTS/missing_sections.md (100%) rename {tools => old/tools}/tests/TEST_INPUTS/test_skeleton.md (100%) rename {tools => old/tools}/tests/TEST_INPUTS/user_content_heading_topic.md (100%) rename {tools => old/tools}/tests/topic_updater_test.py (100%) rename topic_updater.py => old/topic_updater.py (100%) delete mode 100644 program-design/concepts.md create mode 100644 spellcheck/spellcheck_expected.txt create mode 100644 spellcheck/wordlist create mode 100644 templates/bootstrap_menu.html create mode 100644 templates/clean_menu.html create mode 100644 templates/easy_template.html create mode 100644 templates/elegant_bootstrap_menu.html create mode 100644 templates/uikit.html delete mode 100644 user-defined-types/user-defined-literals.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..cf1bf02 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,15 @@ +name: ci + +on: [push] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Prebuild + shell: bash + run: build/prebuild + - name: Build + shell: bash + run: build/build -d ${{runner.temp}}/output -z ${{github.ref}} -s diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..72639f4 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,23 @@ +name: release + +on: + push: + tags: + - 'v*.*.*' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Prebuild + shell: bash + run: build/prebuild + - name: Build + shell: bash + run: build/build -d ${{runner.temp}}/output -z ${{github.ref}} + - name: Deploy + env: + DEPLOY_KEY: ${{secrets.DEPLOY_KEY}} + shell: bash + run: build/deploy -t ${{runner.temp}}/deploy_tmp -r mdadams/sg20_guidelines_for_teaching_cpp -i ${{runner.temp}}/output -z ${{github.ref}} diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..2427faf --- /dev/null +++ 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 new file mode 100644 index 0000000..88918b7 --- /dev/null +++ b/Makefile @@ -0,0 +1,148 @@ +# Specify the document version. +# This can be overridden when invoked from the automated build process. +DOC_VERSION = X.Y.Z + +# Specify whether a spelling error is an error (as opposed to a warning). +# This can be overridden when invoked from the automated build process. +DOC_SPELLCHECK_MUST_PASS = 1 + +# All of the Markdown source files (that are not generated during build). +SOURCES = \ + doc/areas/compile-time-programming/requires-expressions.md \ + doc/areas/functions/defaulted-parameters.md \ + doc/areas/functions/user-defined-literals.md \ + doc/areas/object-model/copy_elision.md \ + doc/areas/object-model/copy-semantics.md \ + doc/course_examples.md \ + doc/disclaimer.md \ + doc/glossary.md \ + doc/contributing.md \ + doc/introduction.md \ + doc/main.md \ + doc/obtaining_document.md \ + doc/references.md \ + +# The Markdown files that are generated during the build process. +GENERATED_MARKDOWN = \ + knowledge_areas_summary.md \ + main.gen.md \ + +################################################################################ +# Define primary targets. +################################################################################ + +.PHONY: all +all: documents spellcheck + +.PHONY: documents +documents: guidelines.html guidelines_html guidelines.epub + +.PHONY: world +world: documents guidelines.pdf + +.PHONY: spellcheck +spellcheck: spellcheck_result.txt + +.PHONY: clean +clean: + rm -f guidelines.html guidelines.pdf guidelines.epub guidelines.tex + rm -rf guidelines.texi + rm -f main.gen.md knowledge_areas_summary.md + rm -f pandoc.css + rm -f missfont.log + rm -rf guidelines_html + rm -f spellcheck_result.txt + rm -f spellcheck/spellcheck_expected_sorted.txt + +.PHONY: install +install: + if [ ! -d $(INSTALL_DIR) ]; then mkdir -p $(INSTALL_DIR) || exit 1; fi + cp guidelines.html $(INSTALL_DIR)/index.html + #cp pandoc.css $(INSTALL_DIR)/pandoc.css + cp -r guidelines_html $(INSTALL_DIR)/split + cp guidelines.epub $(INSTALL_DIR) + +################################################################################ +# Preprocessing setup. +################################################################################ + +knowledge_areas_summary.md: $(SOURCES) doc/knowledge_areas.dat + bin/make_markdown < doc/knowledge_areas.dat > knowledge_areas_summary.md + +main.gen.md: $(SOURCES) doc/main.md + bin/preprocessor -v $(DOC_VERSION) < doc/main.md > main.gen.md + +################################################################################ +# Establish Pandoc settings. +################################################################################ + +PANDOC_OPTIONS += --toc --toc-depth 3 +PANDOC_OPTIONS += --number-sections +PANDOC_OPTIONS += --standalone +PANDOC_OPTIONS += --pdf-engine=xelatex +#PANDOC_OPTIONS += --metadata date="`date +%Y-%m-%d`" +PANDOC_OPTIONS += --variable version=$(DOC_VERSION) +#PANDOC_OPTIONS += --variable mainfont=DejaVuSerif --variable sansfont=DejaVuSans + +INPUT_FORMAT = markdown+header_attributes+multiline_tables + +#CSS_FILE = css/default-pandoc.css +#CSS_FILE = css/github-pandoc.css +#CSS_FILE = css/pandoc.css +#CSS_FILE = css/epub.css + +EPUB_CSS_FILE = css/default-pandoc.css + +#HTML_TEMPLATE = templates/bootstrap_menu.html +HTML_TEMPLATE = templates/uikit.html + +################################################################################ +# Rules for generating the document in various formats. +################################################################################ + +#pandoc.css: +# [ -e pandoc.css ] || ln -s $(CSS_FILE) pandoc.css + +guidelines.html: $(GENERATED_MARKDOWN) + #pandoc $(PANDOC_OPTIONS) -c pandoc.css --from $(INPUT_FORMAT) -o $@ main.gen.md + pandoc $(PANDOC_OPTIONS) --template $(HTML_TEMPLATE) --from $(INPUT_FORMAT) -o $@ main.gen.md + +guidelines.epub: $(GENERATED_MARKDOWN) + pandoc $(PANDOC_OPTIONS) -c $(EPUB_CSS_FILE) --from $(INPUT_FORMAT) -o $@ main.gen.md + +guidelines.pdf: $(GENERATED_MARKDOWN) + pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) -o $@ main.gen.md + +guidelines.texi: $(GENERATED_MARKDOWN) + pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) -o $@ main.gen.md + +guidelines.docbook: $(GENERATED_MARKDOWN) + pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) -o $@ main.gen.md + +guidelines_html: guidelines.texi + makeinfo --no-validate --force --html -o guidelines_html guidelines.texi + +guidelines.tex: + pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) --to latex -o $@ main.gen.md + +################################################################################ +# Rule for spellchecking. +################################################################################ + +spellcheck_result.txt: guidelines.html + rm -f $@ + rm -f spellcheck/spellcheck_expected_sorted.txt + sort spellcheck/spellcheck_expected.txt | uniq > spellcheck/spellcheck_expected_sorted.txt + PATH="bin:$$PATH" pandoc --from $(INPUT_FORMAT) --lua-filter filters/spellcheck.lua main.gen.md | sort | uniq > $@ + @status=0; \ + diff -q spellcheck/spellcheck_expected_sorted.txt $@ || status=1; \ + if [ $$status -ne 0 ]; then \ + echo "SPELLING ERRORS DETECTED:"; \ + diff -u spellcheck/spellcheck_expected_sorted.txt $@ | grep '^[+-]'; \ + if [ $(DOC_SPELLCHECK_MUST_PASS) -ne 0 ]; then \ + echo "ERROR: spelling errors detected"; \ + exit 1; \ + else \ + echo "WARNING: spelling errors detected"; \ + fi; \ + fi diff --git a/README.md b/README.md new file mode 100644 index 0000000..0e99713 --- /dev/null +++ b/README.md @@ -0,0 +1,19 @@ +The following software is needed to build the document: + + - pandoc + - aspell + - make + - various base POSIX utilities such as awk and sed + +To build, simply type: + + - make clean + - make all + +This will build the document in multiple formats. +The main two formats are: + + - HTML format as a single HTML document: guidelines.html + - EPUB format: guidelines.epub + +The build process performs spell checking. diff --git a/TODO.txt b/TODO.txt new file mode 100644 index 0000000..58e34e9 --- /dev/null +++ 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. diff --git a/bin/aspell_frontend b/bin/aspell_frontend new file mode 100755 index 0000000..e49dd69 --- /dev/null +++ b/bin/aspell_frontend @@ -0,0 +1,15 @@ +#! /usr/bin/env bash +# Michael Adams (mdadams@ece.uvic.ca) + +cmd_dir="$(dirname "$0")" || exit 1 + +# Get an absolute pathname. +#cmd_dir=$(realpath "$cmd_dir") || exit 1 + +spellcheck_dir="$cmd_dir/../spellcheck" +wordlist="wordlist" +if [ ! -f "$spellcheck_dir/$wordlist" ]; then + echo "ERROR" + exit 1 +fi +exec aspell --home-dir="$spellcheck_dir" --personal "$wordlist" "$@" diff --git a/bin/make_markdown b/bin/make_markdown new file mode 100755 index 0000000..a547075 --- /dev/null +++ b/bin/make_markdown @@ -0,0 +1,114 @@ +#! /usr/bin/env sh +# Michael Adams (mdadams@ece.uvic.ca) + +awk ' +function output(level, old_level, label, basic, intermediate, advanced, text) { + #bad_char = "🤢"; + bad_char = "❌"; + #check_char = "✓" + check_char = "✔️"; + emdash = "—"; + + if (level == 1) { + if (label == "?") { + label = bad_char; + #basic = emdash; + #intermediate = emdash; + #advanced = emdash; + } else { + if (basic == "y") { + #basic = sprintf("%s", label, check_char); + basic = sprintf("[%s](#%s-basic)", check_char, label); + } else if (basic == "n") { + basic = emdash; + } + if (intermediate == "y") { + #intermediate = sprintf("%s", label, check_char); + intermediate = sprintf("[%s](#%s-intermediate)", check_char, label); + } else if (intermediate == "n") { + intermediate = emdash; + } + if (advanced == "y") { + #advanced = sprintf("%s", label, check_char); + advanced = sprintf("[%s](#%s-advanced)", check_char, label); + } else if (advanced == "n") { + advanced = emdash; + } + } + #label = sprintf("%s", label, label); + label = sprintf("[%s](#%s)", label, label); + } + + if (level == 1 && old_level < 1) { + printf "\n| ID | Unit | Foundational | Main | Advanced |\n"; + printf "|---|----------|---|---|---|\n"; + } + if (level == 1) { + printf "| [%s] | %s | %s | %s | %s |\n", label, text, basic, intermediate, advanced; + } + if ((level == 0 || level == -1) && old_level > 0) { + printf "\n\n"; + #printf "Note: %s indicates no entry yet available\n\n", bad_char; + #printf "Note: The IDs and checkmarks (%s) are linked to the corresponding sections.\n\n", check_char; + } + if (level == 0) { + printf "\n"; + #printf "## [%s] %s {#%s}\n", label, text, label; + printf "## %s {#%s}\n", text, label; + } +} + +BEGIN { + old_level = -1; +} + +(NF > 0) { + line = $0; + level = 0; + while (substr(line, level + 1, 1) == "\t") { + ++level; + } + + label = ""; + basic = ""; + intermediate = ""; + advanced = ""; + text = ""; + + if (level == 0) { + + label = $1; + text = substr($0, index($0, $2)); + output(level, old_level, label, basic, intermediate, advanced, text); + + } else if (level == 1) { + + label = $1; + basic = $2; + intermediate = $3; + advanced = $4; + text = substr($0, index($0, $5)); + + output(level, old_level, label, basic, intermediate, advanced, text); + + } + + old_level = level; + +} + +END { + + level = -1; + + label = ""; + basic = ""; + intermediate = ""; + advanced = ""; + text = ""; + + output(level, old_level, label, basic, intermediate, advanced, text); + +} + +' - diff --git a/bin/preprocessor b/bin/preprocessor new file mode 100755 index 0000000..b728245 --- /dev/null +++ b/bin/preprocessor @@ -0,0 +1,61 @@ +#! /usr/bin/env sh +# Michael Adams (mdadams@ece.uvic.ca) + +program_dir="$(dirname "$0")" || exit 1 +program_pathname="$0" + +panic() +{ + echo "ERROR: $@" + exit 1 +} + +usage() +{ + echo "bad usage: $@" + exit 2 +} + +level=0 +version= + +while getopts v:l: opt; do + case $opt in + v) + version="$OPTARG";; + l) + level="$OPTARG";; + \?) + usage + break;; + esac +done +shift $((OPTIND - 1)) + +if [ -z "$version" ]; then + usage "no version specified" +fi +if [ "$level" -gt 10 ]; then + panic "recursion too deep" +fi + +awk -v program="$program_pathname" -v level="$level" -v version="$version" ' + /^__INCLUDE__(.*)/ { + i = length("__INCLUDE__("); + start = i + 1; + while (substr($0, i, 1) != ")") { + ++i; + } + end = i; + path = substr($0, start, end - start); + result = system(sprintf("cat %s | %s -l %d -v %s", path, program, level + 1, version)); + if (result) { + exit 1; + } + next; + } + { + print $0; + } +' - | \ + sed -e 's/__VERSION__/'"$version"'/g' diff --git a/build/build b/build/build new file mode 100755 index 0000000..8924d54 --- /dev/null +++ b/build/build @@ -0,0 +1,62 @@ +#! /usr/bin/env bash +# Michael Adams (mdadams@ece.uvic.ca) + +cmd_dir=$(dirname "$0") || exit 1 +source_dir="$cmd_dir/.." + +panic() +{ + echo "ERROR: $@" + exit 1 +} + +usage() +{ + echo "bad usage: $@" + cat <<- EOF + $0 -d install_dir -z github_ref + EOF + exit 2 +} + +install_dir= +github_ref= +spellcheck=0 + +while getopts d:z:s opt; do + case $opt in + d) + install_dir="$OPTARG";; + z) + github_ref="$OPTARG";; + s) + spellcheck=1;; + \?) + usage + break;; + esac +done +shift $((OPTIND - 1)) + +if [ -z "$install_dir" ]; then + usage "no output directory specified" +fi +if [ -z "$github_ref" ]; then + usage "no github ref specified" +fi + +version="$(awk -v FS="/" '{print $3;}' <<< "$github_ref")" || panic + +if [ ! -d "$install_dir" ]; then + mkdir -p "$install_dir" || panic +fi + +(cd "$source_dir" && make clean) || panic + +(cd "$source_dir" && \ + make DOC_VERSION="$version" DOC_SPELLCHECK_MUST_PASS="$spellcheck" all) || \ + panic + +INSTALL_DIR="$install_dir" make install +#cp "$source_dir/guidelines.html" "$install_dir/index.html" || panic +#cp "$source_dir/pandoc.css" "$install_dir" || panic diff --git a/build/deploy b/build/deploy new file mode 100755 index 0000000..6a9515e --- /dev/null +++ b/build/deploy @@ -0,0 +1,155 @@ +#! /usr/bin/env bash +# Michael Adams (mdadams@ece.uvic.ca) + +cmd_dir=$(dirname "$0") || exit 1 +source_dir="$cmd_dir/.." + +panic() +{ + echo "ERROR: $@" + exit 1 +} + +usage() +{ + echo "bad usage: $@" + exit 2 +} + +branch="gh-pages" +in_dir= +repo_name= +tmp_dir="${TMPDIR:-/tmp}" +github_ref= +force=0 +prepare_only=0 + +while getopts b:i:r:t:z:fn opt; do + case $opt in + b) + branch="$OPTARG";; + t) + tmp_dir="$OPTARG";; + i) + in_dir="$OPTARG";; + r) + repo_name="$OPTARG";; + z) + github_ref="$OPTARG";; + f) + force=1;; + n) + prepare_only=1;; + \?) + usage + break;; + esac +done +shift $((OPTIND - 1)) + +if [ -z "$github_ref" ]; then + usage "no github ref specified" +fi +if [ -z "$tmp_dir" ]; then + usage "no temporary directory specified" +fi +if [ -z "$in_dir" ]; then + usage "no input directory specified" +fi +if [ -z "$repo_name" ]; then + usage "no repository name specified" +fi +if [ -z "$DEPLOY_KEY" ]; then + usage "DEPLOY_KEY environment variable not set" +fi + +echo "temporary directory $tmp_dir" +echo "input directory $in_dir" +echo "repository name $repo_name" +echo "github ref $github_ref" + +version="$(awk -v FS="/" '{print $3;}' <<< "$github_ref")" || panic +echo "version $version" + +tmp_dir="$tmp_dir/deploy" + +git_dir="$tmp_dir/git" +ssh_dir="$HOME/.ssh" +private_key_file="$ssh_dir/private_key" + +if [ "$force" -eq 0 -a -e "$private_key_file" ]; then + panic "private key file already exists" +fi + +if [ ! -d "$ssh_dir" ]; then + mkdir -p "$ssh_dir" || panic "cannot make directory $ssh_dir" +fi +if [ ! -d "$tmp_dir" ]; then + mkdir -p "$ssh_dir" || panic "cannot make directory $ssh_dir" +fi + +echo "$DEPLOY_KEY" > "$private_key_file" || \ + panic "cannot create private key file" +chmod u+rw,g=,o= "$private_key_file" || \ + panic "cannot set permissions for private key file" + +version_dir="$git_dir/$version" +repo_url="ssh://git@github.com/$repo_name.git" + +if [ -z "$SSH_AGENT_PID" ]; then + eval $(ssh-agent) || panic "cannot start ssh-agent" +fi +ssh-add "$private_key_file" || panic "ssh-add failed" + +git clone "$repo_url" "$git_dir" || \ + panic "clone failed" + +git -C "$git_dir" ls-remote --exit-code --heads "$repo_url" "$branch" \ + > /dev/null +status=$? +if [ "$status" -ne 0 -a "$status" -ne 2 ]; then + panic "git ls-remote failed" +fi +if [ "$status" -eq 2 ]; then + git -C "$git_dir" checkout --orphan "$branch" || \ + panic "cannot create orphan branch $branch" +fi + +git -C "$git_dir" checkout "$branch" || \ + panic "cannot checkout branch $branch" + +git -C "$git_dir" config --local user.name "Michael Adams" +git -C "$git_dir" config --local user.email "mdadams@ece.uvic.ca" + +if [ -e "$version_dir" ]; then + panic "directory already exist for $version" +fi +mkdir -p "$version_dir" || \ + panic "cannot make directory $version_dir" +(cd "$in_dir" && tar -cf - .) | (cd "$version_dir" && tar -xf -) || \ + panic "tar failed" + +target="$git_dir/latest" +if [ -h "$target" -o -e "$target" ]; then + rm -f "$target" || panic "rm failed" +fi +ln -s "$version" "$target" || \ + panic "ln failed" +target="$git_dir/index.html" +if [ -h "$target" -o -e "$target" ]; then + rm -f "$target" || panic "rm failed" +fi +ln -s "latest/index.html" "$target" || \ + panic "ln failed" + +ls -al "$git_dir"/* + +git -C "$git_dir" add . || \ + panic "git add failed" +git -C "$git_dir" commit -m "Deploying" || \ + panic "git commit failed" +if [ "$prepare_only" -eq 0 ]; then + echo "Pushing changes." + git -C "$git_dir" push || \ + panic "git push failed" +fi diff --git a/build/prebuild b/build/prebuild new file mode 100755 index 0000000..83c18f1 --- /dev/null +++ b/build/prebuild @@ -0,0 +1,10 @@ +#! /usr/bin/env bash +# Michael Adams (mdadams@ece.uvic.ca) + +packages=() +packages+=(pandoc) +packages+=(texinfo) +packages+=(aspell) +#packages+=(hunspell) + +sudo apt-get install -y "${packages[@]}" diff --git a/compile-time-programming/concepts.md b/compile-time-programming/concepts.md deleted file mode 100644 index 7e58a7e..0000000 --- a/compile-time-programming/concepts.md +++ /dev/null @@ -1,3 +0,0 @@ -# Compile-time programming: concepts - -This topic is currently under construction and will soon be filled with information :) diff --git a/compile-time-programming/function-templates.md b/compile-time-programming/function-templates.md deleted file mode 100644 index c0bbb6f..0000000 --- a/compile-time-programming/function-templates.md +++ /dev/null @@ -1,3 +0,0 @@ -# Compile-time programming: Function Templates - -This topic is currently under construction and will soon be filled with information :) diff --git a/compile-time-programming/requires-clause.md b/compile-time-programming/requires-clause.md deleted file mode 100644 index 734cb82..0000000 --- a/compile-time-programming/requires-clause.md +++ /dev/null @@ -1,3 +0,0 @@ -# Compile-time programming: requires-clause - -This topic is currently under construction and will soon be filled with information :) diff --git a/css/default-pandoc.css b/css/default-pandoc.css new file mode 100644 index 0000000..9703d63 --- /dev/null +++ b/css/default-pandoc.css @@ -0,0 +1,327 @@ +html { + font-size: 100%; + overflow-y: scroll; + -webkit-text-size-adjust: 100%; + -ms-text-size-adjust: 100%; +} + +body { + color: #444; + font-family: Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif; + font-size: 12px; + line-height: 1.7; + padding: 1em; + margin: auto; +/* + max-width: 42em; +*/ + max-width: 50em; + background: #fefefe; +} + +a { + color: #0645ad; + text-decoration: none; +} + +a:visited { + color: #0b0080; +} + +a:hover { + color: #06e; +} + +a:active { + color: #faa700; +} + +a:focus { + outline: thin dotted; +} + +*::-moz-selection { + background: rgba(255, 255, 0, 0.3); + color: #000; +} + +*::selection { + background: rgba(255, 255, 0, 0.3); + color: #000; +} + +a::-moz-selection { + background: rgba(255, 255, 0, 0.3); + color: #0645ad; +} + +a::selection { + background: rgba(255, 255, 0, 0.3); + color: #0645ad; +} + +p { + margin: 1em 0; +} + +img { + max-width: 100%; +} + +h1, h2, h3, h4, h5, h6 { + color: #111; + line-height: 125%; + margin-top: 2em; + font-weight: normal; +} + +h4, h5, h6 { + font-weight: bold; +} + +h1 { + font-size: 2.5em; +} + +h2 { + font-size: 2em; +} + +h3 { + font-size: 1.5em; +} + +h4 { + font-size: 1.2em; +} + +h5 { + font-size: 1em; +} + +h6 { + font-size: 0.9em; +} + +blockquote { + color: #666666; + margin: 0; + padding-left: 3em; + border-left: 0.5em #EEE solid; +} + +hr { + display: block; + height: 2px; + border: 0; + border-top: 1px solid #aaa; + border-bottom: 1px solid #eee; + margin: 1em 0; + padding: 0; +} + +pre, code, kbd, samp { + color: #000; + font-family: monospace, monospace; + _font-family: 'courier new', monospace; + font-size: 0.98em; +} + +pre { + white-space: pre; + white-space: pre-wrap; + word-wrap: break-word; +} + +b, strong { + font-weight: bold; +} + +dfn { + font-style: italic; +} + +ins { + background: #ff9; + color: #000; + text-decoration: none; +} + +mark { + background: #ff0; + color: #000; + font-style: italic; + font-weight: bold; +} + +sub, sup { + font-size: 75%; + line-height: 0; + position: relative; + vertical-align: baseline; +} + +sup { + top: -0.5em; +} + +sub { + bottom: -0.25em; +} + +ul, ol { + margin: 1em 0; + padding: 0 0 0 2em; +} + +li p:last-child { + margin-bottom: 0; +} + +ul ul, ol ol { + margin: .3em 0; +} + +dl { + margin-bottom: 1em; +} + +dt { + font-weight: bold; + margin-bottom: .8em; +} + +dd { + margin: 0 0 .8em 2em; +} + +dd:last-child { + margin-bottom: 0; +} + +img { + border: 0; + -ms-interpolation-mode: bicubic; + vertical-align: middle; +} + +figure { + display: block; + text-align: center; + margin: 1em 0; +} + +figure img { + border: none; + margin: 0 auto; +} + +figcaption { + font-size: 0.8em; + font-style: italic; + margin: 0 0 .8em; +} + +table { + margin-bottom: 2em; + border-bottom: 1px solid #ddd; + border-right: 1px solid #ddd; + border-spacing: 0; + border-collapse: collapse; +} + +table th { + padding: .2em 1em; + background-color: #eee; + border-top: 1px solid #ddd; + border-left: 1px solid #ddd; +} + +table td { + padding: .2em 1em; + border-top: 1px solid #ddd; + border-left: 1px solid #ddd; + vertical-align: top; +} + +.author { + font-size: 1.2em; + text-align: center; +} + +@media only screen and (min-width: 480px) { + body { + font-size: 14px; + } +} +@media only screen and (min-width: 768px) { + body { + font-size: 16px; + } +} +@media print { + * { + background: transparent !important; + color: black !important; + filter: none !important; + -ms-filter: none !important; + } + + body { + font-size: 12pt; + max-width: 100%; + } + + a, a:visited { + text-decoration: underline; + } + + hr { + height: 1px; + border: 0; + border-bottom: 1px solid black; + } + + a[href]:after { + content: " (" attr(href) ")"; + } + + abbr[title]:after { + content: " (" attr(title) ")"; + } + + .ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after { + content: ""; + } + + pre, blockquote { + border: 1px solid #999; + padding-right: 1em; + page-break-inside: avoid; + } + + tr, img { + page-break-inside: avoid; + } + + img { + max-width: 100% !important; + } + + @page :left { + margin: 15mm 20mm 15mm 10mm; +} + + @page :right { + margin: 15mm 10mm 15mm 20mm; +} + + p, h2, h3 { + orphans: 3; + widows: 3; + } + + h2, h3 { + page-break-after: avoid; + } +} diff --git a/css/elegant_bootstrap.css b/css/elegant_bootstrap.css new file mode 100644 index 0000000..d62d6df --- /dev/null +++ b/css/elegant_bootstrap.css @@ -0,0 +1,329 @@ +/* + * I add this to html files generated with pandoc. + */ + +html { + font-size: 100%; + overflow-y: scroll; + -webkit-text-size-adjust: 100%; + -ms-text-size-adjust: 100%; +} + +body { + color: #444; + font-family: Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif; + font-size: 12px; + line-height: 1.8; + background: #fefefe; +} + +a { + color: #0645ad; + text-decoration: none; +} + +a:visited { + color: #0b0080; +} + +a:hover { + color: #06e; +} + +a:active { + color: #faa700; +} + +a:focus { + outline: thin dotted; +} + +*::-moz-selection { + background: rgba(255, 255, 0, 0.3); + color: #000; +} + +*::selection { + background: rgba(255, 255, 0, 0.3); + color: #000; +} + +a::-moz-selection { + background: rgba(255, 255, 0, 0.3); + color: #0645ad; +} + +a::selection { + background: rgba(255, 255, 0, 0.3); + color: #0645ad; +} + +p { + margin: 1em 0; +} + +img { + max-width: 100%; +} + +h1, h2, h3, h4, h5, h6 { + color: #111; + line-height: 125%; + /* margin-top: 2em; */ + font-weight: normal; +} + +h4, h5, h6 { + font-weight: bold; +} + +h1 { + font-size: 2.5em; +} + +h2 { + font-size: 2em; +} + +h3 { + font-size: 1.5em; +} + +h4 { + font-size: 1.2em; +} + +h5 { + font-size: 1em; +} + +h6 { + font-size: 0.9em; +} + +blockquote { + color: #666666; + margin: 0; + padding-left: 3em; + border-left: 0.5em #EEE solid; +} + +hr { + display: block; + height: 2px; + border: 0; + border-top: 1px solid #aaa; + border-bottom: 1px solid #eee; + margin: 1em 0; + padding: 0; +} + +pre, code, kbd, samp { + color: #000; + font-family: monospace, monospace; + _font-family: 'courier new', monospace; + font-size: 0.98em; +} + +pre { + white-space: pre; + white-space: pre-wrap; + word-wrap: break-word; +} + +b, strong { + font-weight: bold; +} + +dfn { + font-style: italic; +} + +ins { + background: #ff9; + color: #000; + text-decoration: none; +} + +mark { + background: #ff0; + color: #000; + font-style: italic; + font-weight: bold; +} + +sub, sup { + font-size: 75%; + line-height: 0; + position: relative; + vertical-align: baseline; +} + +sup { + top: -0.5em; +} + +sub { + bottom: -0.25em; +} + +ul, ol { + margin: 1em 0; + padding: 0 0 0 2em; +} + +li { + line-height: inherit; +} + +li p:last-child { + margin-bottom: 0; +} + +ul ul, ol ol { + margin: .3em 0; +} + +dl { + margin-bottom: 1em; +} + +dt { + font-weight: bold; + margin-bottom: .8em; +} + +dd { + margin: 0 0 .8em 2em; +} + +dd:last-child { + margin-bottom: 0; +} + +img { + border: 0; + -ms-interpolation-mode: bicubic; + vertical-align: middle; +} + +figure { + display: block; + text-align: center; + margin: 1em 0; +} + +figure img { + border: none; + margin: 0 auto; +} + +figcaption { + font-size: 0.8em; + font-style: italic; + margin: 0 0 .8em; +} + +table { + margin-bottom: 2em; + border-bottom: 1px solid #ddd; + border-right: 1px solid #ddd; + border-spacing: 0; + border-collapse: collapse; +} + +table th { + padding: .2em 1em; + background-color: #eee; + border-top: 1px solid #ddd; + border-left: 1px solid #ddd; +} + +table td { + padding: .2em 1em; + border-top: 1px solid #ddd; + border-left: 1px solid #ddd; + vertical-align: top; +} + +.author { + font-size: 1.2em; + text-align: center; +} + +@media only screen and (min-width: 480px) { + body { + font-size: 14px; + } +} +@media only screen and (min-width: 768px) { + body { + font-size: 16px; + } +} +@media print { + * { + background: transparent !important; + color: black !important; + filter: none !important; + -ms-filter: none !important; + } + + body { + font-size: 12pt; + max-width: 100%; + } + + a, a:visited { + text-decoration: underline; + } + + hr { + height: 1px; + border: 0; + border-bottom: 1px solid black; + } + + a[href]:after { + content: " (" attr(href) ")"; + } + + abbr[title]:after { + content: " (" attr(title) ")"; + } + + .ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after { + content: ""; + } + + pre, blockquote { + border: 1px solid #999; + padding-right: 1em; + page-break-inside: avoid; + } + + tr, img { + page-break-inside: avoid; + } + + img { + max-width: 100% !important; + } + + @page :left { + margin: 15mm 20mm 15mm 10mm; +} + + @page :right { + margin: 15mm 10mm 15mm 20mm; +} + + p, h2, h3 { + orphans: 3; + widows: 3; + } + + h2, h3 { + page-break-after: avoid; + } +} diff --git a/css/epub.css b/css/epub.css new file mode 100644 index 0000000..d07c53f --- /dev/null +++ b/css/epub.css @@ -0,0 +1,1540 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + learnbyexample.github.io/epub.css at master · learnbyexample/learnbyexample.github.io · GitHub + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Skip to content + + + + + + + + +
+ +
+ + + + + +
+ + + +
+ + + + + + + + + +
+
+
+ + + + + + + + + + +
+ +
+ +
+

+ + + / + + learnbyexample.github.io + + +

+ + +
+ + + +
+ + + + +
+ + +
+
+ + + + +
+ + + + Permalink + + + +
+ +
+
+ + + master + + + + +
+
+
+ Switch branches/tags + +
+ + + +
+ +
+ +
+ + +
+ +
+ + + + + + + + + + + + + + +
+ + + + +
+
+ +
+ +
+ +

+ learnbyexample.github.io/files/pandoc_pdf/epub.css +

+ + Go to file + + +
+ + +
    +
  • + + Go to file + +
    • +
  • + +
    • +
  • +
  • + + Copy path + +
    • +
  • + + + Copy permalink + + +
    • +
+
+
+ + + +
+ +
+
+
 
+
+ +
+
 
+ Cannot retrieve contributors at this time +
+
+ + + + + + + + +
+ + +
+
+ + 108 lines (93 sloc) + + 2.15 KB +
+ +
+ +
+ Raw + Blame +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
/* This defines styles and classes used in the book */
/* body { margin: 5%; text-align: justify; font-size: medium; }
code { font-family: monospace; }
h1 { text-align: left; }
h2 { text-align: left; }
h3 { text-align: left; } */
h4 { text-align: left; }
h5 { text-align: left; }
h6 { text-align: left; }
h1.title { }
h2.author { }
h3.date { }
nav#toc ol,
nav#landmarks ol { padding: 0; margin-left: 1em; }
nav#toc ol li,
nav#landmarks ol li { list-style-type: none; margin: 0; padding: 0; }
a.footnote-ref { vertical-align: super; }
em, em em em, em em em em em { font-style: italic;}
em em, em em em em { font-style: normal; }
/* code{ white-space: pre-wrap; } */
span.smallcaps{ font-variant: small-caps; }
span.underline{ text-decoration: underline; }
q { quotes: "“" "”" "‘" "’"; }
div.column{ display: inline-block; vertical-align: top; width: 50%; }
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
+
body {
font-family: "DejaVu Serif", serif;
margin: 5% 5% 20% 5%;
text-align: justify;
font-size: 0.75em;
line-height: 1.5;
}
+
h1 {
text-align: left;
font-size: 2em;
}
+
h2 {
text-align: left;
}
+
h3 {
text-align: left;
}
+
h1.title {
text-align: center;
}
+
p.author {
text-align: center;
}
+
code {
font-family: "DejaVu Sans Mono", monospace;
background-color: #ebebeb;
font-size: 100%;
line-height: inherit;
white-space: pre-wrap;
}
+
pre {
font-family: "DejaVu Sans Mono", monospace;
padding: 1em;
overflow: auto;
font-size: 100%;
line-height: inherit;
border-radius: 0.25em;
background-color: #ebebeb;
white-space: pre-wrap;
}
+
table {
border-collapse: collapse;
font-size: 100%;
}
+
th, td {
padding: 0.8em;
}
+
table, th, td {
border: 0.06em solid black;
}
+
a {
text-decoration: none;
}
+
blockquote {
border-style: solid solid solid solid;
border-color: #a41434;
border-width: medium;
border-radius: 0.5em;
padding-left: 1em;
padding-right: 1em;
background-color: #fcecf4;
}
+
@media screen { /* Workaround for iBooks issue; see #6242 */
.sourceCode {
overflow: visible !important;
white-space: pre-wrap !important;
}
}
+ + + +
+ + +
+ + + +
+ + +
+ + +
 +
+ + +
+ + + +
+
+ +
+
+ +
+ + + + + + + + + + + + + + + + + + + diff --git a/css/github-pandoc.css b/css/github-pandoc.css new file mode 100644 index 0000000..0607023 --- /dev/null +++ b/css/github-pandoc.css @@ -0,0 +1,424 @@ +/*! normalize.css v2.1.3 | MIT License | git.io/normalize */ + +/* ========================================================================== + HTML5 display definitions + ========================================================================== */ + +/** + * Correct `block` display not defined in IE 8/9. + */ + +article, +aside, +details, +figcaption, +figure, +footer, +header, +hgroup, +main, +nav, +section, +summary { + display: block; +} + +/** + * Correct `inline-block` display not defined in IE 8/9. + */ + +audio, +canvas, +video { + display: inline-block; +} + +/** + * Prevent modern browsers from displaying `audio` without controls. + * Remove excess height in iOS 5 devices. + */ + +audio:not([controls]) { + display: none; + height: 0; +} + +/** + * Address `[hidden]` styling not present in IE 8/9. + * Hide the `template` element in IE, Safari, and Firefox < 22. + */ + +[hidden], +template { + display: none; +} + +/* ========================================================================== + Base + ========================================================================== */ + +/** + * 1. Set default font family to sans-serif. + * 2. Prevent iOS text size adjust after orientation change, without disabling + * user zoom. + */ + +html { + font-family: sans-serif; /* 1 */ + -ms-text-size-adjust: 100%; /* 2 */ + -webkit-text-size-adjust: 100%; /* 2 */ +} + +/** + * Remove default margin. + */ + +body { + margin: 0; +} + +/* ========================================================================== + Links + ========================================================================== */ + +/** + * Remove the gray background color from active links in IE 10. + */ + +a { + background: transparent; +} + +/** + * Address `outline` inconsistency between Chrome and other browsers. + */ + +a:focus { + outline: thin dotted; +} + +/** + * Improve readability when focused and also mouse hovered in all browsers. + */ + +a:active, +a:hover { + outline: 0; +} + +/* ========================================================================== + Typography + ========================================================================== */ + +/** + * Address variable `h1` font-size and margin within `section` and `article` + * contexts in Firefox 4+, Safari 5, and Chrome. + */ + +h1 { + font-size: 2em; + margin: 0.67em 0; +} + +/** + * Address styling not present in IE 8/9, Safari 5, and Chrome. + */ + +abbr[title] { + border-bottom: 1px dotted; +} + +/** + * Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. + */ + +b, +strong { + font-weight: bold; +} + +/** + * Address styling not present in Safari 5 and Chrome. + */ + +dfn { + font-style: italic; +} + +/** + * Address differences between Firefox and other browsers. + */ + +hr { + -moz-box-sizing: content-box; + box-sizing: content-box; + height: 0; +} + +/** + * Address styling not present in IE 8/9. + */ + +mark { + background: #ff0; + color: #000; +} + +/** + * Correct font family set oddly in Safari 5 and Chrome. + */ + +code, +kbd, +pre, +samp { + font-family: monospace, serif; + font-size: 1em; +} + +/** + * Improve readability of pre-formatted text in all browsers. + */ + +pre { + white-space: pre-wrap; +} + +/** + * Set consistent quote types. + */ + +q { + quotes: "\201C" "\201D" "\2018" "\2019"; +} + +/** + * Address inconsistent and variable font size in all browsers. + */ + +small { + font-size: 80%; +} + +/** + * Prevent `sub` and `sup` affecting `line-height` in all browsers. + */ + +sub, +sup { + font-size: 75%; + line-height: 0; + position: relative; + vertical-align: baseline; +} + +sup { + top: -0.5em; +} + +sub { + bottom: -0.25em; +} + +/* ========================================================================== + Embedded content + ========================================================================== */ + +/** + * Remove border when inside `a` element in IE 8/9. + */ + +img { + border: 0; +} + +/** + * Correct overflow displayed oddly in IE 9. + */ + +svg:not(:root) { + overflow: hidden; +} + +/* ========================================================================== + Figures + ========================================================================== */ + +/** + * Address margin not present in IE 8/9 and Safari 5. + */ + +figure { + margin: 0; +} + +/* ========================================================================== + Forms + ========================================================================== */ + +/** + * Define consistent border, margin, and padding. + */ + +fieldset { + border: 1px solid #c0c0c0; + margin: 0 2px; + padding: 0.35em 0.625em 0.75em; +} + +/** + * 1. Correct `color` not being inherited in IE 8/9. + * 2. Remove padding so people aren't caught out if they zero out fieldsets. + */ + +legend { + border: 0; /* 1 */ + padding: 0; /* 2 */ +} + +/** + * 1. Correct font family not being inherited in all browsers. + * 2. Correct font size not being inherited in all browsers. + * 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. + */ + +button, +input, +select, +textarea { + font-family: inherit; /* 1 */ + font-size: 100%; /* 2 */ + margin: 0; /* 3 */ +} + +/** + * Address Firefox 4+ setting `line-height` on `input` using `!important` in + * the UA stylesheet. + */ + +button, +input { + line-height: normal; +} + +/** + * Address inconsistent `text-transform` inheritance for `button` and `select`. + * All other form control elements do not inherit `text-transform` values. + * Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. + * Correct `select` style inheritance in Firefox 4+ and Opera. + */ + +button, +select { + text-transform: none; +} + +/** + * 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` + * and `video` controls. + * 2. Correct inability to style clickable `input` types in iOS. + * 3. Improve usability and consistency of cursor style between image-type + * `input` and others. + */ + +button, +html input[type="button"], /* 1 */ +input[type="reset"], +input[type="submit"] { + -webkit-appearance: button; /* 2 */ + cursor: pointer; /* 3 */ +} + +/** + * Re-set default cursor for disabled elements. + */ + +button[disabled], +html input[disabled] { + cursor: default; +} + +/** + * 1. Address box sizing set to `content-box` in IE 8/9/10. + * 2. Remove excess padding in IE 8/9/10. + */ + +input[type="checkbox"], +input[type="radio"] { + box-sizing: border-box; /* 1 */ + padding: 0; /* 2 */ +} + +/** + * 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. + * 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome + * (include `-moz` to future-proof). + */ + +input[type="search"] { + -webkit-appearance: textfield; /* 1 */ + -moz-box-sizing: content-box; + -webkit-box-sizing: content-box; /* 2 */ + box-sizing: content-box; +} + +/** + * Remove inner padding and search cancel button in Safari 5 and Chrome + * on OS X. + */ + +input[type="search"]::-webkit-search-cancel-button, +input[type="search"]::-webkit-search-decoration { + -webkit-appearance: none; +} + +/** + * Remove inner padding and border in Firefox 4+. + */ + +button::-moz-focus-inner, +input::-moz-focus-inner { + border: 0; + padding: 0; +} + +/** + * 1. Remove default vertical scrollbar in IE 8/9. + * 2. Improve readability and alignment in all browsers. + */ + +textarea { + overflow: auto; /* 1 */ + vertical-align: top; /* 2 */ +} + +/* ========================================================================== + Tables + ========================================================================== */ + +/** + * Remove most spacing between table cells. + */ + +table { + border-collapse: collapse; + border-spacing: 0; +} + +.go-top { +position: fixed; +bottom: 2em; +right: 2em; +text-decoration: none; +background-color: #E0E0E0; +font-size: 12px; +padding: 1em; +display: inline; +} + +/* Github css */ + +html,body{ margin: auto; + padding-right: 1em; + padding-left: 1em; + max-width: 44em; color:black;}*:not('#mkdbuttons'){margin:0;padding:0}body{font:13.34px helvetica,arial,freesans,clean,sans-serif;-webkit-font-smoothing:subpixel-antialiased;line-height:1.4;padding:3px;background:#fff;border-radius:3px;-moz-border-radius:3px;-webkit-border-radius:3px}p{margin:1em 0}a{color:#4183c4;text-decoration:none}body{background-color:#fff;padding:30px;margin:15px;font-size:14px;line-height:1.6}body>*:first-child{margin-top:0!important}body>*:last-child{margin-bottom:0!important}@media screen{body{box-shadow:0 0 0 1px #cacaca,0 0 0 4px #eee}}h1,h2,h3,h4,h5,h6{margin:20px 0 10px;padding:0;font-weight:bold;-webkit-font-smoothing:subpixel-antialiased;cursor:text}h1{font-size:28px;color:#000}h2{font-size:24px;border-bottom:1px solid #ccc;color:#000}h3{font-size:18px;color:#333}h4{font-size:16px;color:#333}h5{font-size:14px;color:#333}h6{color:#777;font-size:14px}p,blockquote,table,pre{margin:15px 0}ul{padding-left:30px}ol{padding-left:30px}ol li ul:first-of-type{margin-top:0}hr{background:transparent url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAYAAAAECAYAAACtBE5DAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyJpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMC1jMDYwIDYxLjEzNDc3NywgMjAxMC8wMi8xMi0xNzozMjowMCAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNSBNYWNpbnRvc2giIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6OENDRjNBN0E2NTZBMTFFMEI3QjRBODM4NzJDMjlGNDgiIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6OENDRjNBN0I2NTZBMTFFMEI3QjRBODM4NzJDMjlGNDgiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDo4Q0NGM0E3ODY1NkExMUUwQjdCNEE4Mzg3MkMyOUY0OCIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDo4Q0NGM0E3OTY1NkExMUUwQjdCNEE4Mzg3MkMyOUY0OCIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/PqqezsUAAAAfSURBVHjaYmRABcYwBiM2QSA4y4hNEKYDQxAEAAIMAHNGAzhkPOlYAAAAAElFTkSuQmCC) repeat-x 0 0;border:0 none;color:#ccc;height:4px;padding:0}body>h2:first-child{margin-top:0;padding-top:0}body>h1:first-child{margin-top:0;padding-top:0}body>h1:first-child+h2{margin-top:0;padding-top:0}body>h3:first-child,body>h4:first-child,body>h5:first-child,body>h6:first-child{margin-top:0;padding-top:0}a:first-child h1,a:first-child h2,a:first-child h3,a:first-child h4,a:first-child h5,a:first-child h6{margin-top:0;padding-top:0}h1+p,h2+p,h3+p,h4+p,h5+p,h6+p,ul li>:first-child,ol li>:first-child{margin-top:0}dl{padding:0}dl dt{font-size:14px;font-weight:bold;font-style:italic;padding:0;margin:15px 0 5px}dl dt:first-child{padding:0}dl dt>:first-child{margin-top:0}dl dt>:last-child{margin-bottom:0}dl dd{margin:0 0 15px;padding:0 15px}dl dd>:first-child{margin-top:0}dl dd>:last-child{margin-bottom:0}blockquote{border-left:4px solid #DDD;padding:0 15px;color:#777}blockquote>:first-child{margin-top:0}blockquote>:last-child{margin-bottom:0}table{border-collapse:collapse;border-spacing:0;font-size:100%;font:inherit}table th{font-weight:bold;border:1px solid #ccc;padding:6px 13px}table td{border:1px solid #ccc;padding:6px 13px}table tr{border-top:1px solid #ccc;background-color:#fff}table tr:nth-child(2n){background-color:#f8f8f8}img{max-width:100%}code,tt{margin:0 2px;padding:0 5px;white-space:nowrap;border:1px solid #eaeaea;background-color:#f8f8f8;border-radius:3px;font-family:Consolas,'Liberation Mono',Courier,monospace;font-size:12px;color:#333}pre>code{margin:0;padding:0;white-space:pre;border:0;background:transparent}.highlight pre{background-color:#f8f8f8;border:1px solid #ccc;font-size:13px;line-height:19px;overflow:auto;padding:6px 10px;border-radius:3px}pre{background-color:#f8f8f8;border:1px solid #ccc;font-size:13px;line-height:19px;overflow:auto;padding:6px 10px;border-radius:3px}pre code,pre tt{background-color:transparent;border:0}.poetry pre{font-family:Georgia,Garamond,serif!important;font-style:italic;font-size:110%!important;line-height:1.6em;display:block;margin-left:1em}.poetry pre code{font-family:Georgia,Garamond,serif!important;word-break:break-all;word-break:break-word;-webkit-hyphens:auto;-moz-hyphens:auto;hyphens:auto;white-space:pre-wrap}sup,sub,a.footnote{font-size:1.4ex;height:0;line-height:1;vertical-align:super;position:relative}sub{vertical-align:sub;top:-1px}@media print{body{background:#fff}img,pre,blockquote,table,figure{page-break-inside:avoid}body{background:#fff;border:0}code{background-color:#fff;color:#333!important;padding:0 .2em;border:1px solid #dedede}pre{background:#fff}pre code{background-color:white!important;overflow:visible}}@media screen{body.inverted{color:#eee!important;border-color:#555;box-shadow:none}.inverted body,.inverted hr .inverted p,.inverted td,.inverted li,.inverted h1,.inverted h2,.inverted h3,.inverted h4,.inverted h5,.inverted h6,.inverted th,.inverted .math,.inverted caption,.inverted dd,.inverted dt,.inverted blockquote{color:#eee!important;border-color:#555;box-shadow:none}.inverted td,.inverted th{background:#333}.inverted h2{border-color:#555}.inverted hr{border-color:#777;border-width:1px!important}::selection{background:rgba(157,193,200,0.5)}h1::selection{background-color:rgba(45,156,208,0.3)}h2::selection{background-color:rgba(90,182,224,0.3)}h3::selection,h4::selection,h5::selection,h6::selection,li::selection,ol::selection{background-color:rgba(133,201,232,0.3)}code::selection{background-color:rgba(0,0,0,0.7);color:#eee}code span::selection{background-color:rgba(0,0,0,0.7)!important;color:#eee!important}a::selection{background-color:rgba(255,230,102,0.2)}.inverted a::selection{background-color:rgba(255,230,102,0.6)}td::selection,th::selection,caption::selection{background-color:rgba(180,237,95,0.5)}.inverted{background:#0b2531;background:#252a2a}.inverted body{background:#252a2a}.inverted a{color:#acd1d5}}.highlight .c{color:#998;font-style:italic}.highlight .err{color:#a61717;background-color:#e3d2d2}.highlight .k,.highlight .o{font-weight:bold}.highlight .cm{color:#998;font-style:italic}.highlight .cp{color:#999;font-weight:bold}.highlight .c1{color:#998;font-style:italic}.highlight .cs{color:#999;font-weight:bold;font-style:italic}.highlight .gd{color:#000;background-color:#fdd}.highlight .gd .x{color:#000;background-color:#faa}.highlight .ge{font-style:italic}.highlight .gr{color:#a00}.highlight .gh{color:#999}.highlight .gi{color:#000;background-color:#dfd}.highlight .gi .x{color:#000;background-color:#afa}.highlight .go{color:#888}.highlight .gp{color:#555}.highlight .gs{font-weight:bold}.highlight .gu{color:#800080;font-weight:bold}.highlight .gt{color:#a00}.highlight .kc,.highlight .kd,.highlight .kn,.highlight .kp,.highlight .kr{font-weight:bold}.highlight .kt{color:#458;font-weight:bold}.highlight .m{color:#099}.highlight .s{color:#d14}.highlight .na{color:#008080}.highlight .nb{color:#0086b3}.highlight .nc{color:#458;font-weight:bold}.highlight .no{color:#008080}.highlight .ni{color:#800080}.highlight .ne,.highlight .nf{color:#900;font-weight:bold}.highlight .nn{color:#555}.highlight .nt{color:#000080}.highlight .nv{color:#008080}.highlight .ow{font-weight:bold}.highlight .w{color:#bbb}.highlight .mf,.highlight .mh,.highlight .mi,.highlight .mo{color:#099}.highlight .sb,.highlight .sc,.highlight .sd,.highlight .s2,.highlight .se,.highlight .sh,.highlight .si,.highlight .sx{color:#d14}.highlight .sr{color:#009926}.highlight .s1{color:#d14}.highlight .ss{color:#990073}.highlight .bp{color:#999}.highlight .vc,.highlight .vg,.highlight .vi{color:#008080}.highlight .il{color:#099}.highlight .gc{color:#999;background-color:#eaf2f5}.type-csharp .highlight .k,.type-csharp .highlight .kt{color:#00F}.type-csharp .highlight .nf{color:#000;font-weight:normal}.type-csharp .highlight .nc{color:#2b91af}.type-csharp .highlight .nn{color:#000}.type-csharp .highlight .s,.type-csharp .highlight .sc{color:#a31515} diff --git a/compile-time-programming/requires-expressions.md b/doc/areas/compile-time-programming/requires-expressions.md similarity index 90% rename from compile-time-programming/requires-expressions.md rename to doc/areas/compile-time-programming/requires-expressions.md index b0ad0d3..0c3325c 100644 --- a/compile-time-programming/requires-expressions.md +++ b/doc/areas/compile-time-programming/requires-expressions.md @@ -1,6 +1,6 @@ -# Module name: Requires Expressions +## Module name: Requires Expressions {#req_expr} -## Overview +### Overview @@ -21,7 +21,7 @@
-## Motivation +### Motivation Requires-expressions allow a developer to perform compile-time evaluation on the validity of other expressions. These are fundamental to the ability @@ -33,9 +33,9 @@ Requires-expressions are compile-time predicates which evaluate to true when their specified set of expressions are all valid for a given set of inputs. -## Foundational: Writing requires-expressions +### Foundational: Writing requires-expressions -### Background/Required Knowledge +#### Background/Required Knowledge A student is able to: @@ -46,7 +46,7 @@ It is helpful if: * The student is aware that attempting to specialize the template with types or values which do not match otherwise unstated assumptions will cause errors within the template. -### Student outcomes +#### Student outcomes {#req_expr-basic} A student should be able to: @@ -56,7 +56,7 @@ A student should be able to: 4. Write a nested-requirement to test the constexpr value of an operation, as opposed to just the syntactic validity 5. Use a requires-expression within a concept, requires-clause, or `if constexpr` condition -### Caveats +#### Caveats To require that expressions, which evaluate to a boolean value like `sizeof(t) == 4`, evaluate to `true` a nested-requirement is needed @@ -64,7 +64,7 @@ like `sizeof(t) == 4`, evaluate to `true` a nested-requirement is needed simple-requirement, which is satisfied based purely on syntactic validity, not on the result of the operation. -### Points to cover +#### Points to cover * All requires-expression requirements terminate with a semicolon. * simple-requirements are used to check that an expression is well-formed. @@ -74,9 +74,9 @@ not on the result of the operation. * Checks are performed by the compiler, not at run time. * If covering usage of requires-expression with requires-clause, [[Compile-time programming: requires clause]][3] demonstrate `requires requires` and show how to ever avoid writing it by using a concept. [[Compile-time programming: concepts]][1] -## Main: Advanced requirements +### Main: Advanced requirements -### Background/required knowledge +#### Background/required knowledge * All of the above. * Knowledge of `noexcept` @@ -85,16 +85,16 @@ A student is able to: * Write a concept [[Compile-time programming: concepts]][1] -### Student outcomes +#### Student outcomes {#req_expr-intermediate} A student should be able to: 1. Write compound-requirements which test the `noexcept`ness of an expression. 2. Use a concept as the target of a compound-requirement. -### Caveats +#### Caveats -### Points to cover +#### Points to cover * Compound-requirements allow the optional ability to test whether an expression is marked as `noexcept`, by using a trailing `noexcept` keyword. ``` @@ -109,7 +109,7 @@ static_assert(requires(S s) { { s.bar() } noexcept; } ); // Fails. s.bar() is no ``` * If the return-type-requirement of a compound-requirement is a concept, that concept is given the resulting type as the first parameter, followed by the specified parameters in the compound-requirement. `{ ++x } -> C` would substitute `C` and check that concept C is satisfied for those parameters. -## Advanced +### Advanced {#req_expr-advanced} [1]: ../compile-time-programming/concepts.md [2]: ../compile-time-programming/function-templates.md diff --git a/functions/defaulted-parameters.md b/doc/areas/functions/defaulted-parameters.md similarity index 86% rename from functions/defaulted-parameters.md rename to doc/areas/functions/defaulted-parameters.md index a2ce103..708c4a9 100644 --- a/functions/defaulted-parameters.md +++ b/doc/areas/functions/defaulted-parameters.md @@ -1,7 +1,7 @@ -# Functions: default argument +## Functions: default argument {#func_args} _Skeleton instructions are typeset in italic text._ -## Overview +### Overview Functions in C++ may be overloaded with different numbers and types of parameters. It may be of value to specify default arguments for some number @@ -28,19 +28,19 @@ maintaining backward compatibility with existing callers. -## Motivation +### Motivation Default arguments allow the omission of arguments with obvious or common values. Also may be utilized to extend an existing function signature without forcing changes to existing calling code. -## Topic introduction +### Topic introduction Explain how default arguments work and how to define them. -## Foundational: Using and defining functions with default arguments +### Foundational: Using and defining functions with default arguments -### Background/Required Knowledge +#### Background/Required Knowledge A student is able to: @@ -49,7 +49,7 @@ A student is able to: * Define member and non-member functions [[Functions: member functions]][2] * Explain what a default constructor is and does [[C++ object model: constructors]][3] -### Student outcomes +#### Student outcomes {#func_args-basic} A student should be able to: @@ -58,35 +58,35 @@ A student should be able to: 3. Explain when the lifetime of a default argument begins and ends -### Caveats +#### Caveats * When no forward-declaration exists, the definition serves as the declaration * When multiple declarations exist, only one may specify the default for any particular parameter, but multiple declarations may specify the defaults for different parameters. * Additional default values may be specified for other parameters in repeat declarations * Calling an overloaded function with fewer arguments may be ambiguous with regard to an overload with default arguments -### Points to cover +#### Points to cover * Default value may only be specified once for each parameter among all declarations * Default values must start from the rightmost parameter and continue leftward without gaps * Considerations of when to use default arguments vs overload set -## Main: implementing * +### Main: implementing * -### Background/required knowledge +#### Background/required knowledge * All of the above. -### Student outcomes +#### Student outcomes {#func_args-intermediate} A student should be able to: -### Caveats +#### Caveats -### Points to cover +#### Points to cover -## Advanced +### Advanced Subsequent redeclarations of the same function may add default argument values, which are then usable by callers. diff --git a/functions/user-defined-literals.md b/doc/areas/functions/user-defined-literals.md similarity index 88% rename from functions/user-defined-literals.md rename to doc/areas/functions/user-defined-literals.md index be7852c..3f47168 100644 --- a/functions/user-defined-literals.md +++ b/doc/areas/functions/user-defined-literals.md @@ -1,8 +1,8 @@ -# Functions: user-defined literals +## Functions: user-defined literals {#udl} _Skeleton instructions are typeset in italic text._ -## Overview +### Overview _Provides a short natural language abstract of the module’s contents._ _Specifies the different levels of teaching._ @@ -26,7 +26,7 @@ _Specifies the different levels of teaching._ -## Motivation +### Motivation _Why is this important?_ _Why do we want to learn/teach this topic?_ @@ -35,17 +35,17 @@ _Why do we want to learn/teach this topic?_ * `std::string`: `"Hello, world!"s` * `std::chrono`: `3h + 10m + 5s` -## Topic introduction +### Topic introduction _Very brief introduction to the topic._ * Explain the existence of user defined literals. Example: `12m + 17s` is terse, expressive and type safe. -## Foundational: Using UDLs +### Foundational: Using UDLs -### Background/Required Knowledge +#### Background/Required Knowledge A student: @@ -59,7 +59,7 @@ A student: * knows that namespaces exist, and namespace `std`. * knows what using-declarations and using-directives are. [[C++ object model: declarations]][2] -### Student outcomes +#### Student outcomes {#udl-basic} _A list of things "a student should be able to" after the curriculum._ _The next word should be an action word and testable in an exam._ @@ -78,7 +78,7 @@ A student should be able to: \[1]: explain that it's okay to use a using-directive to "activate" UDLs. -### Caveats +#### Caveats _This section mentions subtle points to understand, like anything resulting in implementation-defined, unspecified, or undefined behavior._ @@ -88,19 +88,19 @@ implementation-defined, unspecified, or undefined behavior._ * A student "activates" two suffixes with the same signature from different namespaces. -### Points to cover +#### Points to cover _This section lists important details for each point._ -## Main: implementing UDLs +### Main: implementing UDLs -### Background/Required Knowledge +#### Background/Required Knowledge * All of the above. -### Student outcomes +#### Student outcomes {#udl-intermediate} _A list of things "a student should be able to" after the curriculum._ _The next word should be an action word and testable in an exam._ @@ -111,18 +111,18 @@ A student should be able to: 1. write a UDL operator of their own. 2. separate unrelated UDLs into distinct namespaces. -### Caveats +#### Caveats _This section mentions subtle points to understand, like anything resulting in implementation-defined, unspecified, or undefined behavior._ No caveats at present. -### Points to cover +#### Points to cover _This section lists important details for each point._ No caveats at present. -## Advanced +### Advanced {#udl-advanced} _These are important topics that are not expected to be covered but provide guidance where one can continue to investigate this topic in more depth._ diff --git a/object-model/copy-semantics.md b/doc/areas/object-model/copy-semantics.md similarity index 91% rename from object-model/copy-semantics.md rename to doc/areas/object-model/copy-semantics.md index d7f85d5..d076b7b 100644 --- a/object-model/copy-semantics.md +++ b/doc/areas/object-model/copy-semantics.md @@ -1,8 +1,8 @@ -# C++ object model: copy semantics +## C++ object model: copy semantics {#copy} _Skeleton instructions are typeset in italic text._ -## Overview +### Overview _Provides a short natural language abstract of the module’s contents._ _Specifies the different levels of teaching._ @@ -26,23 +26,23 @@ _Specifies the different levels of teaching._ -## Motivation +### Motivation _Why is this important?_ _Why do we want to learn/teach this topic?_ Copy semantics allows the user to define how objects of a class get replicated and interact on a value level. -## Topic introduction +### Topic introduction _Very brief introduction to the topic._ Explains when and how objects are copied. -## Foundational: How and when are copies made +### Foundational: How and when are copies made -### Background/Required Knowledge +#### Background/Required Knowledge A student is able to: @@ -54,7 +54,7 @@ It helps when a student is able to: * use move semantics [[C++ object model: move semantics]][4] * explain special member functions [[C++ object model: special member functions]][5] -### Student outcomes +#### Student outcomes {#copy-basic} _A list of things "a student should be able to" after the curriculum._ _The next word should be an action word and testable in an exam._ @@ -69,14 +69,14 @@ A student should be able to: \* In other languages these differences are sometimes referred to as shallow and deep copy. -### Caveats +#### Caveats _This section mentions subtle points to understand, like anything resulting in implementation-defined, unspecified, or undefined behavior._ * Compiler-provided copy operations may result in ownership problems (e.g., `char*`). These ownership problems can generally be solved by using types whose copy operations have the appropriate semantics, e.g., `std::string` instead of `char*` to hold string values. -### Points to cover +#### Points to cover _This section lists important details for each point._ @@ -89,10 +89,10 @@ _This section lists important details for each point._ * Strings (copies the value) -## Main: Implementing user-defined copy operations +### Main: Implementing user-defined copy operations -### Background/Required Knowledge +#### Background/Required Knowledge A student is able to: @@ -103,7 +103,7 @@ It helps when a student is able to: * explain the rule of zero [[C++ object model: rule-of-zero]][7] * explain the rule of five [[C++ object model: rule-of-five]][6] -### Student outcomes +#### Student outcomes {#copy-intermediate} _A list of things "a student should be able to" after the curriculum._ _The next word should be an action word and testable in an exam._ @@ -116,7 +116,7 @@ A student should be able to: * implement copy operations for their own types * _Optional_: explain when copying with basic and strong exception guarantees is useful -### Caveats +#### Caveats _This section mentions subtle points to understand, like anything resulting in implementation-defined, unspecified, or undefined behavior._ @@ -124,7 +124,7 @@ implementation-defined, unspecified, or undefined behavior._ * Intricacies when implementing copy operations: * Examples of how _not_ to write copy operations (e.g., C++03 `std::auto_ptr`) -### Points to cover +#### Points to cover _This section lists important details for each point._ @@ -135,7 +135,7 @@ _This section lists important details for each point._ * Rule-of-five * Copy assignment operators can be ref-qualified to avoid assigning into temporary objects. -## Advanced +### Advanced _These are important topics that are not expected to be covered but provide guidance where one can continue to investigate this topic in more depth._ diff --git a/doc/areas/object-model/copy_elision.md b/doc/areas/object-model/copy_elision.md new file mode 100644 index 0000000..579d334 --- /dev/null +++ b/doc/areas/object-model/copy_elision.md @@ -0,0 +1,33 @@ +## Copy Elision and Implicit Moving {#copy_elision} + +### Basic Learning Outcomes {#copy_elision-basic} + +### Intermediate Learning Outcomes {#copy_elision-intermediate} + +After completing this unit, the student should be able to: + +- explain what copy elision and implicit moving are + and why they are beneficial; + +- explain what is meant by return value optimization (RVO) + and named RVO (NRVO); + +- for certain common code patterns, be able identify whether copy, move, or + copy elision takes place. + +### Advanced Learning Outcomes {#copy_elision-advanced} + +After completing this unit, the student should be able to: + +- identify the particular circumstances when copy + elision is permitted (but not necessarily required) + and when it is required; + +- in arbitrary code, be able to identify whether copy, move, or copy + elision takes place. + +### Common Misunderstandings + +Some common misunderstandings include the following: + +- Copy elision is only relevant to construction not assignment. diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 0000000..011225d --- /dev/null +++ b/doc/contributing.md @@ -0,0 +1,38 @@ +# How To Contribute {#contributing} + +Before attempting to contribute any content for consideration for +inclusion in this document, please read the information below and +and the referenced documents as appropriate. + +All contributions to this project must be made in accordance with the +license in section [License](#license). +This document only offers guidance on teaching C++ as it is specified +in the current version of the C++ standard. +So, content should be presented relative to the most-recently +ratified version of the standard. +A detailed explanation of how to present the material for a topic is given in: + +- JC van Winkel, Bjarne Stroustrup, and Florian Sattler. + P2193 --- + How to structure a teaching topic. + . + +Any potential contributors should ensure that they read this document. +The following document may also be helpful in providing some general +background on the modular approach to teaching followed herein: + +- Christopher Di Bella. + P1725R0 --- + Modular Topic Design. + . + +In order to prepare content, it is important to understand what learning +outcomes are, and how to prepare good ones. +Some information on learning outcomes can be found in the +[references](#references). +The following document offers a concise introduction to learning outcomes: + +- Effective Use of Performance Objectives for Learning and Assessment + (For Use With Fink’s and Bloom’s Taxonomies), + University of New Mexico, School of Medicine, Teaching and Educational Development, + . diff --git a/doc/course_examples.md b/doc/course_examples.md new file mode 100644 index 0000000..2d078cc --- /dev/null +++ b/doc/course_examples.md @@ -0,0 +1,5 @@ +# Examples of Course Curricula + +[**NOTE**: Anyone have any suggestions of items to add here?] +The following are examples of curricula for course on C++: +... diff --git a/doc/disclaimer.md b/doc/disclaimer.md new file mode 100644 index 0000000..c2be6f6 --- /dev/null +++ b/doc/disclaimer.md @@ -0,0 +1,6 @@ +# Disclaimer + +This document is intended as a proof of concept to solicit feedback +from others. +This document is incomplete. +This document likely has at least a few errors. diff --git a/doc/glossary.md b/doc/glossary.md new file mode 100644 index 0000000..dc2fe30 --- /dev/null +++ b/doc/glossary.md @@ -0,0 +1,6 @@ +# Glossary + +Some possible terms to include in the glossary: + + - learning objective + - learning outcome diff --git a/doc/introduction.md b/doc/introduction.md new file mode 100644 index 0000000..8db64ab --- /dev/null +++ b/doc/introduction.md @@ -0,0 +1,95 @@ +# Context and Aim of This Guide + +This document is intended to serve as a resource for instructors +to assist in the preparation of courses on C++ in a variety of +settings, including university, college, and industry environments. +The main objectives of this document are as follows: + + - to provide guidelines for content to be covered by courses of various + difficulty levels on C++ (e.g., topics and learning outcomes) + - to note some common misunderstandings and problematic points that may + be encountered when teaching particular topics + - to suggest resources useful for teaching C++ + - to present examples of curriculum for specific courses + +This document does not itself provide a curriculum for a single specific +course, but is rather a set of guidelines that can be used to prepare +curricula for a wide variety of courses that differ in focus and level +of sophistication. +(This said, however, some links to other documents with examples of +curricula for specific courses may be included herein.) + +# Use of This Document + +**[NOTE: This document follows the same license model as the C++ Core +Guidelines. The LICENSE document is taken verbatim from the C++ Core +Guidelines.]** +This document is made available under a MIT-style license. +In simple terms, this license permits copying, use, modification, +and creation of derivative works. +A copy of the license is included in the section [LICENSE](#license). + +# Contributing to This Document + +Contributions to this document are welcome. +If you would like to help with this project as a contributor, +please read the section [How to Contribute](#contributing). + +# Organization of This Document + +The various concepts (i.e., ideas) to potentially be covered +are partitioned into modules/areas. +A module/area is very broad in scope and consists of numerous topics. +**[Note: Can I suggest that we use the term "area" or "unit" instead of +"module"? I think that these other choices are better and also +avoid any potential confusion over what is meant by "module" +(i.e., C++ term versus plain English term).]** + +For each module/area, topics related to the module/area are identified. +Then, for each topic, learning outcomes are specified. +In order to address a wide variety of courses on C++, each topic +is addressed at three proficiency levels. +These proficiency levels allow each topic to be covered at more than +one level of detail. +This allows target audiences with different background and learning +objectives to be accommodated. +The three proficiency levels are as follows: + + - foundational. This level gives the learner the idea that a + facility exists, what benefits it offers, and the basic ways of using it. + **[Note: Isn't this just "novice"/"beginner"?]** + + - main. This level shows mainstream uses and techniques. + For abstraction and organizational mechanisms it also demonstrates how to + build them. Note that a main description typically cannot be written + concisely without relying on the foundational sections for a variety of + facilities. This is a major reason to separate foundational and main + sections of the presentation of a facility. The main section should + give the learner a basic (but not detailed) understanding of how a + facility might be implemented so that the learner can have a first-order + understanding of any costs involved. + Avoid language lawyering in the main section. + **[Note: The term "main" is not very descriptive/helpful. Could I suggest + using "intermediate"?]** + + - advanced. This level gives information suitable for an expert. + For most topics there is an expert level of knowledge that most + programmers rarely need and techniques that require detailed understanding + of language rules or library implementation. Delving into advanced topics + early would be distracting and reinforce C++’s unfortunate reputation of + being “expert only.” The advanced features often are “expert only” but + the foundational and main descriptions should not be. Finally, we + explicitly mention subjects that are considered too advanced for inclusion + in the guidelines. + +The remainder of this document is organized as follows. +The various topics are listed grouped by module/area. +In cases where a topic might be classified into more +than one module/area, the topic is listed under the module/area of most direct +relevance. +This is done in order to avoid duplication of content. +(In the case that a module/unit is equally relevant to multiple modules/areas, +the decision of which to select is made by a proverbial coin toss.) +The order in which modules/areas are presented +is not meant to imply any order of coverage in a course. +The order in which items are listed is essentially arbitrary. diff --git a/doc/knowledge_areas.dat b/doc/knowledge_areas.dat new file mode 100644 index 0000000..6055f68 --- /dev/null +++ b/doc/knowledge_areas.dat @@ -0,0 +1,76 @@ +CM Compilation Model + ? ? ? ? Translation Units + ? ? ? ? Headers + ? ? ? ? Modules + ? ? ? ? Name Mangling + ? ? ? ? Phases of Translation + ? ? ? ? Separate Compilation + ? ? ? ? Linkage +P Preprocessor + ? ? ? ? Preprocessor Metaprogramming + ? ? ? ? Inclusion + ? ? ? ? Macros +B Basics Types, Objects, Values, Expressions, Statements, and Control-Flow Constructs + ? ? ? ? Constant Objects + ? ? ? ? Declarations and Definitions + ? ? ? ? Selection Constructs (e.g., if, ternary) + ? ? ? ? Looping Constructs (e.g., for, while, etc.) +F Functions + ? ? ? ? Calling Functions + ? ? ? ? Parameter Passing (e.g., Passing By Value and Reference) + func_args y n n Default Arguments + ? ? ? ? Returning Multiple Values + ? ? ? ? Overloading + udl y y n User-Defined Literals +C User-Defined Types (Classes) + ? ? ? ? Special Member Functions + copy_elision n y y Copy Elision and Implicit Moving (e.g., RVO and NRVO, etc.) + ? ? ? ? Types + ? ? ? ? Conversions + ? ? ? ? Constructors and Destructors + ? ? ? ? Move/Copy Constructors and Assignment Operators + ? ? ? ? Member Functions + ? ? ? ? Sum Types + ? ? ? ? User-Defined Literals + ? ? ? ? Special Member Functions + ? ? ? ? Guidelines for Special Member Functions (e.g., Rule of Five, Rule of Zero) + copy y y n Copy Semantics + ? ? ? ? Moving and Copying + ? ? ? ? Lambdas +I Inheritance and Class Hierarchies + ? ? ? ? Virtual Functions + ? ? ? ? Run-Time Type Information +CT Compile-Time Computation + ? ? ? ? Constant Expressions and Constant Evaluation + ? ? ? ? static_assert +T Generic Programming (Templates) + ? ? ? ? Concepts + ? ? ? ? SFINAE + ? ? ? ? Template Metaprogramming + ? ? ? ? Function Templates + ? ? ? ? Requires Clauses + req_expr y y n Requires Expressions +EH Error Handling + ? ? ? ? Classes of Errors + ? ? ? ? errno + ? ? ? ? Error Codes + ? ? ? ? Exception Handling +SL Standard Library + ? ? ? ? Input/Output (I/O) + ? ? ? ? Containers, Iterators, and Algorithms +EL External (i.e., Non Standard) Libraries + ? ? ? ? Graphical User Interfaces +BLD Building + ? ? ? ? Software Build Tools + ? ? ? ? Strategies for Handling Build Problems +TD Testing and Debugging + ? ? ? ? Source-Level Debuggers + ? ? ? ? Code Sanitizers + ? ? ? ? Test Frameworks + ? ? ? ? Debugging Strategies +TOOL Tooling + ? ? ? ? Compiler Toolchains + ? ? ? ? IDEs +SD Software Design + ? ? ? ? Design by Contract + diff --git a/doc/main.md b/doc/main.md new file mode 100644 index 0000000..d532fe8 --- /dev/null +++ b/doc/main.md @@ -0,0 +1,73 @@ +--- +title: Guidelines for Teaching C++ +author: SG20 +geometry: margin=1in +output: pdf_document +--- + +__INCLUDE__(doc/obtaining_document.md) + +__INCLUDE__(doc/disclaimer.md) + +__INCLUDE__(doc/introduction.md) + +# Summary of Modules/Areas and Topics + +In the sections that follow, the various modules/areas and topics +are presented. +There is one section per module/area. +For each module/area, a table listing the various topics in that module/area +is provided. +The ID for a module/area is linked to the detailed coverage of that +module/area that comes later in the document. +In the table, a checkmark indicates that learning outcomes exist for the +specific proficiency level. +A dash indicates that no learning outcomes exist for the specific +proficiency level (simply because there +are not any, not because the information is missing). +In the case that the information for a knowledge unit is completely +missing, a "❌" symbol is used. + +[**NOTE**: These topics are taken mostly from the SG20 GitHub repository. +They are not intended to be complete in any sense. +In fact, by gathering together all topics in one place where they are +easily viewed, it is hoped that missing and unbalanced items will be more +obvious.] + +__INCLUDE__(knowledge_areas_summary.md) + +# Detailed Information for Modules/Areas and Topics + +[//]: # ( ********** START OF DETAILED TOPIC DOCUMENTS ********** ) + +__INCLUDE__(doc/areas/object-model/copy-semantics.md) + +__INCLUDE__(doc/areas/functions/user-defined-literals.md) + +__INCLUDE__(doc/areas/functions/defaulted-parameters.md) + +__INCLUDE__(doc/areas/compile-time-programming/requires-expressions.md) + +__INCLUDE__(doc/areas/object-model/copy_elision.md) + +[//]: # ( ********** END OF DETAILED TOPIC DOCUMENTS ********** ) + +__INCLUDE__(doc/course_examples.md) + +# License {#license} + +**[NOTE: This license is copied verbatim from the C++ Core Guidelines.]** +
+__INCLUDE__(LICENSE.txt)
+
+ +# Contributors + +For a complete list of contributors, please refer to the repository +containing this document on [GitHub](https://github.com/cplusplus/SG20). + +__INCLUDE__(doc/contributing.md) + +__INCLUDE__(doc/glossary.md) + +__INCLUDE__(doc/references.md) diff --git a/doc/obtaining_document.md b/doc/obtaining_document.md new file mode 100644 index 0000000..9b34661 --- /dev/null +++ b/doc/obtaining_document.md @@ -0,0 +1,25 @@ +# Obtaining This Document: The Most Recent Version and Alternate Formats + +The most recent version of this document is available as an online +HTML document at: +. + +The version of the document that you are currently reading is available in the +following formats: + + 1. online (HTML) format as a single large HTML document: + + + 2. EPUB format: + + + 3. online (HTML) format, split across multiple HTML documents: + + **[Note: The support for this format needs more work to look nice.]** + +Older versions of this document are also available. +In general version _ver_ is available at +https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/_ver_. +For example, version v0.1.0 (assuming that this version exists) would be +available at +. diff --git a/doc/references.md b/doc/references.md new file mode 100644 index 0000000..494478b --- /dev/null +++ b/doc/references.md @@ -0,0 +1,36 @@ +# References + +## References on Learning Outcomes + +- D. Kennedy, A. Hyland, and N. Ryan. + Writing and Using Learning Outcomes: A Practical Guide, 2007. + . + +- B. S. Bloom, M. D. Engelhart, E. J. Furst, W. H. Hill, and D. R. Krathwohl. + Taxonomy of educational objectives: The classification of educational goals. + Handbook I: Cognitive domain. New York: David McKay Company, 1956. + +- Bloom's Taxonomy. + . + +- Effective Use of Performance Objectives for Learning and Assessment + (For Use With Fink’s and Bloom’s Taxonomies), + University of New Mexico, School of Medicine, Teaching and Educational Development, + . + +## Working Group Documents Related to C++ Teaching Guidelines + +- Christopher Di Bella, Simon Brand, and Michael Adams. + P1389R0 --- + Standing Document for SG20: Guidelines for Teaching C++ to Beginners. + . + +- Christopher Di Bella. + P1725R0 --- + Modular Topic Design. + . + +- JC van Winkel, Bjarne Stroustrup, and Florian Sattler. + P2193 --- + How to structure a teaching topic. + . diff --git a/filters/spellcheck.lua b/filters/spellcheck.lua new file mode 100644 index 0000000..dd723cb --- /dev/null +++ b/filters/spellcheck.lua @@ -0,0 +1,70 @@ +-- lua filter for spell checking: requires 'aspell'. +-- Copyright (C) 2017-2020 John MacFarlane, released under MIT license + +local text = require('text') +local words = {} +local deflang + +local function add_to_dict(lang, t) + if not words[lang] then + words[lang] = {} + end + if not words[lang][t] then + words[lang][t] = (words[lang][t] or 0) + 1 + end +end + +local function get_deflang(meta) + deflang = (meta.lang and meta.lang[1] and meta.lang[1].c) or 'en' + -- the following is better but won't work in pandoc 2.0.6. + -- it requires pandoc commit ecc46e229fde934f163d1f646383d24bfe2039e1: + -- deflang = (meta.lang and pandoc.utils.stringify(meta.lang)) or 'en' + return {} -- eliminate meta so it doesn't get spellchecked +end + +local function run_spellcheck(lang) + local keys = {} + local wordlist = words[lang] + for k,_ in pairs(wordlist) do + keys[#keys + 1] = k + end + local inp = table.concat(keys, '\n') + local outp = pandoc.pipe('aspell_frontend', {'list','-l',lang}, inp) + for w in string.gmatch(outp, "([%S]+)\n") do + io.write(w) + if lang ~= deflang then + io.write("\t[" .. lang .. "]") + end + io.write("\n") + end +end + +local function results(el) + pandoc.walk_block(pandoc.Div(el.blocks), {Str = function(e) add_to_dict(deflang, e.text) end}) + for lang,v in pairs(words) do + run_spellcheck(lang) + end + os.exit(0) +end + +local function checkstr(el) + add_to_dict(deflang, el.text) +end + +local function checkspan(el) + local lang = el.attributes.lang + if not lang then return nil end + pandoc.walk_inline(el, {Str = function(e) add_to_dict(lang, e.text) end}) + return {} -- remove span, so it doesn't get checked again +end + +local function checkdiv(el) + local lang = el.attributes.lang + if not lang then return nil end + pandoc.walk_block(el, {Str = function(e) add_to_dict(lang, e.text) end}) + return {} -- remove div, so it doesn't get checked again +end + +return {{Meta = get_deflang}, + {Div = checkdiv, Span = checkspan}, + {Str = function(e) add_to_dict(deflang, e.text) end, Pandoc = results}} diff --git a/functions/calling-functions.md b/functions/calling-functions.md deleted file mode 100644 index 4294766..0000000 --- a/functions/calling-functions.md +++ /dev/null @@ -1,3 +0,0 @@ -# C++ functions: calling functions - -This topic is currently under construction and will soon be filled with information :) diff --git a/functions/member-functions.md b/functions/member-functions.md deleted file mode 100644 index 2a02f06..0000000 --- a/functions/member-functions.md +++ /dev/null @@ -1,3 +0,0 @@ -# C++ functions: member functions - -This topic is currently under construction and will soon be filled with information :) diff --git a/object-model/constant-objects.md b/object-model/constant-objects.md deleted file mode 100644 index 6085145..0000000 --- a/object-model/constant-objects.md +++ /dev/null @@ -1,3 +0,0 @@ -# C++ object model: constant objects - -This topic is currently under construction and will soon be filled with information :) diff --git a/object-model/constructors.md b/object-model/constructors.md deleted file mode 100644 index 346e2d4..0000000 --- a/object-model/constructors.md +++ /dev/null @@ -1,3 +0,0 @@ -# C++ object model: constructor - -This topic is currently under construction and will soon be filled with information :) diff --git a/object-model/declarations.md b/object-model/declarations.md deleted file mode 100644 index 4aa1388..0000000 --- a/object-model/declarations.md +++ /dev/null @@ -1,3 +0,0 @@ -# C++ object model: declarations - -This topic is currently under construction and will soon be filled with information :) diff --git a/object-model/move-semantics.md b/object-model/move-semantics.md deleted file mode 100644 index 67b300a..0000000 --- a/object-model/move-semantics.md +++ /dev/null @@ -1,3 +0,0 @@ -# C++ object model: move semantics - -This topic is currently under construction and will soon be filled with information :) diff --git a/object-model/objects.md b/object-model/objects.md deleted file mode 100644 index e1f8793..0000000 --- a/object-model/objects.md +++ /dev/null @@ -1,3 +0,0 @@ -# C++ object model: objects - -This topic is currently under construction and will soon be filled with information :) diff --git a/object-model/rule-of-five.md b/object-model/rule-of-five.md deleted file mode 100644 index f020f8f..0000000 --- a/object-model/rule-of-five.md +++ /dev/null @@ -1,3 +0,0 @@ -# C++ object model: rule of five - -This topic is currently under construction and will soon be filled with information :) diff --git a/object-model/rule-of-zero.md b/object-model/rule-of-zero.md deleted file mode 100644 index 9f31009..0000000 --- a/object-model/rule-of-zero.md +++ /dev/null @@ -1,3 +0,0 @@ -# C++ object model: rule of zero - -This topic is currently under construction and will soon be filled with information :) diff --git a/object-model/special-member-functions.md b/object-model/special-member-functions.md deleted file mode 100644 index 812ebaf..0000000 --- a/object-model/special-member-functions.md +++ /dev/null @@ -1,3 +0,0 @@ -# C++ object model: special member functions - -This topic is currently under construction and will soon be filled with information :) diff --git a/object-model/types.md b/object-model/types.md deleted file mode 100644 index 8060a79..0000000 --- a/object-model/types.md +++ /dev/null @@ -1,3 +0,0 @@ -# C++ object model: types - -This topic is currently under construction and will soon be filled with information :) diff --git a/Readme.md b/old/Readme.md similarity index 100% rename from Readme.md rename to old/Readme.md diff --git a/gen_readme.py b/old/gen_readme.py similarity index 100% rename from gen_readme.py rename to old/gen_readme.py diff --git a/skeleton.md b/old/skeleton.md similarity index 100% rename from skeleton.md rename to old/skeleton.md diff --git a/tools/pytest.ini b/old/tools/pytest.ini similarity index 100% rename from tools/pytest.ini rename to old/tools/pytest.ini diff --git a/tools/requirements.txt b/old/tools/requirements.txt similarity index 100% rename from tools/requirements.txt rename to old/tools/requirements.txt diff --git a/tools/tests/TEST_INPUTS/fix_wrong_sections.md b/old/tools/tests/TEST_INPUTS/fix_wrong_sections.md similarity index 100% rename from tools/tests/TEST_INPUTS/fix_wrong_sections.md rename to old/tools/tests/TEST_INPUTS/fix_wrong_sections.md diff --git a/tools/tests/TEST_INPUTS/missing_sections.md b/old/tools/tests/TEST_INPUTS/missing_sections.md similarity index 100% rename from tools/tests/TEST_INPUTS/missing_sections.md rename to old/tools/tests/TEST_INPUTS/missing_sections.md diff --git a/tools/tests/TEST_INPUTS/test_skeleton.md b/old/tools/tests/TEST_INPUTS/test_skeleton.md similarity index 100% rename from tools/tests/TEST_INPUTS/test_skeleton.md rename to old/tools/tests/TEST_INPUTS/test_skeleton.md diff --git a/tools/tests/TEST_INPUTS/user_content_heading_topic.md b/old/tools/tests/TEST_INPUTS/user_content_heading_topic.md similarity index 100% rename from tools/tests/TEST_INPUTS/user_content_heading_topic.md rename to old/tools/tests/TEST_INPUTS/user_content_heading_topic.md diff --git a/tools/tests/topic_updater_test.py b/old/tools/tests/topic_updater_test.py similarity index 100% rename from tools/tests/topic_updater_test.py rename to old/tools/tests/topic_updater_test.py diff --git a/topic_updater.py b/old/topic_updater.py similarity index 100% rename from topic_updater.py rename to old/topic_updater.py diff --git a/program-design/concepts.md b/program-design/concepts.md deleted file mode 100644 index df6c8a0..0000000 --- a/program-design/concepts.md +++ /dev/null @@ -1 +0,0 @@ -See [concepts](../compile-time-programmings/concepts.md). diff --git a/spellcheck/spellcheck_expected.txt b/spellcheck/spellcheck_expected.txt new file mode 100644 index 0000000..8bec394 --- /dev/null +++ b/spellcheck/spellcheck_expected.txt @@ -0,0 +1,34 @@ +args +Bjarne +checkmark +computable +constexpr +cppreference +decltype +Engelhart +EPUB +errno +expr +Florian +fmt +func +Furst +Hyland +IDEs +JC +Krathwohl +ness +noexcept +NRVO +req +RVO +Sattler +SFINAE +SG +Stroustrup +struct +udl +UDL +UDLs +ver +Winkel diff --git a/spellcheck/wordlist b/spellcheck/wordlist new file mode 100644 index 0000000..416bd6c --- /dev/null +++ b/spellcheck/wordlist @@ -0,0 +1,12 @@ +personal_ws-1.1 en 11 +destructors +invariants +metaprogramming +namespace +namespaces +preprocessor +redeclarations +toolchains +toolchain +boolean +lawyering diff --git a/templates/bootstrap_menu.html b/templates/bootstrap_menu.html new file mode 100644 index 0000000..ff41b51 --- /dev/null +++ b/templates/bootstrap_menu.html @@ -0,0 +1,127 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +$for(author-meta)$ + +$endfor$ +$if(date-meta)$ + +$endif$ + $if(title-prefix)$$title-prefix$ - $endif$$pagetitle$ + +$if(quotes)$ + +$endif$ +$if(highlighting-css)$ + +$endif$ +$for(css)$ + +$endfor$ +$if(math)$ + $math$ +$endif$ +$for(header-includes)$ + $header-includes$ +$endfor$ + + + + + $if(title)$ +
+
+
+ $title$ +
    + $for(author)$ +

  • $author$

    • + $endfor$ + $if(date)$ +

  • $date$

    • + $endif$ +
+
+
+
+ $endif$ +
+
+ $if(toc)$ +
+
+ + $toc$ + +
+
+ $endif$ +
+ $for(include-before)$ + $include-before$ + $endfor$ + $body$ + $for(include-after)$ + $include-after$ + $endfor$ +
+
+
+$if(analytics)$ + + + + diff --git a/templates/clean_menu.html b/templates/clean_menu.html new file mode 100644 index 0000000..9848be5 --- /dev/null +++ b/templates/clean_menu.html @@ -0,0 +1,129 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +$for(author-meta)$ + +$endfor$ +$if(date-meta)$ + +$endif$ + $if(title-prefix)$$title-prefix$ - $endif$$pagetitle$ + + +$if(quotes)$ + +$endif$ +$if(highlighting-css)$ + +$endif$ +$for(css)$ + +$endfor$ +$if(math)$ + $math$ +$endif$ +$for(header-includes)$ + $header-includes$ +$endfor$ + + + + + $if(title)$ +
+
+
+ $title$ +
    + $for(author)$ +

  • $author$

    • + $endfor$ + $if(date)$ +

  • $date$

    • + $endif$ +
+
+
+
+
+ $else$ +
+ $endif$ +
+ $if(toc)$ +
+
+ + $toc$ + +
+
+ $endif$ +
+ $for(include-before)$ + $include-before$ + $endfor$ + $body$ + $for(include-after)$ + $include-after$ + $endfor$ +
+
+
+$if(analytics)$ + + + + diff --git a/templates/easy_template.html b/templates/easy_template.html new file mode 100644 index 0000000..e0ce071 --- /dev/null +++ b/templates/easy_template.html @@ -0,0 +1,128 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +$for(author-meta)$ + +$endfor$ +$if(date-meta)$ + +$endif$ + $if(title-prefix)$$title-prefix$ - $endif$$pagetitle$ + +$if(quotes)$ + +$endif$ +$if(highlighting-css)$ + +$endif$ +$for(css)$ + +$endfor$ +$if(math)$ + $math$ +$endif$ +$for(header-includes)$ + $header-includes$ +$endfor$ + + + + + $if(title)$ +
+
+
+ $title$ +
    + $for(author)$ +

  • $author$

    • + $endfor$ + $if(date)$ +

  • $date$

    • + $endif$ +
+
+
+
+ $endif$ +
+
+ $if(toc)$ +
+
+ + $toc$ + +
+
+ $endif$ +
+ $for(include-before)$ + $include-before$ + $endfor$ + $body$ + $for(include-after)$ + $include-after$ + $endfor$ +
+
+
+$if(analytics)$ + + + + diff --git a/templates/elegant_bootstrap_menu.html b/templates/elegant_bootstrap_menu.html new file mode 100644 index 0000000..e0ce071 --- /dev/null +++ b/templates/elegant_bootstrap_menu.html @@ -0,0 +1,128 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +$for(author-meta)$ + +$endfor$ +$if(date-meta)$ + +$endif$ + $if(title-prefix)$$title-prefix$ - $endif$$pagetitle$ + +$if(quotes)$ + +$endif$ +$if(highlighting-css)$ + +$endif$ +$for(css)$ + +$endfor$ +$if(math)$ + $math$ +$endif$ +$for(header-includes)$ + $header-includes$ +$endfor$ + + + + + $if(title)$ +
+
+
+ $title$ +
    + $for(author)$ +

  • $author$

    • + $endfor$ + $if(date)$ +

  • $date$

    • + $endif$ +
+
+
+
+ $endif$ +
+
+ $if(toc)$ +
+
+ + $toc$ + +
+
+ $endif$ +
+ $for(include-before)$ + $include-before$ + $endfor$ + $body$ + $for(include-after)$ + $include-after$ + $endfor$ +
+
+
+$if(analytics)$ + + + + diff --git a/templates/uikit.html b/templates/uikit.html new file mode 100644 index 0000000..abb5838 --- /dev/null +++ b/templates/uikit.html @@ -0,0 +1,115 @@ + + + + + + + $if(title)$$title$$endif$ + + + +$if(template_css)$ + +$else$ + +$endif$ + + + + + + + + + + + + + + $for(author-meta)$ + + $endfor$ + $if(date-meta)$ + + $endif$ + + $if(version-meta)$ + + $endif$ + + $if(title-prefix)$$title-prefix$ - $endif$$pagetitle$ + + $if(quotes)$ + + $endif$ + $if(highlighting-css)$ + + $endif$ + $for(css)$ + + $endfor$ + $if(math)$ + $math$ + $endif$ + $for(header-includes)$ + $header-includes$ + $endfor$ + + + + + +
+ + $if(title)$ +
+
+

$title$

+ $if(date)$ +

$date$

+ $endif$ + + $if(version)$ +

Version $version$

+ $endif$ + + $for(author)$ +

$author$

+ $endfor$ +
+
+ $endif$ + +
+
+
+
+ + $if(toc)$ + $toc$ + $endif$ + +
+
+
+ +
+$body$ +
+
+$if(analytics)$ + +
+ + diff --git a/user-defined-types/user-defined-literals.md b/user-defined-types/user-defined-literals.md deleted file mode 100644 index c23e1b2..0000000 --- a/user-defined-types/user-defined-literals.md +++ /dev/null @@ -1 +0,0 @@ -See [user-defined-literals](../functions/user-defined-literals.md). From f6a3da0d6331178e34689dcf9929565fa0628bab Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 22 Apr 2021 16:59:09 -0700 Subject: [PATCH 02/64] Added some information to the README document and made some corrections to the main document. --- README.md | 16 +++++++++++++++- doc/main.md | 17 +++++++++-------- 2 files changed, 24 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 0e99713..937988d 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,23 @@ +README +====== + +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://mdadams.github.io/sg20_guidelines_for_teaching_cpp/latest + The following software is needed to build the document: - pandoc - aspell - make - - various base POSIX utilities such as awk and sed + - various basic POSIX utilities, including (amongst others): + - awk + - sed To build, simply type: diff --git a/doc/main.md b/doc/main.md index d532fe8..c0d148c 100644 --- a/doc/main.md +++ b/doc/main.md @@ -18,14 +18,15 @@ are presented. There is one section per module/area. For each module/area, a table listing the various topics in that module/area is provided. -The ID for a module/area is linked to the detailed coverage of that -module/area that comes later in the document. -In the table, a checkmark indicates that learning outcomes exist for the -specific proficiency level. -A dash indicates that no learning outcomes exist for the specific -proficiency level (simply because there -are not any, not because the information is missing). -In the case that the information for a knowledge unit is completely +The ID for a topic is linked to the detailed coverage of that +topic that comes later in the document. +If a topic has any learning outcomes at a given proficiency level, this is +indicated by a checkmark ("✔️"). +If a topic has no learning outcomes +(simply because there +are not any, not because the information is missing), +this is indicated by an em dash ("—"). +In the case that the information for a topic is completely missing, a "❌" symbol is used. [**NOTE**: These topics are taken mostly from the SG20 GitHub repository. From ffc6100dc39a3381717fa1bb0b9daba0310c46c7 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 22 Apr 2021 22:42:09 -0700 Subject: [PATCH 03/64] 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. --- bin/make_markdown | 3 +- .../meta-error-handling/static_assert.md | 145 ++++++++++++++++++ doc/introduction.md | 36 ++--- doc/knowledge_areas.dat | 2 +- doc/main.md | 14 +- 5 files changed, 173 insertions(+), 27 deletions(-) create mode 100644 doc/areas/meta-error-handling/static_assert.md diff --git a/bin/make_markdown b/bin/make_markdown index a547075..bbb03fc 100755 --- a/bin/make_markdown +++ b/bin/make_markdown @@ -4,7 +4,8 @@ awk ' function output(level, old_level, label, basic, intermediate, advanced, text) { #bad_char = "🤢"; - bad_char = "❌"; + #bad_char = "❌"; + bad_char = "?"; #check_char = "✓" check_char = "✔️"; emdash = "—"; diff --git a/doc/areas/meta-error-handling/static_assert.md b/doc/areas/meta-error-handling/static_assert.md new file mode 100644 index 0000000..d3c6a46 --- /dev/null +++ b/doc/areas/meta-error-handling/static_assert.md @@ -0,0 +1,145 @@ +## Meta-error handling: `static_assert` {#static-assert} + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +### Overview + +_Provides a short natural language abstract of the module’s contents._ +_Specifies the different levels of teaching._ + + + + + + + + + + + + + + + + + + +
LevelObjectives
FoundationalCalling static_assert with a constant expression
MainUsing static_assert to detect contract violations and improve error messages
Advanced
+ +### Motivation + +_Why is this important?_ +_Why do we want to learn/teach this topic?_ + +`static_assert` allows the developer to enforce that conditions which can +be checked during compilation will force build errors when violated. +Additionally, they are the best mechanism by which a developer can pass +useful information to other developers regarding what violation occurred or +what must be done, instead. + +### Topic introduction + +_Very brief introduction to the topic._ + +`static_assert` is a compile-time evaluated function that asserts the +truth of a supplied predicate, issuing an optional user-supplied error +message if the predicate is `false`. + +### Foundational: Calling `static_assert` with a constant expression {#static-assert-basic} + +#### Background/Required Knowledge + +A student: + +* Should be able to explain the difference between code evaluated at compile-time and run-time +* Should be able to cite some examples of compile-time known information, such as `sizeof(T)` + +#### Student outcomes + +_A list of things "a student should be able to" after the curriculum._ +_The next word should be an action word and testable in an exam._ +_Max 5 items._ + +A student should be able to: + +1. Assert the expected size of a structure using `static_assert` + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +#### Points to cover + +_This section lists important details for each point._ + +* X +* In addition to what is wrong, a good error message will inform the user of how to correct it + +### Main: Contracts and `static_assert` {#static-assert-intermediate} + +#### Background/Required Knowledge + +* All of the above. +* General understanding of compile-time requirements + +#### Student outcomes + +_A list of things "a student should be able to" after the curriculum._ +_The next word should be an action word and testable in an exam._ +_Max 5 items._ + +A student should be able to: + +1. Utilize `static_assert` to verify preconditions of a meta-function +2. Utilize `static_assert` to verify the results of meta-functions for known values + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +#### Points to cover + +_This section lists important details for each point._ + +* When writing a meta-function, use `static_assert` to test the results +* Write `static_assert` calls at the scope of the code they are guarding +```cpp +template +struct container { + std::map vals; + + // Test location #1 + static_assert( + std::is_default_constructible_v, + "container type T must be default constructible");i + + void add(int key, T const& t) { + // Test location #2 + static_assert( + std::is_default_constructible_v, + "container type T must be default constructible"); + // std::map::operator[] requires default constructible type for + // the value. This will cause a build failure deep in the + // implementation of std::map, when T is not default constructible + vals[key] = t; + } +}; + +struct NoDefCtor { + NoDefCtor() = delete; + NoDefCtor(double d) {} +}; + +container c; // If Test #1 was omitted, this would succeed +// This is ill-formed. Test #2 would catch this and provide a better +// error message for the user +c.add(42, NoDefCtor(1.0)); +``` + +### Advanced {#static-assert-advanced} + +_These are important topics that are not expected to be covered but provide +guidance where one can continue to investigate this topic in more depth._ diff --git a/doc/introduction.md b/doc/introduction.md index 8db64ab..196ef89 100644 --- a/doc/introduction.md +++ b/doc/introduction.md @@ -18,6 +18,12 @@ curricula for a wide variety of courses that differ in focus and level of sophistication. (This said, however, some links to other documents with examples of curricula for specific courses may be included herein.) +This document only intends to target the teaching of the +most recently ratified version of the C++ standard. +(This said, however, since older versions of this document are also +available, these older versions may be of some use to those who need +guidance in older versions of the standard, at least versions that +do not predate C++20.) # Use of This Document @@ -38,14 +44,14 @@ please read the section [How to Contribute](#contributing). # Organization of This Document The various concepts (i.e., ideas) to potentially be covered -are partitioned into modules/areas. -A module/area is very broad in scope and consists of numerous topics. +are partitioned into modules. +A module is very broad in scope and consists of numerous topics. **[Note: Can I suggest that we use the term "area" or "unit" instead of "module"? I think that these other choices are better and also avoid any potential confusion over what is meant by "module" (i.e., C++ term versus plain English term).]** -For each module/area, topics related to the module/area are identified. +For each module, topics related to the module are identified. Then, for each topic, learning outcomes are specified. In order to address a wide variety of courses on C++, each topic is addressed at three proficiency levels. @@ -61,35 +67,27 @@ The three proficiency levels are as follows: - main. This level shows mainstream uses and techniques. For abstraction and organizational mechanisms it also demonstrates how to - build them. Note that a main description typically cannot be written - concisely without relying on the foundational sections for a variety of - facilities. This is a major reason to separate foundational and main - sections of the presentation of a facility. The main section should - give the learner a basic (but not detailed) understanding of how a + build them. + This level should also give the learner a basic (but not detailed) + understanding of how a facility might be implemented so that the learner can have a first-order understanding of any costs involved. - Avoid language lawyering in the main section. **[Note: The term "main" is not very descriptive/helpful. Could I suggest using "intermediate"?]** - advanced. This level gives information suitable for an expert. For most topics there is an expert level of knowledge that most programmers rarely need and techniques that require detailed understanding - of language rules or library implementation. Delving into advanced topics - early would be distracting and reinforce C++’s unfortunate reputation of - being “expert only.” The advanced features often are “expert only” but - the foundational and main descriptions should not be. Finally, we - explicitly mention subjects that are considered too advanced for inclusion - in the guidelines. + of language rules or library implementation. The remainder of this document is organized as follows. -The various topics are listed grouped by module/area. +The various topics are listed grouped by module. In cases where a topic might be classified into more -than one module/area, the topic is listed under the module/area of most direct +than one module, the topic is listed under the module of most direct relevance. This is done in order to avoid duplication of content. -(In the case that a module/unit is equally relevant to multiple modules/areas, +(In the case that a topic is equally relevant to multiple modules, the decision of which to select is made by a proverbial coin toss.) -The order in which modules/areas are presented +The order in which modules and topics are presented is not meant to imply any order of coverage in a course. The order in which items are listed is essentially arbitrary. diff --git a/doc/knowledge_areas.dat b/doc/knowledge_areas.dat index 6055f68..cda618a 100644 --- a/doc/knowledge_areas.dat +++ b/doc/knowledge_areas.dat @@ -42,7 +42,7 @@ I Inheritance and Class Hierarchies ? ? ? ? Run-Time Type Information CT Compile-Time Computation ? ? ? ? Constant Expressions and Constant Evaluation - ? ? ? ? static_assert + static-assert y y n `static_assert` T Generic Programming (Templates) ? ? ? ? Concepts ? ? ? ? SFINAE diff --git a/doc/main.md b/doc/main.md index c0d148c..f5be571 100644 --- a/doc/main.md +++ b/doc/main.md @@ -11,12 +11,12 @@ __INCLUDE__(doc/disclaimer.md) __INCLUDE__(doc/introduction.md) -# Summary of Modules/Areas and Topics +# Summary of Modules and Topics -In the sections that follow, the various modules/areas and topics +In the sections that follow, the various modules and topics are presented. -There is one section per module/area. -For each module/area, a table listing the various topics in that module/area +There is one section per module. +For each module, a table listing the various topics in that module is provided. The ID for a topic is linked to the detailed coverage of that topic that comes later in the document. @@ -27,7 +27,7 @@ If a topic has no learning outcomes are not any, not because the information is missing), this is indicated by an em dash ("—"). In the case that the information for a topic is completely -missing, a "❌" symbol is used. +missing, a question mark ("?") symbol is used. [**NOTE**: These topics are taken mostly from the SG20 GitHub repository. They are not intended to be complete in any sense. @@ -37,7 +37,7 @@ obvious.] __INCLUDE__(knowledge_areas_summary.md) -# Detailed Information for Modules/Areas and Topics +# Detailed Information for Modules and Topics [//]: # ( ********** START OF DETAILED TOPIC DOCUMENTS ********** ) @@ -51,6 +51,8 @@ __INCLUDE__(doc/areas/compile-time-programming/requires-expressions.md) __INCLUDE__(doc/areas/object-model/copy_elision.md) +__INCLUDE__(doc/areas/meta-error-handling/static_assert.md) + [//]: # ( ********** END OF DETAILED TOPIC DOCUMENTS ********** ) __INCLUDE__(doc/course_examples.md) From d7bc3f7e452377b099f5c18911a65046b21528a0 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 22 Apr 2021 23:10:56 -0700 Subject: [PATCH 04/64] Fixed some labelling-related issues in the document. --- .../compile-time-programming/requires-expressions.md | 12 ++++++------ doc/areas/functions/defaulted-parameters.md | 12 ++++++------ doc/areas/functions/user-defined-literals.md | 8 ++++---- doc/areas/object-model/copy-semantics.md | 11 +++++------ doc/areas/object-model/copy_elision.md | 8 ++++---- doc/knowledge_areas.dat | 6 +++--- 6 files changed, 28 insertions(+), 29 deletions(-) diff --git a/doc/areas/compile-time-programming/requires-expressions.md b/doc/areas/compile-time-programming/requires-expressions.md index 0c3325c..bfa8851 100644 --- a/doc/areas/compile-time-programming/requires-expressions.md +++ b/doc/areas/compile-time-programming/requires-expressions.md @@ -1,4 +1,4 @@ -## Module name: Requires Expressions {#req_expr} +## Module name: Requires Expressions {#req-expr} ### Overview @@ -33,7 +33,7 @@ Requires-expressions are compile-time predicates which evaluate to true when their specified set of expressions are all valid for a given set of inputs. -### Foundational: Writing requires-expressions +### Foundational: Writing requires-expressions {#req-expr-basic} #### Background/Required Knowledge @@ -46,7 +46,7 @@ It is helpful if: * The student is aware that attempting to specialize the template with types or values which do not match otherwise unstated assumptions will cause errors within the template. -#### Student outcomes {#req_expr-basic} +#### Student outcomes A student should be able to: @@ -74,7 +74,7 @@ not on the result of the operation. * Checks are performed by the compiler, not at run time. * If covering usage of requires-expression with requires-clause, [[Compile-time programming: requires clause]][3] demonstrate `requires requires` and show how to ever avoid writing it by using a concept. [[Compile-time programming: concepts]][1] -### Main: Advanced requirements +### Main: Advanced requirements {#req-expr-intermediate} #### Background/required knowledge @@ -85,7 +85,7 @@ A student is able to: * Write a concept [[Compile-time programming: concepts]][1] -#### Student outcomes {#req_expr-intermediate} +#### Student outcomes A student should be able to: @@ -109,7 +109,7 @@ static_assert(requires(S s) { { s.bar() } noexcept; } ); // Fails. s.bar() is no ``` * If the return-type-requirement of a compound-requirement is a concept, that concept is given the resulting type as the first parameter, followed by the specified parameters in the compound-requirement. `{ ++x } -> C` would substitute `C` and check that concept C is satisfied for those parameters. -### Advanced {#req_expr-advanced} +### Advanced {#req-expr-advanced} [1]: ../compile-time-programming/concepts.md [2]: ../compile-time-programming/function-templates.md diff --git a/doc/areas/functions/defaulted-parameters.md b/doc/areas/functions/defaulted-parameters.md index 708c4a9..3fe881f 100644 --- a/doc/areas/functions/defaulted-parameters.md +++ b/doc/areas/functions/defaulted-parameters.md @@ -1,4 +1,4 @@ -## Functions: default argument {#func_args} +## Functions: default argument {#func-args} _Skeleton instructions are typeset in italic text._ ### Overview @@ -38,7 +38,7 @@ without forcing changes to existing calling code. Explain how default arguments work and how to define them. -### Foundational: Using and defining functions with default arguments +### Foundational: Using and defining functions with default arguments {#func-args-basic} #### Background/Required Knowledge @@ -49,7 +49,7 @@ A student is able to: * Define member and non-member functions [[Functions: member functions]][2] * Explain what a default constructor is and does [[C++ object model: constructors]][3] -#### Student outcomes {#func_args-basic} +#### Student outcomes A student should be able to: @@ -71,13 +71,13 @@ A student should be able to: * Default values must start from the rightmost parameter and continue leftward without gaps * Considerations of when to use default arguments vs overload set -### Main: implementing * +### Main: implementing * {#func-args-intermediate} #### Background/required knowledge * All of the above. -#### Student outcomes {#func_args-intermediate} +#### Student outcomes A student should be able to: @@ -86,7 +86,7 @@ A student should be able to: #### Points to cover -### Advanced +### Advanced {#func-args-advanced} Subsequent redeclarations of the same function may add default argument values, which are then usable by callers. diff --git a/doc/areas/functions/user-defined-literals.md b/doc/areas/functions/user-defined-literals.md index 3f47168..2033513 100644 --- a/doc/areas/functions/user-defined-literals.md +++ b/doc/areas/functions/user-defined-literals.md @@ -42,7 +42,7 @@ _Very brief introduction to the topic._ * Explain the existence of user defined literals. Example: `12m + 17s` is terse, expressive and type safe. -### Foundational: Using UDLs +### Foundational: Using UDLs {#udl-basic} #### Background/Required Knowledge @@ -59,7 +59,7 @@ A student: * knows that namespaces exist, and namespace `std`. * knows what using-declarations and using-directives are. [[C++ object model: declarations]][2] -#### Student outcomes {#udl-basic} +#### Student outcomes _A list of things "a student should be able to" after the curriculum._ _The next word should be an action word and testable in an exam._ @@ -92,7 +92,7 @@ implementation-defined, unspecified, or undefined behavior._ _This section lists important details for each point._ -### Main: implementing UDLs +### Main: implementing UDLs {#udl-intermediate} #### Background/Required Knowledge @@ -100,7 +100,7 @@ _This section lists important details for each point._ * All of the above. -#### Student outcomes {#udl-intermediate} +#### Student outcomes _A list of things "a student should be able to" after the curriculum._ _The next word should be an action word and testable in an exam._ diff --git a/doc/areas/object-model/copy-semantics.md b/doc/areas/object-model/copy-semantics.md index d076b7b..2e271bc 100644 --- a/doc/areas/object-model/copy-semantics.md +++ b/doc/areas/object-model/copy-semantics.md @@ -39,8 +39,7 @@ _Very brief introduction to the topic._ Explains when and how objects are copied. -### Foundational: How and when are copies made - +### Foundational: How and when are copies made {#copy-basic} #### Background/Required Knowledge @@ -54,7 +53,7 @@ It helps when a student is able to: * use move semantics [[C++ object model: move semantics]][4] * explain special member functions [[C++ object model: special member functions]][5] -#### Student outcomes {#copy-basic} +#### Student outcomes _A list of things "a student should be able to" after the curriculum._ _The next word should be an action word and testable in an exam._ @@ -89,7 +88,7 @@ _This section lists important details for each point._ * Strings (copies the value) -### Main: Implementing user-defined copy operations +### Main: Implementing user-defined copy operations {#copy-intermediate} #### Background/Required Knowledge @@ -103,7 +102,7 @@ It helps when a student is able to: * explain the rule of zero [[C++ object model: rule-of-zero]][7] * explain the rule of five [[C++ object model: rule-of-five]][6] -#### Student outcomes {#copy-intermediate} +#### Student outcomes _A list of things "a student should be able to" after the curriculum._ _The next word should be an action word and testable in an exam._ @@ -135,7 +134,7 @@ _This section lists important details for each point._ * Rule-of-five * Copy assignment operators can be ref-qualified to avoid assigning into temporary objects. -### Advanced +### Advanced {#copy-advanced} _These are important topics that are not expected to be covered but provide guidance where one can continue to investigate this topic in more depth._ diff --git a/doc/areas/object-model/copy_elision.md b/doc/areas/object-model/copy_elision.md index 579d334..6650650 100644 --- a/doc/areas/object-model/copy_elision.md +++ b/doc/areas/object-model/copy_elision.md @@ -1,8 +1,8 @@ -## Copy Elision and Implicit Moving {#copy_elision} +## Copy Elision and Implicit Moving {#copy-elision} -### Basic Learning Outcomes {#copy_elision-basic} +### Basic Learning Outcomes {#copy-elision-basic} -### Intermediate Learning Outcomes {#copy_elision-intermediate} +### Intermediate Learning Outcomes {#copy-elision-intermediate} After completing this unit, the student should be able to: @@ -15,7 +15,7 @@ After completing this unit, the student should be able to: - for certain common code patterns, be able identify whether copy, move, or copy elision takes place. -### Advanced Learning Outcomes {#copy_elision-advanced} +### Advanced Learning Outcomes {#copy-elision-advanced} After completing this unit, the student should be able to: diff --git a/doc/knowledge_areas.dat b/doc/knowledge_areas.dat index cda618a..edc0efe 100644 --- a/doc/knowledge_areas.dat +++ b/doc/knowledge_areas.dat @@ -18,13 +18,13 @@ B Basics Types, Objects, Values, Expressions, Statements, and Control-Flow Const F Functions ? ? ? ? Calling Functions ? ? ? ? Parameter Passing (e.g., Passing By Value and Reference) - func_args y n n Default Arguments + func-args y n n Default Arguments ? ? ? ? Returning Multiple Values ? ? ? ? Overloading udl y y n User-Defined Literals C User-Defined Types (Classes) ? ? ? ? Special Member Functions - copy_elision n y y Copy Elision and Implicit Moving (e.g., RVO and NRVO, etc.) + copy-elision n y y Copy Elision and Implicit Moving (e.g., RVO and NRVO, etc.) ? ? ? ? Types ? ? ? ? Conversions ? ? ? ? Constructors and Destructors @@ -49,7 +49,7 @@ T Generic Programming (Templates) ? ? ? ? Template Metaprogramming ? ? ? ? Function Templates ? ? ? ? Requires Clauses - req_expr y y n Requires Expressions + req-expr y y n Requires Expressions EH Error Handling ? ? ? ? Classes of Errors ? ? ? ? errno From 03bb8efde5c2edf0e8ff94b0de42194f18a4ef25 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 22 Apr 2021 23:22:02 -0700 Subject: [PATCH 05/64] Made a few minor wording changes to the section on contributing. --- doc/contributing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/contributing.md b/doc/contributing.md index 011225d..9f66514 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -6,8 +6,8 @@ and the referenced documents as appropriate. All contributions to this project must be made in accordance with the license in section [License](#license). -This document only offers guidance on teaching C++ as it is specified -in the current version of the C++ standard. +This teaching-guidelines document only offers guidance on teaching C++ +as it is specified in the current version of the C++ standard. So, content should be presented relative to the most-recently ratified version of the standard. A detailed explanation of how to present the material for a topic is given in: @@ -29,7 +29,7 @@ background on the modular approach to teaching followed herein: In order to prepare content, it is important to understand what learning outcomes are, and how to prepare good ones. Some information on learning outcomes can be found in the -[references](#references). +[References](#references) section. The following document offers a concise introduction to learning outcomes: - Effective Use of Performance Objectives for Learning and Assessment From 0e24e79d081d991a328b958a4a7d5831a7ea8dd5 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 23 Apr 2021 09:06:32 -0700 Subject: [PATCH 06/64] Added two WG21 papers to the references section. --- doc/references.md | 10 ++++++++++ spellcheck/spellcheck_expected.txt | 2 ++ 2 files changed, 12 insertions(+) diff --git a/doc/references.md b/doc/references.md index 494478b..903e2b5 100644 --- a/doc/references.md +++ b/doc/references.md @@ -34,3 +34,13 @@ P2193 --- How to structure a teaching topic. . + +- JC van Winkel and Christopher Di Bella. + P1231 --- + Proposal for Study Group: C++ Education. + . + +- H. Hinnant, R. Orr, B. Stroustrup, D. Vandevoorde, and M. Wong. + P2000 --- + Direction for ISO C++, Section 5.1. + . diff --git a/spellcheck/spellcheck_expected.txt b/spellcheck/spellcheck_expected.txt index 8bec394..f0641a6 100644 --- a/spellcheck/spellcheck_expected.txt +++ b/spellcheck/spellcheck_expected.txt @@ -32,3 +32,5 @@ UDL UDLs ver Winkel +Hinnant +Vandevoorde From 13fd4a001a0dca884af543ab12448d3f3e754cc2 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 13 May 2021 20:53:01 -0700 Subject: [PATCH 07/64] 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. --- .github/workflows/ci.yml | 3 ++ .github/workflows/release.yml | 3 ++ Makefile | 41 +++++++++------- build/build | 58 ++++++++++++++++++----- build/deploy | 85 ++++++++++++++++++++++++++++------ build/prebuild | 13 +++++- doc/main.md | 3 +- doc/obtaining_document.md | 4 +- filters/meta_vars.lua | 19 ++++++++ images/cpp_logo.png | Bin 0 -> 23613 bytes templates/uikit.html | 7 +++ 11 files changed, 190 insertions(+), 46 deletions(-) create mode 100644 filters/meta_vars.lua create mode 100644 images/cpp_logo.png diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cf1bf02..af6a6ad 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,3 +1,6 @@ +# This action is used to perform a test build of the document that includes +# performing spell checking. + name: ci on: [push] diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 72639f4..abb6a6f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,3 +1,6 @@ +# This is an action that builds the document and deploys the build document +# to its associated GitHub pages site. + name: release on: diff --git a/Makefile b/Makefile index 88918b7..baa4e09 100644 --- a/Makefile +++ b/Makefile @@ -4,8 +4,12 @@ DOC_VERSION = X.Y.Z # Specify whether a spelling error is an error (as opposed to a warning). # This can be overridden when invoked from the automated build process. +# DOC_SPELLCHECK_MUST_PASS = 0 DOC_SPELLCHECK_MUST_PASS = 1 +# This can be overridden when invoked from the automated build process. +INSTALL_DIR = install + # All of the Markdown source files (that are not generated during build). SOURCES = \ doc/areas/compile-time-programming/requires-expressions.md \ @@ -31,18 +35,24 @@ GENERATED_MARKDOWN = \ # Define primary targets. ################################################################################ +# The all target builds the document in a minimal set of formats and +# performs a spell check. .PHONY: all all: documents spellcheck +# The documents target builds the document in a minimal set of formats. .PHONY: documents documents: guidelines.html guidelines_html guidelines.epub +# The world target builds the document in a few extra formats. .PHONY: world world: documents guidelines.pdf +# The spellcheck format performs a spell check on the document. .PHONY: spellcheck spellcheck: spellcheck_result.txt +# The clean target removes all files generated during the build process. .PHONY: clean clean: rm -f guidelines.html guidelines.pdf guidelines.epub guidelines.tex @@ -54,13 +64,21 @@ clean: rm -f spellcheck_result.txt rm -f spellcheck/spellcheck_expected_sorted.txt +# The install target installs the build document (in various formats) +# in the directory $(INSTALL_DIR). .PHONY: install -install: +install: all if [ ! -d $(INSTALL_DIR) ]; then mkdir -p $(INSTALL_DIR) || exit 1; fi - cp guidelines.html $(INSTALL_DIR)/index.html - #cp pandoc.css $(INSTALL_DIR)/pandoc.css - cp -r guidelines_html $(INSTALL_DIR)/split - cp guidelines.epub $(INSTALL_DIR) + for dir in html html/images; do \ + if [ ! -d "$(INSTALL_DIR)/$$dir" ]; then \ + mkdir -p "$(INSTALL_DIR)/$$dir" || exit 1; \ + fi; \ + done + cp -f images/cpp_logo.png $(INSTALL_DIR)/html/images + cp -f guidelines.html $(INSTALL_DIR)/html/index.html + ln -s -f html/index.html $(INSTALL_DIR) + cp -r -f guidelines_html $(INSTALL_DIR)/html_split + cp -f guidelines.epub $(INSTALL_DIR) ################################################################################ # Preprocessing setup. @@ -80,17 +98,12 @@ PANDOC_OPTIONS += --toc --toc-depth 3 PANDOC_OPTIONS += --number-sections PANDOC_OPTIONS += --standalone PANDOC_OPTIONS += --pdf-engine=xelatex +#PANDOC_OPTIONS += --lua-filter=filters/meta_vars.lua #PANDOC_OPTIONS += --metadata date="`date +%Y-%m-%d`" -PANDOC_OPTIONS += --variable version=$(DOC_VERSION) -#PANDOC_OPTIONS += --variable mainfont=DejaVuSerif --variable sansfont=DejaVuSans +PANDOC_OPTIONS += --metadata version=$(DOC_VERSION) INPUT_FORMAT = markdown+header_attributes+multiline_tables -#CSS_FILE = css/default-pandoc.css -#CSS_FILE = css/github-pandoc.css -#CSS_FILE = css/pandoc.css -#CSS_FILE = css/epub.css - EPUB_CSS_FILE = css/default-pandoc.css #HTML_TEMPLATE = templates/bootstrap_menu.html @@ -100,11 +113,7 @@ HTML_TEMPLATE = templates/uikit.html # Rules for generating the document in various formats. ################################################################################ -#pandoc.css: -# [ -e pandoc.css ] || ln -s $(CSS_FILE) pandoc.css - guidelines.html: $(GENERATED_MARKDOWN) - #pandoc $(PANDOC_OPTIONS) -c pandoc.css --from $(INPUT_FORMAT) -o $@ main.gen.md pandoc $(PANDOC_OPTIONS) --template $(HTML_TEMPLATE) --from $(INPUT_FORMAT) -o $@ main.gen.md guidelines.epub: $(GENERATED_MARKDOWN) diff --git a/build/build b/build/build index 8924d54..aa7934a 100755 --- a/build/build +++ b/build/build @@ -1,24 +1,52 @@ #! /usr/bin/env bash -# Michael Adams (mdadams@ece.uvic.ca) -cmd_dir=$(dirname "$0") || exit 1 -source_dir="$cmd_dir/.." +################################################################################ +# Some helper functions. +################################################################################ +# Terminate with error. panic() { - echo "ERROR: $@" + echo "ERROR: $@" 1>&2 exit 1 } +# Print usage information. usage() { echo "bad usage: $@" cat <<- EOF - $0 -d install_dir -z github_ref + build - Build the document. + + Usage + ===== + + $0 -d \$install_dir -z \$github_ref + + Options + ======= + + -d \$install_dir + Set the installation directory for the built release to \$install_dir. + + -z \$github_ref + Set the GitHub ref to $\github_ref. + (This is used to determine the version of the document being released.) EOF exit 2 } +################################################################################ +# Perform some basic initialization. +################################################################################ + +cmd_dir=$(dirname "$0") || panic "cannot determine directory name" +source_dir="$cmd_dir/.." + +################################################################################ +# Parse command line. +################################################################################ + install_dir= github_ref= spellcheck=0 @@ -45,18 +73,24 @@ if [ -z "$github_ref" ]; then usage "no github ref specified" fi -version="$(awk -v FS="/" '{print $3;}' <<< "$github_ref")" || panic +################################################################################ +# Build the document. +################################################################################ + +version="$(awk -v FS="/" '{print $3;}' <<< "$github_ref")" || \ + panic "cannot determine document version" if [ ! -d "$install_dir" ]; then - mkdir -p "$install_dir" || panic + mkdir -p "$install_dir" || \ + panic "cannot make installation directory $install_dir" fi -(cd "$source_dir" && make clean) || panic +(cd "$source_dir" && make clean) || \ + panic "cannot make clean" (cd "$source_dir" && \ make DOC_VERSION="$version" DOC_SPELLCHECK_MUST_PASS="$spellcheck" all) || \ - panic + panic "cannot build document" -INSTALL_DIR="$install_dir" make install -#cp "$source_dir/guidelines.html" "$install_dir/index.html" || panic -#cp "$source_dir/pandoc.css" "$install_dir" || panic +INSTALL_DIR="$install_dir" make install || \ + panic "cannot install release" diff --git a/build/deploy b/build/deploy index 6a9515e..01b0c29 100755 --- a/build/deploy +++ b/build/deploy @@ -1,21 +1,53 @@ #! /usr/bin/env bash -# Michael Adams (mdadams@ece.uvic.ca) -cmd_dir=$(dirname "$0") || exit 1 -source_dir="$cmd_dir/.." +################################################################################ +# Some helper functions. +################################################################################ +# Terminate with error. panic() { - echo "ERROR: $@" + echo "ERROR: $@" 1>&2 exit 1 } usage() { echo "bad usage: $@" + cat <<- EOF + deploy - deploy new release of document to GitHub Pages repository + + Usage + ===== + + $0 [options] + + Options + ======= + + -b \$branch + Set the deployment branch to \$branch. + -t \$tmp_dir + Set the temporary directory to $\tmp_dir. + -i \$in_dir + Set the input directory to \$in_dir. + -r \$repo_name + Set the deployment repository to \$repo_name. + -z \$github_ref + Set the GitHub ref to \$github_ref. + -f + Allow private key file to be overwritten. + -n + Prepare to push to deployment repository but do not actually + push the changes. (This is only for testing purposes.) + EOF exit 2 } +################################################################################ +# Parse command line. +################################################################################ + branch="gh-pages" in_dir= repo_name= @@ -23,6 +55,7 @@ tmp_dir="${TMPDIR:-/tmp}" github_ref= force=0 prepare_only=0 +verbose=1 while getopts b:i:r:t:z:fn opt; do case $opt in @@ -68,7 +101,16 @@ echo "input directory $in_dir" echo "repository name $repo_name" echo "github ref $github_ref" -version="$(awk -v FS="/" '{print $3;}' <<< "$github_ref")" || panic +################################################################################ +# Perform some basic initialization. +################################################################################ + +cmd_dir=$(dirname "$0") || \ + panic "cannot determine directory" +source_dir="$cmd_dir/.." + +version="$(awk -v FS="/" '{print $3;}' <<< "$github_ref")" || \ + panic "cannot determine document version" echo "version $version" tmp_dir="$tmp_dir/deploy" @@ -76,16 +118,24 @@ tmp_dir="$tmp_dir/deploy" git_dir="$tmp_dir/git" ssh_dir="$HOME/.ssh" private_key_file="$ssh_dir/private_key" +version_dir="$git_dir/$version" +repo_url="ssh://git@github.com/$repo_name.git" + +################################################################################ +# Setup SSH client configuration. +################################################################################ if [ "$force" -eq 0 -a -e "$private_key_file" ]; then panic "private key file already exists" fi if [ ! -d "$ssh_dir" ]; then - mkdir -p "$ssh_dir" || panic "cannot make directory $ssh_dir" + mkdir -p "$ssh_dir" || \ + panic "cannot make directory $ssh_dir" fi if [ ! -d "$tmp_dir" ]; then - mkdir -p "$ssh_dir" || panic "cannot make directory $ssh_dir" + mkdir -p "$ssh_dir" || \ + panic "cannot make directory $ssh_dir" fi echo "$DEPLOY_KEY" > "$private_key_file" || \ @@ -93,17 +143,22 @@ echo "$DEPLOY_KEY" > "$private_key_file" || \ chmod u+rw,g=,o= "$private_key_file" || \ panic "cannot set permissions for private key file" -version_dir="$git_dir/$version" -repo_url="ssh://git@github.com/$repo_name.git" - if [ -z "$SSH_AGENT_PID" ]; then - eval $(ssh-agent) || panic "cannot start ssh-agent" + eval $(ssh-agent) || \ + panic "cannot start ssh-agent" fi -ssh-add "$private_key_file" || panic "ssh-add failed" +ssh-add "$private_key_file" || \ + panic "ssh-add failed" + +################################################################################ +# Add new release to GitHub pages repository. +################################################################################ git clone "$repo_url" "$git_dir" || \ panic "clone failed" +# Create an orphaned branch for the web site content if the branch does +# not already exist. git -C "$git_dir" ls-remote --exit-code --heads "$repo_url" "$branch" \ > /dev/null status=$? @@ -142,11 +197,13 @@ fi ln -s "latest/index.html" "$target" || \ panic "ln failed" -ls -al "$git_dir"/* +if [ "$verbose" -ne 0 ]; then + ls -al "$git_dir"/* +fi git -C "$git_dir" add . || \ panic "git add failed" -git -C "$git_dir" commit -m "Deploying" || \ +git -C "$git_dir" commit -m "Deploying release $version" || \ panic "git commit failed" if [ "$prepare_only" -eq 0 ]; then echo "Pushing changes." diff --git a/build/prebuild b/build/prebuild index 83c18f1..4fccda3 100755 --- a/build/prebuild +++ b/build/prebuild @@ -1,10 +1,19 @@ #! /usr/bin/env bash -# Michael Adams (mdadams@ece.uvic.ca) +# Terminate with error. +panic() +{ + echo "ERROR: $@" 1>&2 + exit 1 +} + +# Initialize the list of required packages. packages=() packages+=(pandoc) packages+=(texinfo) packages+=(aspell) #packages+=(hunspell) -sudo apt-get install -y "${packages[@]}" +# Install the packages. +sudo apt-get install -y "${packages[@]}" || \ + panic "unable to install packages" diff --git a/doc/main.md b/doc/main.md index f5be571..aebb686 100644 --- a/doc/main.md +++ b/doc/main.md @@ -1,6 +1,7 @@ --- +title_logo: images/cpp_logo.png title: Guidelines for Teaching C++ -author: SG20 +author: SG20 (ISO C++ Study Group on Education) geometry: margin=1in output: pdf_document --- diff --git a/doc/obtaining_document.md b/doc/obtaining_document.md index 9b34661..a1cd90e 100644 --- a/doc/obtaining_document.md +++ b/doc/obtaining_document.md @@ -9,12 +9,14 @@ following formats: 1. online (HTML) format as a single large HTML document: + (or equivalently, + ) 2. EPUB format: 3. online (HTML) format, split across multiple HTML documents: - + **[Note: The support for this format needs more work to look nice.]** Older versions of this document are also available. diff --git a/filters/meta_vars.lua b/filters/meta_vars.lua new file mode 100644 index 0000000..0a39558 --- /dev/null +++ b/filters/meta_vars.lua @@ -0,0 +1,19 @@ +local vars = {} + +function get_vars (meta) + for k, v in pairs(meta) do + if type(v) == 'table' and v.t == 'MetaInlines' then + vars["%" .. k .. "%"] = {table.unpack(v)} + end + end +end + +function replace (el) + if vars[el.text] then + return pandoc.Span(vars[el.text]) + else + return el + end +end + +return {{Meta = get_vars}, {Str = replace}} diff --git a/images/cpp_logo.png b/images/cpp_logo.png new file mode 100644 index 0000000000000000000000000000000000000000..780e8a32bdd384c1dbd0fc999b9ef9ed2e1bdad6 GIT binary patch literal 23613 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 literal 0 HcmV?d00001 diff --git a/templates/uikit.html b/templates/uikit.html index abb5838..c1d6bb2 100644 --- a/templates/uikit.html +++ b/templates/uikit.html @@ -65,6 +65,13 @@ $if(title)$
+ + $if(version)$ +
+ +
+ $endif$ +

$title$

$if(date)$ From 1730ea8f96a2a99f62004a09b7d6f234ebd89e28 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 13 May 2021 21:27:55 -0700 Subject: [PATCH 08/64] 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. --- build/build | 7 ++++++- build/deploy | 12 ++++++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/build/build b/build/build index aa7934a..7f31301 100755 --- a/build/build +++ b/build/build @@ -32,6 +32,11 @@ usage() -z \$github_ref Set the GitHub ref to $\github_ref. (This is used to determine the version of the document being released.) + + Examples + ======== + + $0 -d /tmp/sg20_test/install -z refs/tags/v0.0.1 EOF exit 2 } @@ -92,5 +97,5 @@ fi make DOC_VERSION="$version" DOC_SPELLCHECK_MUST_PASS="$spellcheck" all) || \ panic "cannot build document" -INSTALL_DIR="$install_dir" make install || \ +make INSTALL_DIR="$install_dir" install || \ panic "cannot install release" diff --git a/build/deploy b/build/deploy index 01b0c29..3a2f38a 100755 --- a/build/deploy +++ b/build/deploy @@ -31,8 +31,11 @@ usage() Set the temporary directory to $\tmp_dir. -i \$in_dir Set the input directory to \$in_dir. + This is the directory containing the output of the document build + process. -r \$repo_name Set the deployment repository to \$repo_name. + This includes both the user/organization and repository name. -z \$github_ref Set the GitHub ref to \$github_ref. -f @@ -40,6 +43,13 @@ usage() -n Prepare to push to deployment repository but do not actually push the changes. (This is only for testing purposes.) + + Examples + ======== + + export DEPLOY_KEY=.... # private SSH key + $0 -n -f -r mdadams/sg20_guidelines_for_teaching_cpp -b gh-pages \\ + -t /tmp/sg20_test/tmp -i /tmp/sg20_test/install -z refs/tags/v1.0.0 EOF exit 2 } @@ -121,6 +131,8 @@ private_key_file="$ssh_dir/private_key" version_dir="$git_dir/$version" repo_url="ssh://git@github.com/$repo_name.git" +echo "repository URL: $repo_url" + ################################################################################ # Setup SSH client configuration. ################################################################################ From 487000605aa4130231f6eca7b8f4331ed1620737 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 13 May 2021 21:51:53 -0700 Subject: [PATCH 09/64] Changed the document deploy script so that it no longer creates a top-level index.html file in the target repository. --- build/deploy | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/build/deploy b/build/deploy index 3a2f38a..0696f3d 100755 --- a/build/deploy +++ b/build/deploy @@ -202,12 +202,12 @@ if [ -h "$target" -o -e "$target" ]; then fi ln -s "$version" "$target" || \ panic "ln failed" -target="$git_dir/index.html" -if [ -h "$target" -o -e "$target" ]; then - rm -f "$target" || panic "rm failed" -fi -ln -s "latest/index.html" "$target" || \ - panic "ln failed" +#target="$git_dir/index.html" +#if [ -h "$target" -o -e "$target" ]; then +# rm -f "$target" || panic "rm failed" +#fi +#ln -s "latest/html" "$target" || \ +# panic "ln failed" if [ "$verbose" -ne 0 ]; then ls -al "$git_dir"/* From f7732512b1779f7de117199e00f97f883eb8f456 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 13 May 2021 21:58:06 -0700 Subject: [PATCH 10/64] Changed the target of the symlink for the latest version of the document in the document deploy script. --- build/deploy | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build/deploy b/build/deploy index 0696f3d..8792bdb 100755 --- a/build/deploy +++ b/build/deploy @@ -200,7 +200,7 @@ target="$git_dir/latest" if [ -h "$target" -o -e "$target" ]; then rm -f "$target" || panic "rm failed" fi -ln -s "$version" "$target" || \ +ln -s "$version/html" "$target" || \ panic "ln failed" #target="$git_dir/index.html" #if [ -h "$target" -o -e "$target" ]; then From 3bc0b247e21405ca66060c871c59143b27046ea1 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 13 May 2021 22:02:13 -0700 Subject: [PATCH 11/64] Removed an outdated link from the document. --- doc/obtaining_document.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/obtaining_document.md b/doc/obtaining_document.md index a1cd90e..9c6734d 100644 --- a/doc/obtaining_document.md +++ b/doc/obtaining_document.md @@ -8,9 +8,7 @@ The version of the document that you are currently reading is available in the following formats: 1. online (HTML) format as a single large HTML document: - - (or equivalently, - ) + 2. EPUB format: From c23de543a50bf09834a21e7606c09e72abc066b8 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 13:23:18 -0700 Subject: [PATCH 12/64] Made a few improvements to the document deploy script. --- build/deploy | 45 +++++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/build/deploy b/build/deploy index 8792bdb..8c1bbe4 100755 --- a/build/deploy +++ b/build/deploy @@ -11,6 +11,7 @@ panic() exit 1 } +# Print usage information and exit. usage() { echo "bad usage: $@" @@ -67,8 +68,12 @@ force=0 prepare_only=0 verbose=1 -while getopts b:i:r:t:z:fn opt; do +while getopts b:i:r:t:z:fnvq opt; do case $opt in + v) + verbose=$((verbose + 1));; + q) + verbose=$((verbose - 1));; b) branch="$OPTARG";; t) @@ -106,10 +111,12 @@ if [ -z "$DEPLOY_KEY" ]; then usage "DEPLOY_KEY environment variable not set" fi -echo "temporary directory $tmp_dir" -echo "input directory $in_dir" -echo "repository name $repo_name" -echo "github ref $github_ref" +if [ "$verbose" -ge 0 ]; then + echo "temporary directory $tmp_dir" + echo "input directory $in_dir" + echo "repository name $repo_name" + echo "GitHub ref $github_ref" +fi ################################################################################ # Perform some basic initialization. @@ -121,7 +128,9 @@ source_dir="$cmd_dir/.." version="$(awk -v FS="/" '{print $3;}' <<< "$github_ref")" || \ panic "cannot determine document version" -echo "version $version" +if [ "$verbose" -ge 0 ]; then + echo "version $version" +fi tmp_dir="$tmp_dir/deploy" @@ -131,7 +140,9 @@ private_key_file="$ssh_dir/private_key" version_dir="$git_dir/$version" repo_url="ssh://git@github.com/$repo_name.git" -echo "repository URL: $repo_url" +if [ "$verbose" -ge 0 ]; then + echo "repository URL: $repo_url" +fi ################################################################################ # Setup SSH client configuration. @@ -185,8 +196,10 @@ fi git -C "$git_dir" checkout "$branch" || \ panic "cannot checkout branch $branch" -git -C "$git_dir" config --local user.name "Michael Adams" -git -C "$git_dir" config --local user.email "mdadams@ece.uvic.ca" +git -C "$git_dir" config --local user.name "Michael Adams" || \ + panic "cannot set Git user name" +git -C "$git_dir" config --local user.email "mdadams@ece.uvic.ca" || \ + panic "cannot set Git user email" if [ -e "$version_dir" ]; then panic "directory already exist for $version" @@ -202,14 +215,8 @@ if [ -h "$target" -o -e "$target" ]; then fi ln -s "$version/html" "$target" || \ panic "ln failed" -#target="$git_dir/index.html" -#if [ -h "$target" -o -e "$target" ]; then -# rm -f "$target" || panic "rm failed" -#fi -#ln -s "latest/html" "$target" || \ -# panic "ln failed" - -if [ "$verbose" -ne 0 ]; then + +if [ "$verbose" -ge 1 ]; then ls -al "$git_dir"/* fi @@ -218,7 +225,9 @@ git -C "$git_dir" add . || \ git -C "$git_dir" commit -m "Deploying release $version" || \ panic "git commit failed" if [ "$prepare_only" -eq 0 ]; then - echo "Pushing changes." + if [ "$verbose" -ge 0 ]; then + echo "Pushing changes." + fi git -C "$git_dir" push || \ panic "git push failed" fi From 4c8355c65ba60b6dc41cd450d221636347cc8e20 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 13:33:01 -0700 Subject: [PATCH 13/64] Added the creation of a top-level index.html file for the GitHub Pages site. --- build/deploy | 6 ++++++ build/index.html | 6 ++++++ 2 files changed, 12 insertions(+) create mode 100644 build/index.html diff --git a/build/deploy b/build/deploy index 8c1bbe4..1fbe36a 100755 --- a/build/deploy +++ b/build/deploy @@ -216,6 +216,12 @@ fi ln -s "$version/html" "$target" || \ panic "ln failed" +target="$git_dir/index.html" +if [ -e "$target" ]; then + rm -f "$target" || panic "cannot remove $target" +fi +cp "$cmd_dir/index.html" "$target" || panic "cannot copy $target" + if [ "$verbose" -ge 1 ]; then ls -al "$git_dir"/* fi diff --git a/build/index.html b/build/index.html new file mode 100644 index 0000000..604b236 --- /dev/null +++ b/build/index.html @@ -0,0 +1,6 @@ + + + + +

If you are not redirected in five seconds, click here.

+ From 54396ce597ff630ecbbda703a412badaa33800cd Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 13:47:12 -0700 Subject: [PATCH 14/64] Added the deployment of built document to the same repository. --- .github/workflows/release.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index abb6a6f..53bfe90 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -24,3 +24,8 @@ jobs: DEPLOY_KEY: ${{secrets.DEPLOY_KEY}} shell: bash run: build/deploy -t ${{runner.temp}}/deploy_tmp -r mdadams/sg20_guidelines_for_teaching_cpp -i ${{runner.temp}}/output -z ${{github.ref}} + - name: Deploy internal + env: + DEPLOY_KEY: ${{secrets.ALT_DEPLOY_KEY}} + shell: bash + run: build/deploy -t ${{runner.temp}}/deploy_tmp_2 -r mdadams/SG20 -i ${{runner.temp}}/output -z ${{github.ref}} From 6dd41af56e8ccbcd5053c697965c003f2e42776b Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 13:50:06 -0700 Subject: [PATCH 15/64] Corrected some typos in a workflow file. --- .github/workflows/release.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 53bfe90..956e60b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -23,9 +23,9 @@ jobs: env: DEPLOY_KEY: ${{secrets.DEPLOY_KEY}} shell: bash - run: build/deploy -t ${{runner.temp}}/deploy_tmp -r mdadams/sg20_guidelines_for_teaching_cpp -i ${{runner.temp}}/output -z ${{github.ref}} + run: build/deploy -f -t ${{runner.temp}}/deploy_tmp -r mdadams/sg20_guidelines_for_teaching_cpp -i ${{runner.temp}}/output -z ${{github.ref}} - name: Deploy internal env: DEPLOY_KEY: ${{secrets.ALT_DEPLOY_KEY}} shell: bash - run: build/deploy -t ${{runner.temp}}/deploy_tmp_2 -r mdadams/SG20 -i ${{runner.temp}}/output -z ${{github.ref}} + run: build/deploy -f -t ${{runner.temp}}/deploy_tmp_2 -r mdadams/SG20 -i ${{runner.temp}}/output -z ${{github.ref}} From a555d9b47f8ac3fe610155e0f34472f38b23b320 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 14:03:06 -0700 Subject: [PATCH 16/64] Fixed a bug in the deploy script associated with the handling of the case that the gh-pages branch does not yet exist. --- build/deploy | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/build/deploy b/build/deploy index 1fbe36a..70793f4 100755 --- a/build/deploy +++ b/build/deploy @@ -191,11 +191,11 @@ fi if [ "$status" -eq 2 ]; then git -C "$git_dir" checkout --orphan "$branch" || \ panic "cannot create orphan branch $branch" +else + git -C "$git_dir" checkout "$branch" || \ + panic "cannot checkout branch $branch" fi -git -C "$git_dir" checkout "$branch" || \ - panic "cannot checkout branch $branch" - git -C "$git_dir" config --local user.name "Michael Adams" || \ panic "cannot set Git user name" git -C "$git_dir" config --local user.email "mdadams@ece.uvic.ca" || \ From 30fef190bf0cfd69ff7633a65e7b027a979af703 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 14:13:58 -0700 Subject: [PATCH 17/64] Fix a bug in the deploy script. --- build/deploy | 2 ++ 1 file changed, 2 insertions(+) diff --git a/build/deploy b/build/deploy index 70793f4..c116664 100755 --- a/build/deploy +++ b/build/deploy @@ -191,6 +191,8 @@ fi if [ "$status" -eq 2 ]; then git -C "$git_dir" checkout --orphan "$branch" || \ panic "cannot create orphan branch $branch" + git -C "$git_dir" branch --set-upstream-to "origin/$branch" || \ + panic "cannot set upstream branch" else git -C "$git_dir" checkout "$branch" || \ panic "cannot checkout branch $branch" From 2862aecdcca30212804e2e310c247f12628badfb Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 14:18:43 -0700 Subject: [PATCH 18/64] Fix bug in deploy script. --- build/deploy | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/build/deploy b/build/deploy index c116664..1899917 100755 --- a/build/deploy +++ b/build/deploy @@ -177,6 +177,8 @@ ssh-add "$private_key_file" || \ # Add new release to GitHub pages repository. ################################################################################ +git_push_options=() + git clone "$repo_url" "$git_dir" || \ panic "clone failed" @@ -191,8 +193,7 @@ fi if [ "$status" -eq 2 ]; then git -C "$git_dir" checkout --orphan "$branch" || \ panic "cannot create orphan branch $branch" - git -C "$git_dir" branch --set-upstream-to "origin/$branch" || \ - panic "cannot set upstream branch" + git_push_options+=(-u origin) else git -C "$git_dir" checkout "$branch" || \ panic "cannot checkout branch $branch" @@ -236,6 +237,6 @@ if [ "$prepare_only" -eq 0 ]; then if [ "$verbose" -ge 0 ]; then echo "Pushing changes." fi - git -C "$git_dir" push || \ + git -C "$git_dir" push "${git_push_options[@]}" || \ panic "git push failed" fi From 939e6b216e37ac67e09fb11b5bde9070589a1694 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 14:24:08 -0700 Subject: [PATCH 19/64] Testing. --- build/deploy | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/build/deploy b/build/deploy index 1899917..665bc4c 100755 --- a/build/deploy +++ b/build/deploy @@ -122,6 +122,11 @@ fi # Perform some basic initialization. ################################################################################ +verbose=10 +if [ "$verbose" -ge 10 ]; then + set -xv +fi + cmd_dir=$(dirname "$0") || \ panic "cannot determine directory" source_dir="$cmd_dir/.." From 1d973032df9c9e31f97a76490779d5636806943c Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 14:29:03 -0700 Subject: [PATCH 20/64] Testing. --- build/deploy | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/build/deploy b/build/deploy index 665bc4c..a861094 100755 --- a/build/deploy +++ b/build/deploy @@ -182,8 +182,6 @@ ssh-add "$private_key_file" || \ # Add new release to GitHub pages repository. ################################################################################ -git_push_options=() - git clone "$repo_url" "$git_dir" || \ panic "clone failed" @@ -198,7 +196,8 @@ fi if [ "$status" -eq 2 ]; then git -C "$git_dir" checkout --orphan "$branch" || \ panic "cannot create orphan branch $branch" - git_push_options+=(-u origin) + git -C "$git_dir" push -u origin "$branch" || \ + panic "cannot push new branch $branch" else git -C "$git_dir" checkout "$branch" || \ panic "cannot checkout branch $branch" @@ -242,6 +241,6 @@ if [ "$prepare_only" -eq 0 ]; then if [ "$verbose" -ge 0 ]; then echo "Pushing changes." fi - git -C "$git_dir" push "${git_push_options[@]}" || \ + git -C "$git_dir" push || \ panic "git push failed" fi From 766f13c57d8877375732e0ab1463fac30a3fdbfd Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 14:43:37 -0700 Subject: [PATCH 21/64] Testing. --- build/deploy | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/build/deploy b/build/deploy index a861094..9e8c047 100755 --- a/build/deploy +++ b/build/deploy @@ -182,6 +182,8 @@ ssh-add "$private_key_file" || \ # Add new release to GitHub pages repository. ################################################################################ +git_push_options=() + git clone "$repo_url" "$git_dir" || \ panic "clone failed" @@ -196,8 +198,11 @@ fi if [ "$status" -eq 2 ]; then git -C "$git_dir" checkout --orphan "$branch" || \ panic "cannot create orphan branch $branch" - git -C "$git_dir" push -u origin "$branch" || \ - panic "cannot push new branch $branch" +# git -C "$git_dir" commit --allow-empty -m "Root commit" || \ +# panic "commit failed" +# git -C "$git_dir" push -u origin "$branch" || \ +# panic "cannot push new branch $branch" + git_push_options=(-u origin "$branch") else git -C "$git_dir" checkout "$branch" || \ panic "cannot checkout branch $branch" @@ -241,6 +246,6 @@ if [ "$prepare_only" -eq 0 ]; then if [ "$verbose" -ge 0 ]; then echo "Pushing changes." fi - git -C "$git_dir" push || \ + git -C "$git_dir" push "${git_push_options[@]}" || \ panic "git push failed" fi From d207f32a5304e581d5ac83f19b7ce91ebf122e57 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 14:55:05 -0700 Subject: [PATCH 22/64] Testing. --- build/deploy | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/build/deploy b/build/deploy index 9e8c047..acc1718 100755 --- a/build/deploy +++ b/build/deploy @@ -48,8 +48,8 @@ usage() Examples ======== - export DEPLOY_KEY=.... # private SSH key - $0 -n -f -r mdadams/sg20_guidelines_for_teaching_cpp -b gh-pages \\ + export DEPLOY_KEY=.... # set DEPLOY_KEY to private SSH key + $0 -n -f -r mdadams/sg20 -b gh-pages \\ -t /tmp/sg20_test/tmp -i /tmp/sg20_test/install -z refs/tags/v1.0.0 EOF exit 2 @@ -111,7 +111,7 @@ if [ -z "$DEPLOY_KEY" ]; then usage "DEPLOY_KEY environment variable not set" fi -if [ "$verbose" -ge 0 ]; then +if [ "$verbose" -ge 1 ]; then echo "temporary directory $tmp_dir" echo "input directory $in_dir" echo "repository name $repo_name" @@ -122,8 +122,7 @@ fi # Perform some basic initialization. ################################################################################ -verbose=10 -if [ "$verbose" -ge 10 ]; then +if [ "$verbose" -ge 3 ]; then set -xv fi @@ -133,7 +132,7 @@ source_dir="$cmd_dir/.." version="$(awk -v FS="/" '{print $3;}' <<< "$github_ref")" || \ panic "cannot determine document version" -if [ "$verbose" -ge 0 ]; then +if [ "$verbose" -ge 1 ]; then echo "version $version" fi @@ -145,7 +144,7 @@ private_key_file="$ssh_dir/private_key" version_dir="$git_dir/$version" repo_url="ssh://git@github.com/$repo_name.git" -if [ "$verbose" -ge 0 ]; then +if [ "$verbose" -ge 1 ]; then echo "repository URL: $repo_url" fi @@ -182,10 +181,11 @@ ssh-add "$private_key_file" || \ # Add new release to GitHub pages repository. ################################################################################ -git_push_options=() +git_push_extra_args=() +# Clone the repository. git clone "$repo_url" "$git_dir" || \ - panic "clone failed" + panic "cannot clone repository $repo_url" # Create an orphaned branch for the web site content if the branch does # not already exist. @@ -198,21 +198,19 @@ fi if [ "$status" -eq 2 ]; then git -C "$git_dir" checkout --orphan "$branch" || \ panic "cannot create orphan branch $branch" -# git -C "$git_dir" commit --allow-empty -m "Root commit" || \ -# panic "commit failed" -# git -C "$git_dir" push -u origin "$branch" || \ -# panic "cannot push new branch $branch" - git_push_options=(-u origin "$branch") + git_push_extra_args=(-u origin "$branch") else git -C "$git_dir" checkout "$branch" || \ panic "cannot checkout branch $branch" fi +# Set the Git user. git -C "$git_dir" config --local user.name "Michael Adams" || \ panic "cannot set Git user name" git -C "$git_dir" config --local user.email "mdadams@ece.uvic.ca" || \ panic "cannot set Git user email" +# Add the content for the new release. if [ -e "$version_dir" ]; then panic "directory already exist for $version" fi @@ -221,6 +219,7 @@ mkdir -p "$version_dir" || \ (cd "$in_dir" && tar -cf - .) | (cd "$version_dir" && tar -xf -) || \ panic "tar failed" +# Update the symlink for the latest release. target="$git_dir/latest" if [ -h "$target" -o -e "$target" ]; then rm -f "$target" || panic "rm failed" @@ -228,24 +227,26 @@ fi ln -s "$version/html" "$target" || \ panic "ln failed" +# Add a top-level index.html file to redirect to the latest release. target="$git_dir/index.html" if [ -e "$target" ]; then rm -f "$target" || panic "cannot remove $target" fi cp "$cmd_dir/index.html" "$target" || panic "cannot copy $target" -if [ "$verbose" -ge 1 ]; then +if [ "$verbose" -ge 2 ]; then ls -al "$git_dir"/* fi +# Commit and push all of the changes. git -C "$git_dir" add . || \ panic "git add failed" git -C "$git_dir" commit -m "Deploying release $version" || \ panic "git commit failed" if [ "$prepare_only" -eq 0 ]; then - if [ "$verbose" -ge 0 ]; then + if [ "$verbose" -ge 1 ]; then echo "Pushing changes." fi - git -C "$git_dir" push "${git_push_options[@]}" || \ + git -C "$git_dir" push "${git_push_extra_args[@]}" || \ panic "git push failed" fi From 0eb6385197a070f5815671ee5cf3afd2a61e99b8 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 15:23:08 -0700 Subject: [PATCH 23/64] Made changes to file layout. --- .github/workflows/ci.yml | 4 ++-- .github/workflows/release.yml | 8 ++++---- Makefile | 18 ++++++++++++------ {bin => tools/build}/aspell_frontend | 2 +- {build => tools/build}/build | 2 +- {build => tools/build}/deploy | 2 +- {build => tools/build}/index.html | 0 {bin => tools/build}/make_markdown | 0 {build => tools/build}/prebuild | 0 {bin => tools/build}/preprocessor | 0 .../pandoc_filters}/meta_vars.lua | 0 .../pandoc_filters}/spellcheck.lua | 0 12 files changed, 21 insertions(+), 15 deletions(-) rename {bin => tools/build}/aspell_frontend (88%) rename {build => tools/build}/build (98%) rename {build => tools/build}/deploy (99%) rename {build => tools/build}/index.html (100%) rename {bin => tools/build}/make_markdown (100%) rename {build => tools/build}/prebuild (100%) rename {bin => tools/build}/preprocessor (100%) rename {filters => tools/pandoc_filters}/meta_vars.lua (100%) rename {filters => tools/pandoc_filters}/spellcheck.lua (100%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index af6a6ad..ac08914 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,7 +12,7 @@ jobs: - uses: actions/checkout@v2 - name: Prebuild shell: bash - run: build/prebuild + run: tools/build/prebuild - name: Build shell: bash - run: build/build -d ${{runner.temp}}/output -z ${{github.ref}} -s + run: tools/build/build -d ${{runner.temp}}/output -z ${{github.ref}} -s diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 956e60b..66a307c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -15,17 +15,17 @@ jobs: - uses: actions/checkout@v2 - name: Prebuild shell: bash - run: build/prebuild + run: tools/build/prebuild - name: Build shell: bash - run: build/build -d ${{runner.temp}}/output -z ${{github.ref}} + run: tools/build/build -d ${{runner.temp}}/output -z ${{github.ref}} - name: Deploy env: DEPLOY_KEY: ${{secrets.DEPLOY_KEY}} shell: bash - run: build/deploy -f -t ${{runner.temp}}/deploy_tmp -r mdadams/sg20_guidelines_for_teaching_cpp -i ${{runner.temp}}/output -z ${{github.ref}} + run: tools/build/deploy -f -t ${{runner.temp}}/deploy_tmp -r mdadams/sg20_guidelines_for_teaching_cpp -i ${{runner.temp}}/output -z ${{github.ref}} - name: Deploy internal env: DEPLOY_KEY: ${{secrets.ALT_DEPLOY_KEY}} shell: bash - run: build/deploy -f -t ${{runner.temp}}/deploy_tmp_2 -r mdadams/SG20 -i ${{runner.temp}}/output -z ${{github.ref}} + run: tools/build/deploy -f -t ${{runner.temp}}/deploy_tmp_2 -r mdadams/SG20 -i ${{runner.temp}}/output -z ${{github.ref}} diff --git a/Makefile b/Makefile index baa4e09..2497ba9 100644 --- a/Makefile +++ b/Makefile @@ -76,19 +76,25 @@ install: all done cp -f images/cpp_logo.png $(INSTALL_DIR)/html/images cp -f guidelines.html $(INSTALL_DIR)/html/index.html - ln -s -f html/index.html $(INSTALL_DIR) cp -r -f guidelines_html $(INSTALL_DIR)/html_split cp -f guidelines.epub $(INSTALL_DIR) ################################################################################ -# Preprocessing setup. +# Some additional configuration. ################################################################################ -knowledge_areas_summary.md: $(SOURCES) doc/knowledge_areas.dat - bin/make_markdown < doc/knowledge_areas.dat > knowledge_areas_summary.md +MD_PREPROCESSOR = tools/build/preprocessor +MAKE_MARKDOWN = tools/build/make_markdown + +################################################################################ +# Preprocessing setup. +################################################################################ main.gen.md: $(SOURCES) doc/main.md - bin/preprocessor -v $(DOC_VERSION) < doc/main.md > main.gen.md + $(MD_PREPROCESSOR) -v $(DOC_VERSION) < doc/main.md > main.gen.md + +knowledge_areas_summary.md: $(SOURCES) doc/knowledge_areas.dat + $(MAKE_MARKDOWN) < doc/knowledge_areas.dat > knowledge_areas_summary.md ################################################################################ # Establish Pandoc settings. @@ -142,7 +148,7 @@ spellcheck_result.txt: guidelines.html rm -f $@ rm -f spellcheck/spellcheck_expected_sorted.txt sort spellcheck/spellcheck_expected.txt | uniq > spellcheck/spellcheck_expected_sorted.txt - PATH="bin:$$PATH" pandoc --from $(INPUT_FORMAT) --lua-filter filters/spellcheck.lua main.gen.md | sort | uniq > $@ + PATH="tools/build:$$PATH" pandoc --from $(INPUT_FORMAT) --lua-filter tools/pandoc_filters/spellcheck.lua main.gen.md | sort | uniq > $@ @status=0; \ diff -q spellcheck/spellcheck_expected_sorted.txt $@ || status=1; \ if [ $$status -ne 0 ]; then \ diff --git a/bin/aspell_frontend b/tools/build/aspell_frontend similarity index 88% rename from bin/aspell_frontend rename to tools/build/aspell_frontend index e49dd69..f119e49 100755 --- a/bin/aspell_frontend +++ b/tools/build/aspell_frontend @@ -6,7 +6,7 @@ cmd_dir="$(dirname "$0")" || exit 1 # Get an absolute pathname. #cmd_dir=$(realpath "$cmd_dir") || exit 1 -spellcheck_dir="$cmd_dir/../spellcheck" +spellcheck_dir="$cmd_dir/../../spellcheck" wordlist="wordlist" if [ ! -f "$spellcheck_dir/$wordlist" ]; then echo "ERROR" diff --git a/build/build b/tools/build/build similarity index 98% rename from build/build rename to tools/build/build index 7f31301..1c4363b 100755 --- a/build/build +++ b/tools/build/build @@ -46,7 +46,7 @@ usage() ################################################################################ cmd_dir=$(dirname "$0") || panic "cannot determine directory name" -source_dir="$cmd_dir/.." +source_dir="$cmd_dir/../.." ################################################################################ # Parse command line. diff --git a/build/deploy b/tools/build/deploy similarity index 99% rename from build/deploy rename to tools/build/deploy index acc1718..cc87aa3 100755 --- a/build/deploy +++ b/tools/build/deploy @@ -128,7 +128,7 @@ fi cmd_dir=$(dirname "$0") || \ panic "cannot determine directory" -source_dir="$cmd_dir/.." +source_dir="$cmd_dir/../.." version="$(awk -v FS="/" '{print $3;}' <<< "$github_ref")" || \ panic "cannot determine document version" diff --git a/build/index.html b/tools/build/index.html similarity index 100% rename from build/index.html rename to tools/build/index.html diff --git a/bin/make_markdown b/tools/build/make_markdown similarity index 100% rename from bin/make_markdown rename to tools/build/make_markdown diff --git a/build/prebuild b/tools/build/prebuild similarity index 100% rename from build/prebuild rename to tools/build/prebuild diff --git a/bin/preprocessor b/tools/build/preprocessor similarity index 100% rename from bin/preprocessor rename to tools/build/preprocessor diff --git a/filters/meta_vars.lua b/tools/pandoc_filters/meta_vars.lua similarity index 100% rename from filters/meta_vars.lua rename to tools/pandoc_filters/meta_vars.lua diff --git a/filters/spellcheck.lua b/tools/pandoc_filters/spellcheck.lua similarity index 100% rename from filters/spellcheck.lua rename to tools/pandoc_filters/spellcheck.lua From 95587e4b63d1c4fd97bae23870c0675cf53f3c74 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 16:33:56 -0700 Subject: [PATCH 24/64] More reorganizing. --- Makefile | 167 +---------------- .../pandoc_templates}/bootstrap_menu.html | 0 .../pandoc_templates}/clean_menu.html | 0 .../pandoc_templates}/easy_template.html | 0 .../elegant_bootstrap_menu.html | 0 .../pandoc_templates}/uikit.html | 0 .../spellcheck}/spellcheck_expected.txt | 0 .../spellcheck/spellcheck_expected_sorted.txt | 36 ++++ {spellcheck => config/spellcheck}/wordlist | 0 sources/Makefile | 172 ++++++++++++++++++ {doc => sources}/contributing.md | 0 {doc => sources}/course_examples.md | 0 {css => sources/css}/default-pandoc.css | 0 {css => sources/css}/elegant_bootstrap.css | 0 {css => sources/css}/epub.css | 0 {css => sources/css}/github-pandoc.css | 0 {doc => sources}/disclaimer.md | 0 {doc => sources}/glossary.md | 0 {images => sources/images}/cpp_logo.png | Bin {tools/build => sources}/index.html | 0 {doc => sources}/introduction.md | 0 {doc => sources}/knowledge_areas.dat | 0 {doc => sources}/main.md | 26 +-- .../requires-expressions.md | 0 .../functions/defaulted-parameters.md | 0 .../functions/user-defined-literals.md | 0 .../meta-error-handling/static_assert.md | 0 .../modules}/object-model/copy-semantics.md | 0 .../modules}/object-model/copy_elision.md | 0 {doc => sources}/obtaining_document.md | 0 {doc => sources}/references.md | 0 tools/build/aspell_frontend | 3 +- tools/build/deploy | 4 +- tools/build/preprocessor | 8 + 34 files changed, 239 insertions(+), 177 deletions(-) rename {templates => config/pandoc_templates}/bootstrap_menu.html (100%) rename {templates => config/pandoc_templates}/clean_menu.html (100%) rename {templates => config/pandoc_templates}/easy_template.html (100%) rename {templates => config/pandoc_templates}/elegant_bootstrap_menu.html (100%) rename {templates => config/pandoc_templates}/uikit.html (100%) rename {spellcheck => config/spellcheck}/spellcheck_expected.txt (100%) create mode 100644 config/spellcheck/spellcheck_expected_sorted.txt rename {spellcheck => config/spellcheck}/wordlist (100%) create mode 100644 sources/Makefile rename {doc => sources}/contributing.md (100%) rename {doc => sources}/course_examples.md (100%) rename {css => sources/css}/default-pandoc.css (100%) rename {css => sources/css}/elegant_bootstrap.css (100%) rename {css => sources/css}/epub.css (100%) rename {css => sources/css}/github-pandoc.css (100%) rename {doc => sources}/disclaimer.md (100%) rename {doc => sources}/glossary.md (100%) rename {images => sources/images}/cpp_logo.png (100%) rename {tools/build => sources}/index.html (100%) rename {doc => sources}/introduction.md (100%) rename {doc => sources}/knowledge_areas.dat (100%) rename {doc => sources}/main.md (74%) rename {doc/areas => sources/modules}/compile-time-programming/requires-expressions.md (100%) rename {doc/areas => sources/modules}/functions/defaulted-parameters.md (100%) rename {doc/areas => sources/modules}/functions/user-defined-literals.md (100%) rename {doc/areas => sources/modules}/meta-error-handling/static_assert.md (100%) rename {doc/areas => sources/modules}/object-model/copy-semantics.md (100%) rename {doc/areas => sources/modules}/object-model/copy_elision.md (100%) rename {doc => sources}/obtaining_document.md (100%) rename {doc => sources}/references.md (100%) diff --git a/Makefile b/Makefile index 2497ba9..fbf8ad0 100644 --- a/Makefile +++ b/Makefile @@ -1,163 +1,8 @@ -# Specify the document version. -# This can be overridden when invoked from the automated build process. -DOC_VERSION = X.Y.Z +SUBDIRS = \ + sources \ -# Specify whether a spelling error is an error (as opposed to a warning). -# This can be overridden when invoked from the automated build process. -# DOC_SPELLCHECK_MUST_PASS = 0 -DOC_SPELLCHECK_MUST_PASS = 1 - -# This can be overridden when invoked from the automated build process. -INSTALL_DIR = install - -# All of the Markdown source files (that are not generated during build). -SOURCES = \ - doc/areas/compile-time-programming/requires-expressions.md \ - doc/areas/functions/defaulted-parameters.md \ - doc/areas/functions/user-defined-literals.md \ - doc/areas/object-model/copy_elision.md \ - doc/areas/object-model/copy-semantics.md \ - doc/course_examples.md \ - doc/disclaimer.md \ - doc/glossary.md \ - doc/contributing.md \ - doc/introduction.md \ - doc/main.md \ - doc/obtaining_document.md \ - doc/references.md \ - -# The Markdown files that are generated during the build process. -GENERATED_MARKDOWN = \ - knowledge_areas_summary.md \ - main.gen.md \ - -################################################################################ -# Define primary targets. -################################################################################ - -# The all target builds the document in a minimal set of formats and -# performs a spell check. -.PHONY: all -all: documents spellcheck - -# The documents target builds the document in a minimal set of formats. -.PHONY: documents -documents: guidelines.html guidelines_html guidelines.epub - -# The world target builds the document in a few extra formats. -.PHONY: world -world: documents guidelines.pdf - -# The spellcheck format performs a spell check on the document. -.PHONY: spellcheck -spellcheck: spellcheck_result.txt - -# The clean target removes all files generated during the build process. -.PHONY: clean -clean: - rm -f guidelines.html guidelines.pdf guidelines.epub guidelines.tex - rm -rf guidelines.texi - rm -f main.gen.md knowledge_areas_summary.md - rm -f pandoc.css - rm -f missfont.log - rm -rf guidelines_html - rm -f spellcheck_result.txt - rm -f spellcheck/spellcheck_expected_sorted.txt - -# The install target installs the build document (in various formats) -# in the directory $(INSTALL_DIR). -.PHONY: install -install: all - if [ ! -d $(INSTALL_DIR) ]; then mkdir -p $(INSTALL_DIR) || exit 1; fi - for dir in html html/images; do \ - if [ ! -d "$(INSTALL_DIR)/$$dir" ]; then \ - mkdir -p "$(INSTALL_DIR)/$$dir" || exit 1; \ - fi; \ +.PHONY: all clean install +all clean install: + for subdir in $(SUBDIRS); do \ + ( cd $$subdir && make -$(MAKEFLAGS) $@ ) || exit 1; \ done - cp -f images/cpp_logo.png $(INSTALL_DIR)/html/images - cp -f guidelines.html $(INSTALL_DIR)/html/index.html - cp -r -f guidelines_html $(INSTALL_DIR)/html_split - cp -f guidelines.epub $(INSTALL_DIR) - -################################################################################ -# Some additional configuration. -################################################################################ - -MD_PREPROCESSOR = tools/build/preprocessor -MAKE_MARKDOWN = tools/build/make_markdown - -################################################################################ -# Preprocessing setup. -################################################################################ - -main.gen.md: $(SOURCES) doc/main.md - $(MD_PREPROCESSOR) -v $(DOC_VERSION) < doc/main.md > main.gen.md - -knowledge_areas_summary.md: $(SOURCES) doc/knowledge_areas.dat - $(MAKE_MARKDOWN) < doc/knowledge_areas.dat > knowledge_areas_summary.md - -################################################################################ -# Establish Pandoc settings. -################################################################################ - -PANDOC_OPTIONS += --toc --toc-depth 3 -PANDOC_OPTIONS += --number-sections -PANDOC_OPTIONS += --standalone -PANDOC_OPTIONS += --pdf-engine=xelatex -#PANDOC_OPTIONS += --lua-filter=filters/meta_vars.lua -#PANDOC_OPTIONS += --metadata date="`date +%Y-%m-%d`" -PANDOC_OPTIONS += --metadata version=$(DOC_VERSION) - -INPUT_FORMAT = markdown+header_attributes+multiline_tables - -EPUB_CSS_FILE = css/default-pandoc.css - -#HTML_TEMPLATE = templates/bootstrap_menu.html -HTML_TEMPLATE = templates/uikit.html - -################################################################################ -# Rules for generating the document in various formats. -################################################################################ - -guidelines.html: $(GENERATED_MARKDOWN) - pandoc $(PANDOC_OPTIONS) --template $(HTML_TEMPLATE) --from $(INPUT_FORMAT) -o $@ main.gen.md - -guidelines.epub: $(GENERATED_MARKDOWN) - pandoc $(PANDOC_OPTIONS) -c $(EPUB_CSS_FILE) --from $(INPUT_FORMAT) -o $@ main.gen.md - -guidelines.pdf: $(GENERATED_MARKDOWN) - pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) -o $@ main.gen.md - -guidelines.texi: $(GENERATED_MARKDOWN) - pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) -o $@ main.gen.md - -guidelines.docbook: $(GENERATED_MARKDOWN) - pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) -o $@ main.gen.md - -guidelines_html: guidelines.texi - makeinfo --no-validate --force --html -o guidelines_html guidelines.texi - -guidelines.tex: - pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) --to latex -o $@ main.gen.md - -################################################################################ -# Rule for spellchecking. -################################################################################ - -spellcheck_result.txt: guidelines.html - rm -f $@ - rm -f spellcheck/spellcheck_expected_sorted.txt - sort spellcheck/spellcheck_expected.txt | uniq > spellcheck/spellcheck_expected_sorted.txt - PATH="tools/build:$$PATH" pandoc --from $(INPUT_FORMAT) --lua-filter tools/pandoc_filters/spellcheck.lua main.gen.md | sort | uniq > $@ - @status=0; \ - diff -q spellcheck/spellcheck_expected_sorted.txt $@ || status=1; \ - if [ $$status -ne 0 ]; then \ - echo "SPELLING ERRORS DETECTED:"; \ - diff -u spellcheck/spellcheck_expected_sorted.txt $@ | grep '^[+-]'; \ - if [ $(DOC_SPELLCHECK_MUST_PASS) -ne 0 ]; then \ - echo "ERROR: spelling errors detected"; \ - exit 1; \ - else \ - echo "WARNING: spelling errors detected"; \ - fi; \ - fi diff --git a/templates/bootstrap_menu.html b/config/pandoc_templates/bootstrap_menu.html similarity index 100% rename from templates/bootstrap_menu.html rename to config/pandoc_templates/bootstrap_menu.html diff --git a/templates/clean_menu.html b/config/pandoc_templates/clean_menu.html similarity index 100% rename from templates/clean_menu.html rename to config/pandoc_templates/clean_menu.html diff --git a/templates/easy_template.html b/config/pandoc_templates/easy_template.html similarity index 100% rename from templates/easy_template.html rename to config/pandoc_templates/easy_template.html diff --git a/templates/elegant_bootstrap_menu.html b/config/pandoc_templates/elegant_bootstrap_menu.html similarity index 100% rename from templates/elegant_bootstrap_menu.html rename to config/pandoc_templates/elegant_bootstrap_menu.html diff --git a/templates/uikit.html b/config/pandoc_templates/uikit.html similarity index 100% rename from templates/uikit.html rename to config/pandoc_templates/uikit.html diff --git a/spellcheck/spellcheck_expected.txt b/config/spellcheck/spellcheck_expected.txt similarity index 100% rename from spellcheck/spellcheck_expected.txt rename to config/spellcheck/spellcheck_expected.txt diff --git a/config/spellcheck/spellcheck_expected_sorted.txt b/config/spellcheck/spellcheck_expected_sorted.txt new file mode 100644 index 0000000..f0d2e61 --- /dev/null +++ b/config/spellcheck/spellcheck_expected_sorted.txt @@ -0,0 +1,36 @@ +args +Bjarne +checkmark +computable +constexpr +cppreference +decltype +Engelhart +EPUB +errno +expr +Florian +fmt +func +Furst +Hinnant +Hyland +IDEs +JC +Krathwohl +ness +noexcept +NRVO +req +RVO +Sattler +SFINAE +SG +Stroustrup +struct +udl +UDL +UDLs +Vandevoorde +ver +Winkel diff --git a/spellcheck/wordlist b/config/spellcheck/wordlist similarity index 100% rename from spellcheck/wordlist rename to config/spellcheck/wordlist diff --git a/sources/Makefile b/sources/Makefile new file mode 100644 index 0000000..53cf6b5 --- /dev/null +++ b/sources/Makefile @@ -0,0 +1,172 @@ +#TOP_DIR = $(realpath ..) +TOP_DIR = .. + +# Specify the document version. +# This can be overridden when invoked from the automated build process. +DOC_VERSION = X.Y.Z + +# Specify whether a spelling error is an error (as opposed to a warning). +# This can be overridden when invoked from the automated build process. +# Please resist the temptation to set this variable to zero. ;-) +# DOC_SPELLCHECK_MUST_PASS = 0 +DOC_SPELLCHECK_MUST_PASS = 1 + +# This can be overridden when invoked from the automated build process. +INSTALL_DIR = $(TOP_DIR)/install + +# All of the Markdown source files (that are not generated during build). +SOURCES = \ + modules/compile-time-programming/requires-expressions.md \ + modules/functions/defaulted-parameters.md \ + modules/functions/user-defined-literals.md \ + modules/object-model/copy_elision.md \ + modules/object-model/copy-semantics.md \ + course_examples.md \ + disclaimer.md \ + glossary.md \ + contributing.md \ + introduction.md \ + main.md \ + obtaining_document.md \ + references.md \ + +# The Markdown files that are generated during the build process. +GENERATED_MARKDOWN = \ + knowledge_areas_summary.md \ + main.gen.md \ + +################################################################################ +# Define primary targets. +################################################################################ + +# The all target builds the document in a minimal set of formats and +# performs a spell check. +.PHONY: all +all: documents spellcheck + +# The documents target builds the document in a minimal set of formats. +.PHONY: documents +documents: guidelines.html guidelines_html guidelines.epub + +# The world target builds the document in a few extra formats. +.PHONY: world +world: documents guidelines.pdf + +# The spellcheck format performs a spell check on the document. +.PHONY: spellcheck +spellcheck: spellcheck_result.txt + +# The clean target removes all files generated during the build process. +.PHONY: clean +clean: + rm -f guidelines.html guidelines.pdf guidelines.epub guidelines.tex + rm -rf guidelines.texi + rm -f main.gen.md knowledge_areas_summary.md + rm -f missfont.log + rm -rf guidelines_html + rm -f spellcheck_result.txt + rm -f spellcheck/spellcheck_expected_sorted.txt + +# The install target installs the build document (in various formats) +# in the directory $(INSTALL_DIR). +.PHONY: install +install: all + if [ ! -d $(INSTALL_DIR) ]; then mkdir -p $(INSTALL_DIR) || exit 1; fi + for dir in html html/images; do \ + if [ ! -d "$(INSTALL_DIR)/$$dir" ]; then \ + mkdir -p "$(INSTALL_DIR)/$$dir" || exit 1; \ + fi; \ + done + cp -f images/cpp_logo.png $(INSTALL_DIR)/html/images + cp -f guidelines.html $(INSTALL_DIR)/html/index.html + cp -r -f guidelines_html $(INSTALL_DIR)/html_split + cp -f guidelines.epub $(INSTALL_DIR) + +################################################################################ +# Some additional configuration. +################################################################################ + +MD_PREPROCESSOR = $(TOP_DIR)/tools/build/preprocessor +MAKE_MARKDOWN = $(TOP_DIR)/tools/build/make_markdown +SPELLCHECK_DIR = $(TOP_DIR)/config/spellcheck + +################################################################################ +# Preprocessing setup. +################################################################################ + +main.gen.md: $(SOURCES) main.md + $(MD_PREPROCESSOR) -v $(DOC_VERSION) < main.md > main.gen.md + +knowledge_areas_summary.md: $(SOURCES) knowledge_areas.dat + $(MAKE_MARKDOWN) < knowledge_areas.dat > knowledge_areas_summary.md + +################################################################################ +# Establish Pandoc settings. +################################################################################ + +PANDOC_OPTIONS += --toc --toc-depth 3 +PANDOC_OPTIONS += --number-sections +PANDOC_OPTIONS += --standalone +PANDOC_OPTIONS += --pdf-engine=xelatex +#PANDOC_OPTIONS += --lua-filter=tools/pandoc_filters/meta_vars.lua +#PANDOC_OPTIONS += --metadata date="`date +%Y-%m-%d`" +PANDOC_OPTIONS += --metadata version=$(DOC_VERSION) + +INPUT_FORMAT = markdown+header_attributes+multiline_tables + +EPUB_CSS_FILE = css/default-pandoc.css + +#HTML_TEMPLATE = templates/bootstrap_menu.html +HTML_TEMPLATE = $(TOP_DIR)/config/pandoc_templates/uikit.html + +################################################################################ +# Rules for generating the document in various formats. +################################################################################ + +guidelines.html: $(GENERATED_MARKDOWN) + pandoc $(PANDOC_OPTIONS) --template $(HTML_TEMPLATE) --from $(INPUT_FORMAT) -o $@ main.gen.md + +guidelines.epub: $(GENERATED_MARKDOWN) + pandoc $(PANDOC_OPTIONS) -c $(EPUB_CSS_FILE) --from $(INPUT_FORMAT) -o $@ main.gen.md + +guidelines.pdf: $(GENERATED_MARKDOWN) + pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) -o $@ main.gen.md + +guidelines.texi: $(GENERATED_MARKDOWN) + pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) -o $@ main.gen.md + +guidelines.docbook: $(GENERATED_MARKDOWN) + pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) -o $@ main.gen.md + +guidelines_html: guidelines.texi + makeinfo --no-validate --force --html -o guidelines_html guidelines.texi + +guidelines.tex: + pandoc $(PANDOC_OPTIONS) --from $(INPUT_FORMAT) --to latex -o $@ main.gen.md + +################################################################################ +# Rule for spellchecking. +################################################################################ + +spellcheck_result.txt: guidelines.html + rm -f $@ + rm -f $(SPELLCHECK_DIR)/spellcheck_expected_sorted.txt + sort $(SPELLCHECK_DIR)/spellcheck_expected.txt | \ + uniq > $(SPELLCHECK_DIR)/spellcheck_expected_sorted.txt + PATH="$(TOP_DIR)/tools/build:$$PATH" pandoc --from $(INPUT_FORMAT) \ + --lua-filter $(TOP_DIR)/tools/pandoc_filters/spellcheck.lua \ + main.gen.md | sort | uniq > $@ + @status=0; \ + diff -q $(SPELLCHECK_DIR)/spellcheck_expected_sorted.txt $@ || \ + status=1; \ + if [ $$status -ne 0 ]; then \ + echo "SPELLING ERRORS DETECTED:"; \ + diff -u $(SPELLCHECK_DIR)/spellcheck_expected_sorted.txt $@ | \ + grep '^[+-]'; \ + if [ $(DOC_SPELLCHECK_MUST_PASS) -ne 0 ]; then \ + echo "ERROR: spelling errors detected"; \ + exit 1; \ + else \ + echo "WARNING: spelling errors detected"; \ + fi; \ + fi diff --git a/doc/contributing.md b/sources/contributing.md similarity index 100% rename from doc/contributing.md rename to sources/contributing.md diff --git a/doc/course_examples.md b/sources/course_examples.md similarity index 100% rename from doc/course_examples.md rename to sources/course_examples.md diff --git a/css/default-pandoc.css b/sources/css/default-pandoc.css similarity index 100% rename from css/default-pandoc.css rename to sources/css/default-pandoc.css diff --git a/css/elegant_bootstrap.css b/sources/css/elegant_bootstrap.css similarity index 100% rename from css/elegant_bootstrap.css rename to sources/css/elegant_bootstrap.css diff --git a/css/epub.css b/sources/css/epub.css similarity index 100% rename from css/epub.css rename to sources/css/epub.css diff --git a/css/github-pandoc.css b/sources/css/github-pandoc.css similarity index 100% rename from css/github-pandoc.css rename to sources/css/github-pandoc.css diff --git a/doc/disclaimer.md b/sources/disclaimer.md similarity index 100% rename from doc/disclaimer.md rename to sources/disclaimer.md diff --git a/doc/glossary.md b/sources/glossary.md similarity index 100% rename from doc/glossary.md rename to sources/glossary.md diff --git a/images/cpp_logo.png b/sources/images/cpp_logo.png similarity index 100% rename from images/cpp_logo.png rename to sources/images/cpp_logo.png diff --git a/tools/build/index.html b/sources/index.html similarity index 100% rename from tools/build/index.html rename to sources/index.html diff --git a/doc/introduction.md b/sources/introduction.md similarity index 100% rename from doc/introduction.md rename to sources/introduction.md diff --git a/doc/knowledge_areas.dat b/sources/knowledge_areas.dat similarity index 100% rename from doc/knowledge_areas.dat rename to sources/knowledge_areas.dat diff --git a/doc/main.md b/sources/main.md similarity index 74% rename from doc/main.md rename to sources/main.md index aebb686..f8064a3 100644 --- a/doc/main.md +++ b/sources/main.md @@ -6,11 +6,11 @@ geometry: margin=1in output: pdf_document --- -__INCLUDE__(doc/obtaining_document.md) +__INCLUDE__(obtaining_document.md) -__INCLUDE__(doc/disclaimer.md) +__INCLUDE__(disclaimer.md) -__INCLUDE__(doc/introduction.md) +__INCLUDE__(introduction.md) # Summary of Modules and Topics @@ -42,21 +42,21 @@ __INCLUDE__(knowledge_areas_summary.md) [//]: # ( ********** START OF DETAILED TOPIC DOCUMENTS ********** ) -__INCLUDE__(doc/areas/object-model/copy-semantics.md) +__INCLUDE__(modules/object-model/copy-semantics.md) -__INCLUDE__(doc/areas/functions/user-defined-literals.md) +__INCLUDE__(modules/functions/user-defined-literals.md) -__INCLUDE__(doc/areas/functions/defaulted-parameters.md) +__INCLUDE__(modules/functions/defaulted-parameters.md) -__INCLUDE__(doc/areas/compile-time-programming/requires-expressions.md) +__INCLUDE__(modules/compile-time-programming/requires-expressions.md) -__INCLUDE__(doc/areas/object-model/copy_elision.md) +__INCLUDE__(modules/object-model/copy_elision.md) -__INCLUDE__(doc/areas/meta-error-handling/static_assert.md) +__INCLUDE__(modules/meta-error-handling/static_assert.md) [//]: # ( ********** END OF DETAILED TOPIC DOCUMENTS ********** ) -__INCLUDE__(doc/course_examples.md) +__INCLUDE__(course_examples.md) # License {#license} @@ -70,8 +70,8 @@ __INCLUDE__(LICENSE.txt) For a complete list of contributors, please refer to the repository containing this document on [GitHub](https://github.com/cplusplus/SG20). -__INCLUDE__(doc/contributing.md) +__INCLUDE__(contributing.md) -__INCLUDE__(doc/glossary.md) +__INCLUDE__(glossary.md) -__INCLUDE__(doc/references.md) +__INCLUDE__(references.md) diff --git a/doc/areas/compile-time-programming/requires-expressions.md b/sources/modules/compile-time-programming/requires-expressions.md similarity index 100% rename from doc/areas/compile-time-programming/requires-expressions.md rename to sources/modules/compile-time-programming/requires-expressions.md diff --git a/doc/areas/functions/defaulted-parameters.md b/sources/modules/functions/defaulted-parameters.md similarity index 100% rename from doc/areas/functions/defaulted-parameters.md rename to sources/modules/functions/defaulted-parameters.md diff --git a/doc/areas/functions/user-defined-literals.md b/sources/modules/functions/user-defined-literals.md similarity index 100% rename from doc/areas/functions/user-defined-literals.md rename to sources/modules/functions/user-defined-literals.md diff --git a/doc/areas/meta-error-handling/static_assert.md b/sources/modules/meta-error-handling/static_assert.md similarity index 100% rename from doc/areas/meta-error-handling/static_assert.md rename to sources/modules/meta-error-handling/static_assert.md diff --git a/doc/areas/object-model/copy-semantics.md b/sources/modules/object-model/copy-semantics.md similarity index 100% rename from doc/areas/object-model/copy-semantics.md rename to sources/modules/object-model/copy-semantics.md diff --git a/doc/areas/object-model/copy_elision.md b/sources/modules/object-model/copy_elision.md similarity index 100% rename from doc/areas/object-model/copy_elision.md rename to sources/modules/object-model/copy_elision.md diff --git a/doc/obtaining_document.md b/sources/obtaining_document.md similarity index 100% rename from doc/obtaining_document.md rename to sources/obtaining_document.md diff --git a/doc/references.md b/sources/references.md similarity index 100% rename from doc/references.md rename to sources/references.md diff --git a/tools/build/aspell_frontend b/tools/build/aspell_frontend index f119e49..a949b08 100755 --- a/tools/build/aspell_frontend +++ b/tools/build/aspell_frontend @@ -6,7 +6,8 @@ cmd_dir="$(dirname "$0")" || exit 1 # Get an absolute pathname. #cmd_dir=$(realpath "$cmd_dir") || exit 1 -spellcheck_dir="$cmd_dir/../../spellcheck" +top_dir="$cmd_dir/../.." +spellcheck_dir="$top_dir/config/spellcheck" wordlist="wordlist" if [ ! -f "$spellcheck_dir/$wordlist" ]; then echo "ERROR" diff --git a/tools/build/deploy b/tools/build/deploy index cc87aa3..a60ecc3 100755 --- a/tools/build/deploy +++ b/tools/build/deploy @@ -128,7 +128,7 @@ fi cmd_dir=$(dirname "$0") || \ panic "cannot determine directory" -source_dir="$cmd_dir/../.." +top_dir="$cmd_dir/../.." version="$(awk -v FS="/" '{print $3;}' <<< "$github_ref")" || \ panic "cannot determine document version" @@ -232,7 +232,7 @@ target="$git_dir/index.html" if [ -e "$target" ]; then rm -f "$target" || panic "cannot remove $target" fi -cp "$cmd_dir/index.html" "$target" || panic "cannot copy $target" +cp "$top_dir/sources/index.html" "$target" || panic "cannot copy $target" if [ "$verbose" -ge 2 ]; then ls -al "$git_dir"/* diff --git a/tools/build/preprocessor b/tools/build/preprocessor index b728245..5c3ef26 100755 --- a/tools/build/preprocessor +++ b/tools/build/preprocessor @@ -50,6 +50,7 @@ awk -v program="$program_pathname" -v level="$level" -v version="$version" ' path = substr($0, start, end - start); result = system(sprintf("cat %s | %s -l %d -v %s", path, program, level + 1, version)); if (result) { + printf "error processing %s\n", path > "/dev/stderr"; exit 1; } next; @@ -59,3 +60,10 @@ awk -v program="$program_pathname" -v level="$level" -v version="$version" ' } ' - | \ sed -e 's/__VERSION__/'"$version"'/g' + +status=("${PIPESTATUS[@]}") +for i in "${status[@]}"; do + if [ "$i" -ne 0 ]; then + panic "preprocessor failed" + fi +done From d4f4ae0c62db5b36487227cc9527996ed44c72e8 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 16:35:45 -0700 Subject: [PATCH 25/64] Testing. --- tools/build/preprocessor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/build/preprocessor b/tools/build/preprocessor index 5c3ef26..ee857e3 100755 --- a/tools/build/preprocessor +++ b/tools/build/preprocessor @@ -1,4 +1,4 @@ -#! /usr/bin/env sh +#! /usr/bin/env bash # Michael Adams (mdadams@ece.uvic.ca) program_dir="$(dirname "$0")" || exit 1 From 6ff132e0d868c0d586f815cada176049dbc3117a Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 16:37:02 -0700 Subject: [PATCH 26/64] Testing. --- tools/build/make_markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/build/make_markdown b/tools/build/make_markdown index bbb03fc..e584380 100755 --- a/tools/build/make_markdown +++ b/tools/build/make_markdown @@ -1,4 +1,4 @@ -#! /usr/bin/env sh +#! /usr/bin/env bash # Michael Adams (mdadams@ece.uvic.ca) awk ' From 43ebd548d0a007b89c971ac0dc77b188bed63358 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 16:49:20 -0700 Subject: [PATCH 27/64] Revised README. --- README.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 937988d..a9d0312 100644 --- a/README.md +++ b/README.md @@ -21,13 +21,20 @@ The following software is needed to build the document: To build, simply type: - - make clean - - make all + 1. make clean + 2. make all + 3. make install -This will build the document in multiple formats. -The main two formats are: +(Strictly speaking, step 2 can be skipped, since the install target +has a dependency on the all target.) - - HTML format as a single HTML document: guidelines.html - - EPUB format: guidelines.epub +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 The build process performs spell checking. From 3e0ade757d28d779e4e82c44622a01e69541f2cb Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 20:56:10 -0700 Subject: [PATCH 28/64] Replaced HTML markup for tables with the corresponding Markdown markup in several document source files. --- config/spellcheck/spellcheck_expected.txt | 1 - .../spellcheck/spellcheck_expected_sorted.txt | 36 ------------------- sources/Makefile | 10 +++--- .../requires-expressions.md | 29 ++++++--------- .../modules/functions/defaulted-parameters.md | 28 ++++++--------- .../functions/user-defined-literals.md | 27 +++++--------- .../meta-error-handling/static_assert.md | 28 ++++++--------- .../modules/object-model/copy-semantics.md | 27 +++++--------- 8 files changed, 54 insertions(+), 132 deletions(-) delete mode 100644 config/spellcheck/spellcheck_expected_sorted.txt diff --git a/config/spellcheck/spellcheck_expected.txt b/config/spellcheck/spellcheck_expected.txt index f0641a6..f8f1ff0 100644 --- a/config/spellcheck/spellcheck_expected.txt +++ b/config/spellcheck/spellcheck_expected.txt @@ -10,7 +10,6 @@ EPUB errno expr Florian -fmt func Furst Hyland diff --git a/config/spellcheck/spellcheck_expected_sorted.txt b/config/spellcheck/spellcheck_expected_sorted.txt deleted file mode 100644 index f0d2e61..0000000 --- a/config/spellcheck/spellcheck_expected_sorted.txt +++ /dev/null @@ -1,36 +0,0 @@ -args -Bjarne -checkmark -computable -constexpr -cppreference -decltype -Engelhart -EPUB -errno -expr -Florian -fmt -func -Furst -Hinnant -Hyland -IDEs -JC -Krathwohl -ness -noexcept -NRVO -req -RVO -Sattler -SFINAE -SG -Stroustrup -struct -udl -UDL -UDLs -Vandevoorde -ver -Winkel diff --git a/sources/Makefile b/sources/Makefile index 53cf6b5..6dd046e 100644 --- a/sources/Makefile +++ b/sources/Makefile @@ -65,7 +65,7 @@ clean: rm -f missfont.log rm -rf guidelines_html rm -f spellcheck_result.txt - rm -f spellcheck/spellcheck_expected_sorted.txt + rm -f spellcheck_expected_sorted.txt # The install target installs the build document (in various formats) # in the directory $(INSTALL_DIR). @@ -150,18 +150,18 @@ guidelines.tex: spellcheck_result.txt: guidelines.html rm -f $@ - rm -f $(SPELLCHECK_DIR)/spellcheck_expected_sorted.txt + rm -f spellcheck_expected_sorted.txt sort $(SPELLCHECK_DIR)/spellcheck_expected.txt | \ - uniq > $(SPELLCHECK_DIR)/spellcheck_expected_sorted.txt + uniq > spellcheck_expected_sorted.txt PATH="$(TOP_DIR)/tools/build:$$PATH" pandoc --from $(INPUT_FORMAT) \ --lua-filter $(TOP_DIR)/tools/pandoc_filters/spellcheck.lua \ main.gen.md | sort | uniq > $@ @status=0; \ - diff -q $(SPELLCHECK_DIR)/spellcheck_expected_sorted.txt $@ || \ + diff -q spellcheck_expected_sorted.txt $@ || \ status=1; \ if [ $$status -ne 0 ]; then \ echo "SPELLING ERRORS DETECTED:"; \ - diff -u $(SPELLCHECK_DIR)/spellcheck_expected_sorted.txt $@ | \ + diff -u spellcheck_expected_sorted.txt $@ | \ grep '^[+-]'; \ if [ $(DOC_SPELLCHECK_MUST_PASS) -ne 0 ]; then \ echo "ERROR: spelling errors detected"; \ diff --git a/sources/modules/compile-time-programming/requires-expressions.md b/sources/modules/compile-time-programming/requires-expressions.md index bfa8851..8b72281 100644 --- a/sources/modules/compile-time-programming/requires-expressions.md +++ b/sources/modules/compile-time-programming/requires-expressions.md @@ -2,24 +2,17 @@ ### Overview - - - - - - - - - - - - - - - - - -
LevelObjectives
FoundationalDefine and use requires-expressions to check satisfaction of expressions by given parameters
MainDefine and use requires-expressions to check properties of expressions
Advanced
+------------------------------------------------------------------------- +Level Objectives +------------------ ------------------------------------------------------ +Foundational Define and use requires-expressions to check + satisfaction of expressions by given parameters + +Main Define and use requires-expressions to check + properties of expressions + +Advanced --- +------------------------------------------------------------------------- ### Motivation diff --git a/sources/modules/functions/defaulted-parameters.md b/sources/modules/functions/defaulted-parameters.md index 3fe881f..9e6a434 100644 --- a/sources/modules/functions/defaulted-parameters.md +++ b/sources/modules/functions/defaulted-parameters.md @@ -9,24 +9,16 @@ of parameters, to allow a caller to avoid specifying arguments that rarely change, or to enable expanding the set of parameters while maintaining backward compatibility with existing callers. - - - - - - - - - - - - - - - - - -
LevelObjectives
FoundationalDefine and use functions with default arguments
Main
Advancedrefinement of default arguments through multiple declarations
+------------------------------------------------------------------------ +Level Objective +----------------- ------------------------------------------------------ +Foundational Define and use functions with default arguments + +Main --- + +Advanced refinement of default arguments through multiple + declarations +------------------------------------------------------------------------ ### Motivation diff --git a/sources/modules/functions/user-defined-literals.md b/sources/modules/functions/user-defined-literals.md index 2033513..127eec9 100644 --- a/sources/modules/functions/user-defined-literals.md +++ b/sources/modules/functions/user-defined-literals.md @@ -7,24 +7,15 @@ _Skeleton instructions are typeset in italic text._ _Provides a short natural language abstract of the module’s contents._ _Specifies the different levels of teaching._ - - - - - - - - - - - - - - - - - -
LevelObjectives
Foundationalusing and understanding UDLs
Mainimplementing your own UDLs
AdvancedAdvanced use ("{}, {}!"_fmt("Hello", "World"))
+------------------------------------------------------------------------- +Level Objectives +---------------- -------------------------------------------------------- +Foundational using and understanding UDLs + +Main implementing your own UDLs + +Advanced Advanced use (```"{}, {}!"_fmt("Hello", "World")```) +------------------------------------------------------------------------- ### Motivation diff --git a/sources/modules/meta-error-handling/static_assert.md b/sources/modules/meta-error-handling/static_assert.md index d3c6a46..b82e12f 100644 --- a/sources/modules/meta-error-handling/static_assert.md +++ b/sources/modules/meta-error-handling/static_assert.md @@ -8,24 +8,16 @@ _so please don't remove these descriptions when editing the topic._ _Provides a short natural language abstract of the module’s contents._ _Specifies the different levels of teaching._ - - - - - - - - - - - - - - - - - -
LevelObjectives
FoundationalCalling static_assert with a constant expression
MainUsing static_assert to detect contract violations and improve error messages
Advanced
+---------------------------------------------------------------------------- +Level Objectives +---------------- ----------------------------------------------------------- +Foundational Calling ```static_assert``` with a constant expression + +Main Using ```static_assert``` to detect contract violations + and improve error messages + +Advanced --- +---------------------------------------------------------------------------- ### Motivation diff --git a/sources/modules/object-model/copy-semantics.md b/sources/modules/object-model/copy-semantics.md index 2e271bc..eba49f9 100644 --- a/sources/modules/object-model/copy-semantics.md +++ b/sources/modules/object-model/copy-semantics.md @@ -7,24 +7,15 @@ _Skeleton instructions are typeset in italic text._ _Provides a short natural language abstract of the module’s contents._ _Specifies the different levels of teaching._ - - - - - - - - - - - - - - - - - -
LevelObjectives
Foundationalunderstanding how and when are copies made
Mainimplementing user-defined copy operations
Advancedspecial cases: copy elision
+--------------------------------------------------------- +Level Objectives +------------- ------------------------------------------- +Foundational understanding how and when are copies made + +Main implementing user-defined copy operations + +Advanced special cases: copy elision +--------------------------------------------------------- ### Motivation From 484c296f12fd839743049af7f167072d739a0ac9 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 21:04:20 -0700 Subject: [PATCH 29/64] Added the missing license text. --- sources/main.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/main.md b/sources/main.md index f8064a3..8e8c3f8 100644 --- a/sources/main.md +++ b/sources/main.md @@ -62,7 +62,7 @@ __INCLUDE__(course_examples.md) **[NOTE: This license is copied verbatim from the C++ Core Guidelines.]** 
-__INCLUDE__(LICENSE.txt)
+__INCLUDE__(../LICENSE.txt)
# Contributors From 366a9c6de0b2a48a6eca13b84d5410e8f64c046f Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 21:27:13 -0700 Subject: [PATCH 30/64] Pulled contributor names from the Git repository revision history. --- sources/Makefile | 11 ++++++++--- sources/main.md | 9 +++++---- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/sources/Makefile b/sources/Makefile index 6dd046e..babde98 100644 --- a/sources/Makefile +++ b/sources/Makefile @@ -34,6 +34,7 @@ SOURCES = \ GENERATED_MARKDOWN = \ knowledge_areas_summary.md \ main.gen.md \ + contributors.md \ ################################################################################ # Define primary targets. @@ -59,13 +60,13 @@ spellcheck: spellcheck_result.txt # The clean target removes all files generated during the build process. .PHONY: clean clean: + rm -f $(GENERATED_MARKDOWN) rm -f guidelines.html guidelines.pdf guidelines.epub guidelines.tex rm -rf guidelines.texi - rm -f main.gen.md knowledge_areas_summary.md - rm -f missfont.log rm -rf guidelines_html rm -f spellcheck_result.txt rm -f spellcheck_expected_sorted.txt + rm -f missfont.log # The install target installs the build document (in various formats) # in the directory $(INSTALL_DIR). @@ -94,12 +95,16 @@ SPELLCHECK_DIR = $(TOP_DIR)/config/spellcheck # Preprocessing setup. ################################################################################ -main.gen.md: $(SOURCES) main.md +main.gen.md: $(SOURCES) contributors.md main.md $(MD_PREPROCESSOR) -v $(DOC_VERSION) < main.md > main.gen.md knowledge_areas_summary.md: $(SOURCES) knowledge_areas.dat $(MAKE_MARKDOWN) < knowledge_areas.dat > knowledge_areas_summary.md +contributors.md: + rm -f $@ + git log --pretty="%an; %ae" | sort | uniq | sed -e 's/@/ at /g' | sed -e 's/\./ dot /g' >> contributors.md + ################################################################################ # Establish Pandoc settings. ################################################################################ diff --git a/sources/main.md b/sources/main.md index 8e8c3f8..ac2bf76 100644 --- a/sources/main.md +++ b/sources/main.md @@ -61,14 +61,15 @@ __INCLUDE__(course_examples.md) # License {#license} **[NOTE: This license is copied verbatim from the C++ Core Guidelines.]** -
+```
 __INCLUDE__(../LICENSE.txt)
-
+``` # Contributors -For a complete list of contributors, please refer to the repository -containing this document on [GitHub](https://github.com/cplusplus/SG20). +``` +__INCLUDE__(contributors.md) +``` __INCLUDE__(contributing.md) From 5e7ff7fc4482075d5d13653c63b75c36ca76b319 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 21:32:05 -0700 Subject: [PATCH 31/64] Testing. --- sources/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/Makefile b/sources/Makefile index babde98..79b7d9e 100644 --- a/sources/Makefile +++ b/sources/Makefile @@ -103,7 +103,7 @@ knowledge_areas_summary.md: $(SOURCES) knowledge_areas.dat contributors.md: rm -f $@ - git log --pretty="%an; %ae" | sort | uniq | sed -e 's/@/ at /g' | sed -e 's/\./ dot /g' >> contributors.md + git log --all --pretty="%an; %ae" | sort | uniq | sed -e 's/@/ at /g' | sed -e 's/\./ dot /g' >> contributors.md ################################################################################ # Establish Pandoc settings. From 1c48ea509122968ce183bb22a35f9f9cc58985e5 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 21:40:34 -0700 Subject: [PATCH 32/64] Testing. --- .github/workflows/release.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 66a307c..f27ea8d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -13,6 +13,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 + fetch-depth: 0 - name: Prebuild shell: bash run: tools/build/prebuild From eace4262655cfd03e90e910f9eb03aad0b730019 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 21:42:35 -0700 Subject: [PATCH 33/64] Testing. --- .github/workflows/release.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index f27ea8d..1624def 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -13,6 +13,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 + with: fetch-depth: 0 - name: Prebuild shell: bash From dd3a41dc1250dbb84dcea88bf2b0e19f0fd59cd9 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 21:46:52 -0700 Subject: [PATCH 34/64] Testing. --- sources/Makefile | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sources/Makefile b/sources/Makefile index 79b7d9e..4d414bf 100644 --- a/sources/Makefile +++ b/sources/Makefile @@ -102,8 +102,7 @@ knowledge_areas_summary.md: $(SOURCES) knowledge_areas.dat $(MAKE_MARKDOWN) < knowledge_areas.dat > knowledge_areas_summary.md contributors.md: - rm -f $@ - git log --all --pretty="%an; %ae" | sort | uniq | sed -e 's/@/ at /g' | sed -e 's/\./ dot /g' >> contributors.md + git log --all --pretty="%an" | sort | uniq > contributors.md ################################################################################ # Establish Pandoc settings. From 703307c68f3a4a5ae35fc7341ba8d71676ea32b1 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 21:50:39 -0700 Subject: [PATCH 35/64] Testing. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index a9d0312..de78ee5 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,9 @@ This repository contains the source for the document: When the repository is tagged, this document is automatically built and made available via GitHub Pages at: + - https://cplusplus.github.io/sg20/latest - https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/latest + - https://mdadams.github.io/sg20/latest The following software is needed to build the document: From 149d0a3dd32b065afbfae69350afbc9f366858af Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 21:51:48 -0700 Subject: [PATCH 36/64] Testing. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index de78ee5..0094381 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ This repository contains the source for the document: When the repository is tagged, this document is automatically built and made available via GitHub Pages at: - - https://cplusplus.github.io/sg20/latest + - https://cplusplus.github.io/SG20/latest - https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/latest - - https://mdadams.github.io/sg20/latest + - https://mdadams.github.io/SG20/latest The following software is needed to build the document: From 619d35d856f7f99ae33ffc5d9cfe7c53ad14f39d Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 21:53:05 -0700 Subject: [PATCH 37/64] Testing. --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0094381..a387a98 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,10 @@ This repository contains the source for the document: When the repository is tagged, this document is automatically built and made available via GitHub Pages at: - - https://cplusplus.github.io/SG20/latest - - https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/latest - - https://mdadams.github.io/SG20/latest + - (soon) + - + (currently) + - (currently) The following software is needed to build the document: From 3707f46618ffcd07877fb71d287f1b3c77ffba0e Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Thu, 20 May 2021 22:06:16 -0700 Subject: [PATCH 38/64] Testing. --- README.md | 17 ++++++++++++++++- ...pellcheck_expected.txt => ignored_words.txt} | 0 sources/Makefile | 2 +- 3 files changed, 17 insertions(+), 2 deletions(-) rename config/spellcheck/{spellcheck_expected.txt => ignored_words.txt} (100%) diff --git a/README.md b/README.md index a387a98..227c251 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ The following software is needed to build the document: - awk - sed -To build, simply type: +To build the document, simply type: 1. make clean 2. make all @@ -41,3 +41,18 @@ The above commands will build the document in several formats: install/html_split/index.html The build process performs 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 words, but are flagged as erroneous + +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 + + + diff --git a/config/spellcheck/spellcheck_expected.txt b/config/spellcheck/ignored_words.txt similarity index 100% rename from config/spellcheck/spellcheck_expected.txt rename to config/spellcheck/ignored_words.txt diff --git a/sources/Makefile b/sources/Makefile index 4d414bf..22481b6 100644 --- a/sources/Makefile +++ b/sources/Makefile @@ -155,7 +155,7 @@ guidelines.tex: spellcheck_result.txt: guidelines.html rm -f $@ rm -f spellcheck_expected_sorted.txt - sort $(SPELLCHECK_DIR)/spellcheck_expected.txt | \ + sort $(SPELLCHECK_DIR)/ignored_words.txt | \ uniq > spellcheck_expected_sorted.txt PATH="$(TOP_DIR)/tools/build:$$PATH" pandoc --from $(INPUT_FORMAT) \ --lua-filter $(TOP_DIR)/tools/pandoc_filters/spellcheck.lua \ From ebafa2f2cf4a094b65e2320c49612289c34f6996 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 21 May 2021 05:40:29 -0700 Subject: [PATCH 39/64] Testing. --- .github/workflows/release.yml | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1624def..ce3dab8 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -25,9 +25,19 @@ jobs: env: DEPLOY_KEY: ${{secrets.DEPLOY_KEY}} shell: bash - run: tools/build/deploy -f -t ${{runner.temp}}/deploy_tmp -r mdadams/sg20_guidelines_for_teaching_cpp -i ${{runner.temp}}/output -z ${{github.ref}} + run: | + tools/build/deploy \ + -f -t ${{runner.temp}}/deploy_tmp \ + -r mdadams/sg20_guidelines_for_teaching_cpp \ + -i ${{runner.temp}}/output \ + -z ${{github.ref}} - name: Deploy internal env: DEPLOY_KEY: ${{secrets.ALT_DEPLOY_KEY}} shell: bash - run: tools/build/deploy -f -t ${{runner.temp}}/deploy_tmp_2 -r mdadams/SG20 -i ${{runner.temp}}/output -z ${{github.ref}} + run: | + tools/build/deploy \ + -f -t ${{runner.temp}}/deploy_tmp_2 \ + -r mdadams/SG20 \ + -i ${{runner.temp}}/output \ + -z ${{github.ref}} From 2f705dbdac9a23063224aae0da8e383898820dc6 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 21 May 2021 05:56:28 -0700 Subject: [PATCH 40/64] Testing. --- .github/workflows/ci.yml | 4 ++-- .github/workflows/release.yml | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ac08914..ea444d5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,9 +10,9 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - - name: Prebuild + - name: Prepare to build the document. shell: bash run: tools/build/prebuild - - name: Build + - 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 index ce3dab8..3a253a7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -15,13 +15,13 @@ jobs: - uses: actions/checkout@v2 with: fetch-depth: 0 - - name: Prebuild + - name: Prepare to build the document. shell: bash run: tools/build/prebuild - - name: Build + - name: Build the document. shell: bash run: tools/build/build -d ${{runner.temp}}/output -z ${{github.ref}} - - name: Deploy + - name: Deploy the built document to a GitHub Pages branch (in a different repository). env: DEPLOY_KEY: ${{secrets.DEPLOY_KEY}} shell: bash @@ -31,7 +31,7 @@ jobs: -r mdadams/sg20_guidelines_for_teaching_cpp \ -i ${{runner.temp}}/output \ -z ${{github.ref}} - - name: Deploy internal + - name: Deploy the built document to a GitHub Pages branch (in the same repository). env: DEPLOY_KEY: ${{secrets.ALT_DEPLOY_KEY}} shell: bash From 8b6f87a233cff30103d4b0e660cd5530cfd6c614 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 21 May 2021 06:04:09 -0700 Subject: [PATCH 41/64] Testing. --- .github/workflows/release.yml | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3a253a7..ba916fb 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -21,23 +21,25 @@ jobs: - name: Build the document. shell: bash run: tools/build/build -d ${{runner.temp}}/output -z ${{github.ref}} - - name: Deploy the built document to a GitHub Pages branch (in a different repository). + - name: Deploy the built document to a GitHub Pages branch. env: DEPLOY_KEY: ${{secrets.DEPLOY_KEY}} shell: bash run: | tools/build/deploy \ - -f -t ${{runner.temp}}/deploy_tmp \ - -r mdadams/sg20_guidelines_for_teaching_cpp \ + -f \ + -t ${{runner.temp}}/deploy_tmp_2 \ -i ${{runner.temp}}/output \ + -r mdadams/SG20 \ -z ${{github.ref}} - - name: Deploy the built document to a GitHub Pages branch (in the same repository). + - name: Deploy the built document to a GitHub Pages branch. env: DEPLOY_KEY: ${{secrets.ALT_DEPLOY_KEY}} shell: bash run: | tools/build/deploy \ - -f -t ${{runner.temp}}/deploy_tmp_2 \ - -r mdadams/SG20 \ + -f \ + -t ${{runner.temp}}/deploy_tmp \ -i ${{runner.temp}}/output \ + -r mdadams/sg20_guidelines_for_teaching_cpp \ -z ${{github.ref}} From 1ba86b1059748c89b0c722751aba13f5281057f6 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 21 May 2021 06:06:45 -0700 Subject: [PATCH 42/64] Testing. --- .github/workflows/release.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ba916fb..f528738 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -28,7 +28,7 @@ jobs: run: | tools/build/deploy \ -f \ - -t ${{runner.temp}}/deploy_tmp_2 \ + -t ${{runner.temp}}/deploy_tmp \ -i ${{runner.temp}}/output \ -r mdadams/SG20 \ -z ${{github.ref}} @@ -39,7 +39,7 @@ jobs: run: | tools/build/deploy \ -f \ - -t ${{runner.temp}}/deploy_tmp \ + -t ${{runner.temp}}/deploy_tmp_2 \ -i ${{runner.temp}}/output \ -r mdadams/sg20_guidelines_for_teaching_cpp \ -z ${{github.ref}} From 1fb755d9134bae134eb6ce8f23b00f00e27960a7 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 21 May 2021 06:23:53 -0700 Subject: [PATCH 43/64] Testing. --- Makefile | 4 ++-- README.md | 17 +++++++++++++---- sources/Makefile | 20 +++++++++++++------- 3 files changed, 28 insertions(+), 13 deletions(-) diff --git a/Makefile b/Makefile index fbf8ad0..1ee6116 100644 --- a/Makefile +++ b/Makefile @@ -1,8 +1,8 @@ SUBDIRS = \ sources \ -.PHONY: all clean install -all clean install: +.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 index 227c251..fbf6b5b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -README -====== +Guidelines for Teaching C++ +=========================== This repository contains the source for the document: @@ -13,6 +13,8 @@ and made available via GitHub Pages at: (currently) - (currently) +# Prerequisites for Building the Document + The following software is needed to build the document: - pandoc @@ -22,6 +24,8 @@ The following software is needed to build the document: - awk - sed +# Building the Document + To build the document, simply type: 1. make clean @@ -40,7 +44,14 @@ The above commands will build the document in several formats: - 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: @@ -54,5 +65,3 @@ config/spellcheck/wordlist. Words in category 2 should be added to the file config/spellcheck/ignored_words.txt - - diff --git a/sources/Makefile b/sources/Makefile index 22481b6..cc83c04 100644 --- a/sources/Makefile +++ b/sources/Makefile @@ -45,13 +45,18 @@ GENERATED_MARKDOWN = \ .PHONY: all all: documents spellcheck +# The world target is similar to the all target except that it builds the +# document in some additional formats. +.PHONY: world +world: all documents_extra + # The documents target builds the document in a minimal set of formats. .PHONY: documents documents: guidelines.html guidelines_html guidelines.epub -# The world target builds the document in a few extra formats. +# The documents_extra target builds the document in a few extra formats. .PHONY: world -world: documents guidelines.pdf +documents_extra: guidelines.pdf # The spellcheck format performs a spell check on the document. .PHONY: spellcheck @@ -72,16 +77,17 @@ clean: # in the directory $(INSTALL_DIR). .PHONY: install install: all - if [ ! -d $(INSTALL_DIR) ]; then mkdir -p $(INSTALL_DIR) || exit 1; fi + if [ ! -d "$(INSTALL_DIR)" ]; then mkdir -p "$(INSTALL_DIR)" || exit 1; fi for dir in html html/images; do \ if [ ! -d "$(INSTALL_DIR)/$$dir" ]; then \ mkdir -p "$(INSTALL_DIR)/$$dir" || exit 1; \ fi; \ done - cp -f images/cpp_logo.png $(INSTALL_DIR)/html/images - cp -f guidelines.html $(INSTALL_DIR)/html/index.html - cp -r -f guidelines_html $(INSTALL_DIR)/html_split - cp -f guidelines.epub $(INSTALL_DIR) + cp -f images/cpp_logo.png "$(INSTALL_DIR)/html/images" + cp -f guidelines.html "$(INSTALL_DIR)/html/index.html" + cp -r -f guidelines_html "$(INSTALL_DIR)/html_split" + cp -f guidelines.epub "$(INSTALL_DIR)" + [ -f guidelines.pdf ] && cp -f guidelines.pdf "$(INSTALL_DIR)" ################################################################################ # Some additional configuration. From a147a1ffa1944889b605c9e97e20efe40c4aa559 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 21 May 2021 06:29:07 -0700 Subject: [PATCH 44/64] Testing. --- sources/Makefile | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/sources/Makefile b/sources/Makefile index cc83c04..a20dc37 100644 --- a/sources/Makefile +++ b/sources/Makefile @@ -77,17 +77,21 @@ clean: # in the directory $(INSTALL_DIR). .PHONY: install install: all - if [ ! -d "$(INSTALL_DIR)" ]; then mkdir -p "$(INSTALL_DIR)" || exit 1; fi + if [ ! -d "$(INSTALL_DIR)" ]; then \ + mkdir -p "$(INSTALL_DIR)" || exit 1; \ + fi for dir in html html/images; do \ - if [ ! -d "$(INSTALL_DIR)/$$dir" ]; then \ - mkdir -p "$(INSTALL_DIR)/$$dir" || exit 1; \ - fi; \ - done + if [ ! -d "$(INSTALL_DIR)/$$dir" ]; then \ + mkdir -p "$(INSTALL_DIR)/$$dir" || exit 1; \ + fi; \ + done cp -f images/cpp_logo.png "$(INSTALL_DIR)/html/images" cp -f guidelines.html "$(INSTALL_DIR)/html/index.html" cp -r -f guidelines_html "$(INSTALL_DIR)/html_split" cp -f guidelines.epub "$(INSTALL_DIR)" - [ -f guidelines.pdf ] && cp -f guidelines.pdf "$(INSTALL_DIR)" + if [ -f guidelines.pdf ]; then \ + cp -f guidelines.pdf "$(INSTALL_DIR)"; \ + fi ################################################################################ # Some additional configuration. From e5a80557c1decce49da672b98e8506e2f0e76dcc Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 21 May 2021 06:35:18 -0700 Subject: [PATCH 45/64] Testing. --- sources/obtaining_document.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/obtaining_document.md b/sources/obtaining_document.md index 9c6734d..53fff58 100644 --- a/sources/obtaining_document.md +++ b/sources/obtaining_document.md @@ -15,7 +15,7 @@ following formats: 3. online (HTML) format, split across multiple HTML documents: - **[Note: The support for this format needs more work to look nice.]** + **[Note: The support for this format needs more work (to beautify and fix linking issues.]** Older versions of this document are also available. In general version _ver_ is available at From 4d4638ea27276161b4f1ec443e71354e5b54799f Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 21 May 2021 06:38:58 -0700 Subject: [PATCH 46/64] Testing. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fbf6b5b..4fce122 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,8 @@ The following software is needed to build the document: - pandoc - aspell - - make - various basic POSIX utilities, including (amongst others): + - make - awk - sed From 91322f0bf35fa686ee22d0635581c01cab6dd787 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 21 May 2021 06:41:00 -0700 Subject: [PATCH 47/64] Testing. --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index 4fce122..a19f7cf 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,11 @@ The following software is needed to build the document: - 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: From 663415b4bbafcc1d6c2f7b36e3c3db6b696a1c64 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 21 May 2021 06:50:53 -0700 Subject: [PATCH 48/64] Testing. --- README.md | 3 ++- config/spellcheck/ignored_words.txt | 5 ----- config/spellcheck/wordlist | 7 ++++++- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index a19f7cf..163bdb1 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,8 @@ 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 words, but are flagged as erroneous + 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. diff --git a/config/spellcheck/ignored_words.txt b/config/spellcheck/ignored_words.txt index f8f1ff0..adbd386 100644 --- a/config/spellcheck/ignored_words.txt +++ b/config/spellcheck/ignored_words.txt @@ -1,7 +1,6 @@ args Bjarne checkmark -computable constexpr cppreference decltype @@ -13,7 +12,6 @@ Florian func Furst Hyland -IDEs JC Krathwohl ness @@ -22,13 +20,10 @@ NRVO req RVO Sattler -SFINAE SG Stroustrup struct udl -UDL -UDLs ver Winkel Hinnant diff --git a/config/spellcheck/wordlist b/config/spellcheck/wordlist index 416bd6c..a36f99f 100644 --- a/config/spellcheck/wordlist +++ b/config/spellcheck/wordlist @@ -1,4 +1,4 @@ -personal_ws-1.1 en 11 +personal_ws-1.1 en 14 destructors invariants metaprogramming @@ -10,3 +10,8 @@ toolchains toolchain boolean lawyering +computable +UDL +UDLs +IDEs +SFINAE From 8b370a42494ff0ed59db6bb3fbc7acfe792a94ee Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Fri, 21 May 2021 07:16:54 -0700 Subject: [PATCH 49/64] Add missing files. --- sources/modules/compile-time-programming/concepts.md | 3 +++ .../modules/compile-time-programming/function-templates.md | 3 +++ sources/modules/compile-time-programming/requires-clause.md | 6 ++++++ sources/modules/functions/calling-functions.md | 6 ++++++ sources/modules/functions/member-functions.md | 6 ++++++ sources/modules/object-model/constant-objects.md | 6 ++++++ sources/modules/object-model/constructors.md | 6 ++++++ sources/modules/object-model/declarations.md | 6 ++++++ sources/modules/object-model/move-semantics.md | 6 ++++++ sources/modules/object-model/objects.md | 6 ++++++ sources/modules/object-model/rule-of-five.md | 6 ++++++ sources/modules/object-model/rule-of-zero.md | 6 ++++++ sources/modules/object-model/special-member-functions.md | 6 ++++++ sources/modules/object-model/types.md | 6 ++++++ sources/modules/program-design/concepts.md | 1 + sources/modules/user-defined-types/user-defined-literals.md | 1 + {old => tools/old}/Readme.md | 0 {old => tools/old}/gen_readme.py | 0 {old => tools/old}/skeleton.md | 0 {old => tools/old}/tools/pytest.ini | 0 {old => tools/old}/tools/requirements.txt | 0 .../old}/tools/tests/TEST_INPUTS/fix_wrong_sections.md | 0 .../old}/tools/tests/TEST_INPUTS/missing_sections.md | 0 {old => tools/old}/tools/tests/TEST_INPUTS/test_skeleton.md | 0 .../tools/tests/TEST_INPUTS/user_content_heading_topic.md | 0 {old => tools/old}/tools/tests/topic_updater_test.py | 0 {old => tools/old}/topic_updater.py | 0 27 files changed, 80 insertions(+) create mode 100644 sources/modules/compile-time-programming/concepts.md create mode 100644 sources/modules/compile-time-programming/function-templates.md create mode 100644 sources/modules/compile-time-programming/requires-clause.md create mode 100644 sources/modules/functions/calling-functions.md create mode 100644 sources/modules/functions/member-functions.md create mode 100644 sources/modules/object-model/constant-objects.md create mode 100644 sources/modules/object-model/constructors.md create mode 100644 sources/modules/object-model/declarations.md create mode 100644 sources/modules/object-model/move-semantics.md create mode 100644 sources/modules/object-model/objects.md create mode 100644 sources/modules/object-model/rule-of-five.md create mode 100644 sources/modules/object-model/rule-of-zero.md create mode 100644 sources/modules/object-model/special-member-functions.md create mode 100644 sources/modules/object-model/types.md create mode 100644 sources/modules/program-design/concepts.md create mode 100644 sources/modules/user-defined-types/user-defined-literals.md rename {old => tools/old}/Readme.md (100%) rename {old => tools/old}/gen_readme.py (100%) rename {old => tools/old}/skeleton.md (100%) rename {old => tools/old}/tools/pytest.ini (100%) rename {old => tools/old}/tools/requirements.txt (100%) rename {old => tools/old}/tools/tests/TEST_INPUTS/fix_wrong_sections.md (100%) rename {old => tools/old}/tools/tests/TEST_INPUTS/missing_sections.md (100%) rename {old => tools/old}/tools/tests/TEST_INPUTS/test_skeleton.md (100%) rename {old => tools/old}/tools/tests/TEST_INPUTS/user_content_heading_topic.md (100%) rename {old => tools/old}/tools/tests/topic_updater_test.py (100%) rename {old => tools/old}/topic_updater.py (100%) diff --git a/sources/modules/compile-time-programming/concepts.md b/sources/modules/compile-time-programming/concepts.md new file mode 100644 index 0000000..7e58a7e --- /dev/null +++ b/sources/modules/compile-time-programming/concepts.md @@ -0,0 +1,3 @@ +# Compile-time programming: concepts + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/compile-time-programming/function-templates.md b/sources/modules/compile-time-programming/function-templates.md new file mode 100644 index 0000000..c0bbb6f --- /dev/null +++ b/sources/modules/compile-time-programming/function-templates.md @@ -0,0 +1,3 @@ +# Compile-time programming: Function Templates + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/compile-time-programming/requires-clause.md b/sources/modules/compile-time-programming/requires-clause.md new file mode 100644 index 0000000..b4d5a99 --- /dev/null +++ b/sources/modules/compile-time-programming/requires-clause.md @@ -0,0 +1,6 @@ +# Compile-time programming: requires-clause + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/functions/calling-functions.md b/sources/modules/functions/calling-functions.md new file mode 100644 index 0000000..183a5e5 --- /dev/null +++ b/sources/modules/functions/calling-functions.md @@ -0,0 +1,6 @@ +# C++ functions: calling functions + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/functions/member-functions.md b/sources/modules/functions/member-functions.md new file mode 100644 index 0000000..cd67792 --- /dev/null +++ b/sources/modules/functions/member-functions.md @@ -0,0 +1,6 @@ +# C++ functions: member functions + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/object-model/constant-objects.md b/sources/modules/object-model/constant-objects.md new file mode 100644 index 0000000..4e034eb --- /dev/null +++ b/sources/modules/object-model/constant-objects.md @@ -0,0 +1,6 @@ +# C++ object model: constant objects + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/object-model/constructors.md b/sources/modules/object-model/constructors.md new file mode 100644 index 0000000..6c08eb9 --- /dev/null +++ b/sources/modules/object-model/constructors.md @@ -0,0 +1,6 @@ +# C++ object model: constructor + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/object-model/declarations.md b/sources/modules/object-model/declarations.md new file mode 100644 index 0000000..c4497db --- /dev/null +++ b/sources/modules/object-model/declarations.md @@ -0,0 +1,6 @@ +# C++ object model: declarations + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/object-model/move-semantics.md b/sources/modules/object-model/move-semantics.md new file mode 100644 index 0000000..a0b4cc0 --- /dev/null +++ b/sources/modules/object-model/move-semantics.md @@ -0,0 +1,6 @@ +# C++ object model: move semantics + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/object-model/objects.md b/sources/modules/object-model/objects.md new file mode 100644 index 0000000..cb59892 --- /dev/null +++ b/sources/modules/object-model/objects.md @@ -0,0 +1,6 @@ +# C++ object model: objects + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/object-model/rule-of-five.md b/sources/modules/object-model/rule-of-five.md new file mode 100644 index 0000000..78ef963 --- /dev/null +++ b/sources/modules/object-model/rule-of-five.md @@ -0,0 +1,6 @@ +# C++ object model: rule of five + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/object-model/rule-of-zero.md b/sources/modules/object-model/rule-of-zero.md new file mode 100644 index 0000000..8ee7520 --- /dev/null +++ b/sources/modules/object-model/rule-of-zero.md @@ -0,0 +1,6 @@ +# C++ object model: rule of zero + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/object-model/special-member-functions.md b/sources/modules/object-model/special-member-functions.md new file mode 100644 index 0000000..091f31a --- /dev/null +++ b/sources/modules/object-model/special-member-functions.md @@ -0,0 +1,6 @@ +# C++ object model: special member functions + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/object-model/types.md b/sources/modules/object-model/types.md new file mode 100644 index 0000000..4eaa1ab --- /dev/null +++ b/sources/modules/object-model/types.md @@ -0,0 +1,6 @@ +# C++ object model: types + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/program-design/concepts.md b/sources/modules/program-design/concepts.md new file mode 100644 index 0000000..df6c8a0 --- /dev/null +++ b/sources/modules/program-design/concepts.md @@ -0,0 +1 @@ +See [concepts](../compile-time-programmings/concepts.md). diff --git a/sources/modules/user-defined-types/user-defined-literals.md b/sources/modules/user-defined-types/user-defined-literals.md new file mode 100644 index 0000000..c23e1b2 --- /dev/null +++ b/sources/modules/user-defined-types/user-defined-literals.md @@ -0,0 +1 @@ +See [user-defined-literals](../functions/user-defined-literals.md). diff --git a/old/Readme.md b/tools/old/Readme.md similarity index 100% rename from old/Readme.md rename to tools/old/Readme.md diff --git a/old/gen_readme.py b/tools/old/gen_readme.py similarity index 100% rename from old/gen_readme.py rename to tools/old/gen_readme.py diff --git a/old/skeleton.md b/tools/old/skeleton.md similarity index 100% rename from old/skeleton.md rename to tools/old/skeleton.md diff --git a/old/tools/pytest.ini b/tools/old/tools/pytest.ini similarity index 100% rename from old/tools/pytest.ini rename to tools/old/tools/pytest.ini diff --git a/old/tools/requirements.txt b/tools/old/tools/requirements.txt similarity index 100% rename from old/tools/requirements.txt rename to tools/old/tools/requirements.txt diff --git a/old/tools/tests/TEST_INPUTS/fix_wrong_sections.md b/tools/old/tools/tests/TEST_INPUTS/fix_wrong_sections.md similarity index 100% rename from old/tools/tests/TEST_INPUTS/fix_wrong_sections.md rename to tools/old/tools/tests/TEST_INPUTS/fix_wrong_sections.md diff --git a/old/tools/tests/TEST_INPUTS/missing_sections.md b/tools/old/tools/tests/TEST_INPUTS/missing_sections.md similarity index 100% rename from old/tools/tests/TEST_INPUTS/missing_sections.md rename to tools/old/tools/tests/TEST_INPUTS/missing_sections.md diff --git a/old/tools/tests/TEST_INPUTS/test_skeleton.md b/tools/old/tools/tests/TEST_INPUTS/test_skeleton.md similarity index 100% rename from old/tools/tests/TEST_INPUTS/test_skeleton.md rename to tools/old/tools/tests/TEST_INPUTS/test_skeleton.md diff --git a/old/tools/tests/TEST_INPUTS/user_content_heading_topic.md b/tools/old/tools/tests/TEST_INPUTS/user_content_heading_topic.md similarity index 100% rename from old/tools/tests/TEST_INPUTS/user_content_heading_topic.md rename to tools/old/tools/tests/TEST_INPUTS/user_content_heading_topic.md diff --git a/old/tools/tests/topic_updater_test.py b/tools/old/tools/tests/topic_updater_test.py similarity index 100% rename from old/tools/tests/topic_updater_test.py rename to tools/old/tools/tests/topic_updater_test.py diff --git a/old/topic_updater.py b/tools/old/topic_updater.py similarity index 100% rename from old/topic_updater.py rename to tools/old/topic_updater.py From 43c3c866d0a29722b503c6337529d080fee252e6 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Mon, 31 May 2021 08:37:35 -0700 Subject: [PATCH 50/64] Added a description of the repository organization to the top-level README document. --- README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/README.md b/README.md index 163bdb1..5df96c6 100644 --- a/README.md +++ b/README.md @@ -71,3 +71,42 @@ 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 in by pandoc during + the document build process. + - spellcheck + The directory contains lists of additional works and ignorable errors + for spell checking. +- sources + This directory hierarchy contains the source files for the document. + - css + This directory contains CSS files used when building the document + 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. From ca4ff6aaeed42c917f46d14f118cd2a6b4d27e66 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Mon, 31 May 2021 08:42:09 -0700 Subject: [PATCH 51/64] Made some minor editorial changes to the top-level README. --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 5df96c6..ad77284 100644 --- a/README.md +++ b/README.md @@ -75,38 +75,38 @@ config/spellcheck/ignored_words.txt The files in this repository are organized into directories as follows: -- config. +- config: This directory contains configuration files that control various aspects of how the guidelines document is built. - - pandoc_templates + - pandoc_templates: This directory contains document templates used in by pandoc during the document build process. - - spellcheck + - spellcheck: The directory contains lists of additional works and ignorable errors for spell checking. -- sources +- sources: This directory hierarchy contains the source files for the document. - - css + - css: This directory contains CSS files used when building the document in HTML format. - - images + - images: This directory contains images used in the document. - - modules + - modules: The directory hierarchy contains the information for individual modules and topics. There is one directory per module and one file per topic. -- tools +- tools: The directory hierarchy contains various scripts and other tools used for building and deploying the document to GitHub pages site. - - build + - build: This directory contains scripts used for building and deploying the document. - - old + - 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 + - pandoc_filters: This directory contains various filters needed for pandoc. These filters do things such as allow markdown-aware spell checking. From b330b1278ca3289aebbd48e70257ec98b7f7a273 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Mon, 7 Jun 2021 07:38:59 -0700 Subject: [PATCH 52/64] Fixed a typo in the README. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ad77284..78530d2 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ The files in this repository are organized into directories as follows: This directory contains configuration files that control various aspects of how the guidelines document is built. - pandoc_templates: - This directory contains document templates used in by pandoc during + This directory contains document templates used by pandoc during the document build process. - spellcheck: The directory contains lists of additional works and ignorable errors From bc821d5ebdfdb241fcd80bc5db73a9cc6f8c53c6 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Mon, 7 Jun 2021 07:44:58 -0700 Subject: [PATCH 53/64] Fixed wording/spelling in README document. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 78530d2..e8799f5 100644 --- a/README.md +++ b/README.md @@ -82,12 +82,12 @@ The files in this repository are organized into directories as follows: This directory contains document templates used by pandoc during the document build process. - spellcheck: - The directory contains lists of additional works and ignorable errors + 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 when building the document + This directory contains CSS files used by the document when built in HTML format. - images: This directory contains images used in the document. From 3d81d6cdfff783b19fabfc89e69cae18fb21058c Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 20 Jul 2021 16:04:08 -0700 Subject: [PATCH 54/64] Added preliminary support for the use of an access token for authentication during deployment. --- .github/workflows/release.yml | 8 ++- tools/build/deploy | 117 ++++++++++++++++++++++++---------- 2 files changed, 92 insertions(+), 33 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index f528738..fb0fb65 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -21,17 +21,22 @@ jobs: - 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. - name: Deploy the built document to a GitHub Pages branch. env: - DEPLOY_KEY: ${{secrets.DEPLOY_KEY}} + 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 \ -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}} @@ -39,6 +44,7 @@ jobs: run: | tools/build/deploy \ -f \ + -m key \ -t ${{runner.temp}}/deploy_tmp_2 \ -i ${{runner.temp}}/output \ -r mdadams/sg20_guidelines_for_teaching_cpp \ diff --git a/tools/build/deploy b/tools/build/deploy index a60ecc3..117c41c 100755 --- a/tools/build/deploy +++ b/tools/build/deploy @@ -11,6 +11,14 @@ panic() exit 1 } +join_by() +{ + local IFS="$1" + shift + echo "$*" +} + + # Print usage information and exit. usage() { @@ -67,9 +75,12 @@ github_ref= force=0 prepare_only=0 verbose=1 +deploy_mode= -while getopts b:i:r:t:z:fnvq opt; do +while getopts b:i:r:t:z:fnvqm: opt; do case $opt in + m) + deploy_mode="$OPTARG";; v) verbose=$((verbose + 1));; q) @@ -107,9 +118,22 @@ fi if [ -z "$repo_name" ]; then usage "no repository name specified" fi -if [ -z "$DEPLOY_KEY" ]; then - usage "DEPLOY_KEY environment variable not set" -fi + +case "$deploy_mode" in +key) + if [ -z "$DEPLOY_KEY" ]; then + usage "DEPLOY_KEY environment variable not set" + fi + ;; +token) + if [ -z "$DEPLOY_TOKEN" ]; then + usage "DEPLOY_TOKEN environment variable not set" + fi + ;; +*) + usage "bad deployment mode specified $deploy_mode" + ;; +esac if [ "$verbose" -ge 1 ]; then echo "temporary directory $tmp_dir" @@ -139,43 +163,72 @@ fi tmp_dir="$tmp_dir/deploy" git_dir="$tmp_dir/git" -ssh_dir="$HOME/.ssh" -private_key_file="$ssh_dir/private_key" version_dir="$git_dir/$version" -repo_url="ssh://git@github.com/$repo_name.git" - -if [ "$verbose" -ge 1 ]; then - echo "repository URL: $repo_url" -fi +github_host="github.com" +github_user="git" ################################################################################ -# Setup SSH client configuration. +# Setup SSH client configuration if needed. ################################################################################ -if [ "$force" -eq 0 -a -e "$private_key_file" ]; then - panic "private key file already exists" -fi +case "$deploy_mode" in +ssh) -if [ ! -d "$ssh_dir" ]; then - mkdir -p "$ssh_dir" || \ - panic "cannot make directory $ssh_dir" -fi -if [ ! -d "$tmp_dir" ]; then - mkdir -p "$ssh_dir" || \ - panic "cannot make directory $ssh_dir" -fi + ssh_dir="$HOME/.ssh" + private_key_file="$ssh_dir/private_key" -echo "$DEPLOY_KEY" > "$private_key_file" || \ - panic "cannot create private key file" -chmod u+rw,g=,o= "$private_key_file" || \ - panic "cannot set permissions for private key file" + repo_url="ssh://git@$github_host/$repo_name.git" -if [ -z "$SSH_AGENT_PID" ]; then - eval $(ssh-agent) || \ - panic "cannot start ssh-agent" + if [ "$force" -eq 0 -a -e "$private_key_file" ]; then + panic "private key file already exists" + fi + + if [ ! -d "$ssh_dir" ]; then + mkdir -p "$ssh_dir" || \ + panic "cannot make directory $ssh_dir" + fi + if [ ! -d "$tmp_dir" ]; then + mkdir -p "$ssh_dir" || \ + panic "cannot make directory $ssh_dir" + fi + + echo "$DEPLOY_KEY" > "$private_key_file" || \ + panic "cannot create private key file" + chmod u+rw,g=,o= "$private_key_file" || \ + panic "cannot set permissions for private key file" + + if [ -z "$SSH_AGENT_PID" ]; then + eval $(ssh-agent) || \ + panic "cannot start ssh-agent" + fi + ssh-add "$private_key_file" || \ + panic "ssh-add failed" + +token) + + git config --global credential.helper 'cache --timeout=86400' || \ + panic "cannot set credential helper" + cred_info=() + cred_info+=("protocol=https") + cred_info+=("host=$github_host") + cred_info+=("username=$github_user") + cred_info+=("password=$DEPLOY_TOKEN") + cred_string="$(join_by $'\n' "${pairs[@]}")" || \ + panic "string processing failed" + git credential approve <<< "$cred_string" || \ + panic "git credential approve failed" + + repo_url="https://$github_user@$github_host/$repo_name.git" + ;; + +*) + panic "unexpected case";; + +esac + +if [ "$verbose" -ge 1 ]; then + echo "repository URL: $repo_url" fi -ssh-add "$private_key_file" || \ - panic "ssh-add failed" ################################################################################ # Add new release to GitHub pages repository. From 4de0d071745889b0a636fe99a9d5229b817b3301 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 20 Jul 2021 16:08:26 -0700 Subject: [PATCH 55/64] Fixed a typo in the deploy script. --- tools/build/deploy | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tools/build/deploy b/tools/build/deploy index 117c41c..84abf4f 100755 --- a/tools/build/deploy +++ b/tools/build/deploy @@ -203,6 +203,7 @@ ssh) fi ssh-add "$private_key_file" || \ panic "ssh-add failed" + ;; token) @@ -222,7 +223,8 @@ token) ;; *) - panic "unexpected case";; + panic "unexpected case" + ;; esac From eb3a03c9b68b90beb8d3701924c5d558d0523337 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 20 Jul 2021 16:17:23 -0700 Subject: [PATCH 56/64] Made more changes to the deploy script. --- tools/build/deploy | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tools/build/deploy b/tools/build/deploy index 84abf4f..15bbde1 100755 --- a/tools/build/deploy +++ b/tools/build/deploy @@ -214,8 +214,11 @@ token) cred_info+=("host=$github_host") cred_info+=("username=$github_user") cred_info+=("password=$DEPLOY_TOKEN") - cred_string="$(join_by $'\n' "${pairs[@]}")" || \ + cred_string="$(join_by $'\n' "${cred_info[@]}")" || \ panic "string processing failed" + cred_string="$(git credential fill <<< "$cred_string")" || \ + panic "git credential fill failed" + git credential approve <<< "$cred_string" || \ panic "git credential approve failed" From 3a4df84e358fd3ab5456a364a6e8560afd8473fb Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 20 Jul 2021 16:20:18 -0700 Subject: [PATCH 57/64] Made another change to the deploy script. --- tools/build/deploy | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tools/build/deploy b/tools/build/deploy index 15bbde1..d88de76 100755 --- a/tools/build/deploy +++ b/tools/build/deploy @@ -172,7 +172,8 @@ github_user="git" ################################################################################ case "$deploy_mode" in -ssh) + +key) ssh_dir="$HOME/.ssh" private_key_file="$ssh_dir/private_key" @@ -226,6 +227,7 @@ token) ;; *) + panic "unexpected case" ;; From 75a5e1f89390cf600646e1c96a62509c6f742403 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 20 Jul 2021 16:37:28 -0700 Subject: [PATCH 58/64] Made some editorial changes to the GitHub Actions workflow files. --- .github/workflows/ci.yml | 9 ++++++++- .github/workflows/release.yml | 29 ++++++++++++++++++++++++++++- 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ea444d5..41476a3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,9 +10,16 @@ jobs: 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 + run: | + tools/build/build \ + -d ${{runner.temp}}/output \ + -z ${{github.ref}} \ + -s + ############################################################ diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index fb0fb65..38c1b0c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -15,12 +15,19 @@ jobs: - 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}} + 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. - name: Deploy the built document to a GitHub Pages branch. @@ -34,7 +41,25 @@ jobs: -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. @@ -48,4 +73,6 @@ jobs: -t ${{runner.temp}}/deploy_tmp_2 \ -i ${{runner.temp}}/output \ -r mdadams/sg20_guidelines_for_teaching_cpp \ + -b gh-pages \ -z ${{github.ref}} + ############################################################ From 1ae2d425650c75e361a53126668688c206a165bb Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 20 Jul 2021 16:42:12 -0700 Subject: [PATCH 59/64] Commented out some obsolete/unused lines in the release workflow file. --- .github/workflows/release.yml | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 38c1b0c..3db1cda 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -30,19 +30,20 @@ jobs: ############################################################ # The following deploys to a different branch of the same repository # using an access token for authentication. - - 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}} + # 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. From 7081bd74c92ad1496acbc3604c1e1f9ba4529da8 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 20 Jul 2021 16:51:16 -0700 Subject: [PATCH 60/64] Added mention of some new links in the teaching guidelines document. --- sources/obtaining_document.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sources/obtaining_document.md b/sources/obtaining_document.md index 53fff58..f2a5e3d 100644 --- a/sources/obtaining_document.md +++ b/sources/obtaining_document.md @@ -9,13 +9,17 @@ following formats: 1. online (HTML) format as a single large HTML document: + [later to be ?] 2. EPUB format: + [later to be ?] 3. online (HTML) format, split across multiple HTML documents: - **[Note: The support for this format needs more work (to beautify and fix linking issues.]** + [later to be ?] + **[Note: The support for this format needs more work (in order to beautify + and fix linking issues).]** Older versions of this document are also available. In general version _ver_ is available at From b65cfc75e59277b40e1393ea8cbbe0db9c6f9bf4 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 20 Jul 2021 16:56:15 -0700 Subject: [PATCH 61/64] Added mention of a new link in the teaching guidelines document. --- sources/obtaining_document.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sources/obtaining_document.md b/sources/obtaining_document.md index f2a5e3d..b4d2a34 100644 --- a/sources/obtaining_document.md +++ b/sources/obtaining_document.md @@ -26,4 +26,5 @@ In general version _ver_ is available at https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/_ver_. For example, version v0.1.0 (assuming that this version exists) would be available at -. +[later to be +?]. From f1bff3f333410d6f333bf846e47adeb450393c7e Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 20 Jul 2021 17:09:32 -0700 Subject: [PATCH 62/64] Removed the copy elision module that is neither complete nor approved for inclusion in the guidelines document. --- sources/Makefile | 1 - sources/main.md | 2 -- sources/modules/object-model/copy_elision.md | 33 -------------------- 3 files changed, 36 deletions(-) delete mode 100644 sources/modules/object-model/copy_elision.md diff --git a/sources/Makefile b/sources/Makefile index a20dc37..b3a5121 100644 --- a/sources/Makefile +++ b/sources/Makefile @@ -19,7 +19,6 @@ SOURCES = \ modules/compile-time-programming/requires-expressions.md \ modules/functions/defaulted-parameters.md \ modules/functions/user-defined-literals.md \ - modules/object-model/copy_elision.md \ modules/object-model/copy-semantics.md \ course_examples.md \ disclaimer.md \ diff --git a/sources/main.md b/sources/main.md index ac2bf76..71e462d 100644 --- a/sources/main.md +++ b/sources/main.md @@ -50,8 +50,6 @@ __INCLUDE__(modules/functions/defaulted-parameters.md) __INCLUDE__(modules/compile-time-programming/requires-expressions.md) -__INCLUDE__(modules/object-model/copy_elision.md) - __INCLUDE__(modules/meta-error-handling/static_assert.md) [//]: # ( ********** END OF DETAILED TOPIC DOCUMENTS ********** ) diff --git a/sources/modules/object-model/copy_elision.md b/sources/modules/object-model/copy_elision.md deleted file mode 100644 index 6650650..0000000 --- a/sources/modules/object-model/copy_elision.md +++ /dev/null @@ -1,33 +0,0 @@ -## Copy Elision and Implicit Moving {#copy-elision} - -### Basic Learning Outcomes {#copy-elision-basic} - -### Intermediate Learning Outcomes {#copy-elision-intermediate} - -After completing this unit, the student should be able to: - -- explain what copy elision and implicit moving are - and why they are beneficial; - -- explain what is meant by return value optimization (RVO) - and named RVO (NRVO); - -- for certain common code patterns, be able identify whether copy, move, or - copy elision takes place. - -### Advanced Learning Outcomes {#copy-elision-advanced} - -After completing this unit, the student should be able to: - -- identify the particular circumstances when copy - elision is permitted (but not necessarily required) - and when it is required; - -- in arbitrary code, be able to identify whether copy, move, or copy - elision takes place. - -### Common Misunderstandings - -Some common misunderstandings include the following: - -- Copy elision is only relevant to construction not assignment. From ba572fe6aa22fbf1f3d2c53704f0ee9e98360d4a Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 20 Jul 2021 17:20:08 -0700 Subject: [PATCH 63/64] Removed an obsolete entry in the knowledge areas file. --- sources/knowledge_areas.dat | 1 - 1 file changed, 1 deletion(-) diff --git a/sources/knowledge_areas.dat b/sources/knowledge_areas.dat index edc0efe..f3566a8 100644 --- a/sources/knowledge_areas.dat +++ b/sources/knowledge_areas.dat @@ -24,7 +24,6 @@ F Functions udl y y n User-Defined Literals C User-Defined Types (Classes) ? ? ? ? Special Member Functions - copy-elision n y y Copy Elision and Implicit Moving (e.g., RVO and NRVO, etc.) ? ? ? ? Types ? ? ? ? Conversions ? ? ? ? Constructors and Destructors From 9d28463c06b06850f504369412f7adf43f121732 Mon Sep 17 00:00:00 2001 From: Michael Adams Date: Tue, 7 Sep 2021 22:04:35 -0700 Subject: [PATCH 64/64] Moved some files around in order to facilitate easier merging. --- tools/{old/tools => }/pytest.ini | 0 tools/{old/tools => }/requirements.txt | 0 tools/{old/tools => }/tests/TEST_INPUTS/fix_wrong_sections.md | 0 tools/{old/tools => }/tests/TEST_INPUTS/missing_sections.md | 0 tools/{old/tools => }/tests/TEST_INPUTS/test_skeleton.md | 0 .../tools => }/tests/TEST_INPUTS/user_content_heading_topic.md | 0 tools/{old/tools => }/tests/topic_updater_test.py | 0 7 files changed, 0 insertions(+), 0 deletions(-) rename tools/{old/tools => }/pytest.ini (100%) rename tools/{old/tools => }/requirements.txt (100%) rename tools/{old/tools => }/tests/TEST_INPUTS/fix_wrong_sections.md (100%) rename tools/{old/tools => }/tests/TEST_INPUTS/missing_sections.md (100%) rename tools/{old/tools => }/tests/TEST_INPUTS/test_skeleton.md (100%) rename tools/{old/tools => }/tests/TEST_INPUTS/user_content_heading_topic.md (100%) rename tools/{old/tools => }/tests/topic_updater_test.py (100%) diff --git a/tools/old/tools/pytest.ini b/tools/pytest.ini similarity index 100% rename from tools/old/tools/pytest.ini rename to tools/pytest.ini diff --git a/tools/old/tools/requirements.txt b/tools/requirements.txt similarity index 100% rename from tools/old/tools/requirements.txt rename to tools/requirements.txt diff --git a/tools/old/tools/tests/TEST_INPUTS/fix_wrong_sections.md b/tools/tests/TEST_INPUTS/fix_wrong_sections.md similarity index 100% rename from tools/old/tools/tests/TEST_INPUTS/fix_wrong_sections.md rename to tools/tests/TEST_INPUTS/fix_wrong_sections.md diff --git a/tools/old/tools/tests/TEST_INPUTS/missing_sections.md b/tools/tests/TEST_INPUTS/missing_sections.md similarity index 100% rename from tools/old/tools/tests/TEST_INPUTS/missing_sections.md rename to tools/tests/TEST_INPUTS/missing_sections.md diff --git a/tools/old/tools/tests/TEST_INPUTS/test_skeleton.md b/tools/tests/TEST_INPUTS/test_skeleton.md similarity index 100% rename from tools/old/tools/tests/TEST_INPUTS/test_skeleton.md rename to tools/tests/TEST_INPUTS/test_skeleton.md diff --git a/tools/old/tools/tests/TEST_INPUTS/user_content_heading_topic.md b/tools/tests/TEST_INPUTS/user_content_heading_topic.md similarity index 100% rename from tools/old/tools/tests/TEST_INPUTS/user_content_heading_topic.md rename to tools/tests/TEST_INPUTS/user_content_heading_topic.md diff --git a/tools/old/tools/tests/topic_updater_test.py b/tools/tests/topic_updater_test.py similarity index 100% rename from tools/old/tools/tests/topic_updater_test.py rename to tools/tests/topic_updater_test.py