Skip to content

Commit cdab539

Browse files
mdadamsvulder
mdadams
authored and
vulder
committed
Merge of work to build and deploy teaching guidelines document in multiple formats (#70)
* Added a new attempt at a revised "Guidelines for Teaching C++" document. * Added some information to the README document and made some corrections to the main document. * Document: Revised some of the information in the introductory sections. Added the information for the topic on static_assert. Fixed a few places in the document that were using incorrect terminology. Changed some of the symbols used in the module/topic tables. * Fixed some labelling-related issues in the document. * Made a few minor wording changes to the section on contributing. * Added two WG21 papers to the references section. * Added a logo to the document title and made a few other minor changes to the document. Performed some clean up on the makefile and added a few comments to it as well. Added some comments and better error messages to the document build script. Made numerous improvements to the document deploy script (e.g., added usage information and added a few comments). Added some comments to the GitHub workflow files. * Added some examples to the usage information for the document build and deploy scripts. Fixed a bug in the deploy script introduced by earlier changes. * Changed the document deploy script so that it no longer creates a top-level index.html file in the target repository. * Changed the target of the symlink for the latest version of the document in the document deploy script. * Removed an outdated link from the document. * Made a few improvements to the document deploy script. * Added the creation of a top-level index.html file for the GitHub Pages site. * Added the deployment of built document to the same repository. * Corrected some typos in a workflow file. * Fixed a bug in the deploy script associated with the handling of the case that the gh-pages branch does not yet exist. * Fix a bug in the deploy script. * Fix bug in deploy script. * Testing. * Testing. * Testing. * Testing. * Made changes to file layout. * More reorganizing. * Testing. * Testing. * Revised README. * Replaced HTML markup for tables with the corresponding Markdown markup in several document source files. * Added the missing license text. * Pulled contributor names from the Git repository revision history. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Testing. * Add missing files. * Added a description of the repository organization to the top-level README document. * Made some minor editorial changes to the top-level README. * Fixed a typo in the README. * Fixed wording/spelling in README document. * Added preliminary support for the use of an access token for authentication during deployment. * Fixed a typo in the deploy script. * Made more changes to the deploy script. * Made another change to the deploy script. * Made some editorial changes to the GitHub Actions workflow files. * Commented out some obsolete/unused lines in the release workflow file. * Added mention of some new links in the teaching guidelines document. * Added mention of a new link in the teaching guidelines document. * Removed the copy elision module that is neither complete nor approved for inclusion in the guidelines document. * Removed an obsolete entry in the knowledge areas file. * Moved some files around in order to facilitate easier merging.
1 parent b3c532e commit cdab539

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+4988
-176
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# This action is used to perform a test build of the document that includes
2+
# performing spell checking.
3+
4+
name: ci
5+
6+
on: [push]
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v2
13+
############################################################
14+
- name: Prepare to build the document.
15+
shell: bash
16+
run: tools/build/prebuild
17+
############################################################
18+
- name: Build the document.
19+
shell: bash
20+
run: |
21+
tools/build/build \
22+
-d ${{runner.temp}}/output \
23+
-z ${{github.ref}} \
24+
-s
25+
############################################################

‎.github/workflows/release.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# This is an action that builds the document and deploys the build document
2+
# to its associated GitHub pages site.
3+
4+
name: release
5+
6+
on:
7+
push:
8+
tags:
9+
- 'v*.*.*'
10+
11+
jobs:
12+
build:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v2
16+
with:
17+
fetch-depth: 0
18+
############################################################
19+
- name: Prepare to build the document.
20+
shell: bash
21+
run: tools/build/prebuild
22+
############################################################
23+
# The following builds the document in multiple formats for deployment.
24+
- name: Build the document.
25+
shell: bash
26+
run: |
27+
tools/build/build \
28+
-d ${{runner.temp}}/output \
29+
-z ${{github.ref}}
30+
############################################################
31+
# The following deploys to a different branch of the same repository
32+
# using an access token for authentication.
33+
# Note: It is recommended that this approach not be used.
34+
#- name: Deploy the built document to a GitHub Pages branch.
35+
# env:
36+
# DEPLOY_TOKEN: ${{secrets.DEPLOY_TOKEN}}
37+
# shell: bash
38+
# run: |
39+
# tools/build/deploy \
40+
# -f \
41+
# -m token \
42+
# -t ${{runner.temp}}/deploy_tmp \
43+
# -i ${{runner.temp}}/output \
44+
# -r mdadams/SG20 \
45+
# -b gh-pages \
46+
# -z ${{github.ref}}
47+
############################################################
48+
# The following deploys to a different branch of the same repository
49+
# using a deploy (i.e., SSH) key for authentication.
50+
- name: Deploy the built document to a GitHub Pages branch.
51+
env:
52+
DEPLOY_KEY: ${{secrets.DEPLOY_KEY}}
53+
shell: bash
54+
run: |
55+
tools/build/deploy \
56+
-f \
57+
-m key \
58+
-t ${{runner.temp}}/deploy_tmp \
59+
-i ${{runner.temp}}/output \
60+
-r mdadams/SG20 \
61+
-b gh-pages \
62+
-z ${{github.ref}}
63+
############################################################
64+
# The following deploys to a branch of a different repository
65+
# using a deploy (i.e., SSH) key authentication.
66+
- name: Deploy the built document to a GitHub Pages branch.
67+
env:
68+
DEPLOY_KEY: ${{secrets.ALT_DEPLOY_KEY}}
69+
shell: bash
70+
run: |
71+
tools/build/deploy \
72+
-f \
73+
-m key \
74+
-t ${{runner.temp}}/deploy_tmp_2 \
75+
-i ${{runner.temp}}/output \
76+
-r mdadams/sg20_guidelines_for_teaching_cpp \
77+
-b gh-pages \
78+
-z ${{github.ref}}
79+
############################################################

‎LICENSE.txt‎

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

‎Makefile‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
SUBDIRS = \
2+
sources \
3+
4+
.PHONY: all world clean install
5+
all world clean install:
6+
for subdir in $(SUBDIRS); do \
7+
( cd $$subdir && make -$(MAKEFLAGS) $@ ) || exit 1; \
8+
done

‎README.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
Guidelines for Teaching C++
2+
===========================
3+
4+
This repository contains the source for the document:
5+
6+
- Guidelines for Teaching C++
7+
8+
When the repository is tagged, this document is automatically built
9+
and made available via GitHub Pages at:
10+
11+
- <https://cplusplus.github.io/SG20/latest> (soon)
12+
- <https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/latest>
13+
(currently)
14+
- <https://mdadams.github.io/SG20/latest> (currently)
15+
16+
# Prerequisites for Building the Document
17+
18+
The following software is needed to build the document:
19+
20+
- pandoc
21+
- aspell
22+
- various basic POSIX utilities, including (amongst others):
23+
- make
24+
- awk
25+
- sed
26+
27+
If one would like to build the document in PDF format, the
28+
following software is also required:
29+
30+
- LaTex
31+
32+
# Building the Document
33+
34+
To build the document, simply type:
35+
36+
1. make clean
37+
2. make all
38+
3. make install
39+
40+
(Strictly speaking, step 2 can be skipped, since the install target
41+
has a dependency on the all target.)
42+
43+
The above commands will build the document in several formats:
44+
45+
- HTML format as a single HTML document:
46+
install/html/index.html
47+
- EPUB format:
48+
guidelines.epub
49+
- HTML format split across multiple HTML documents:
50+
install/html_split/index.html
51+
52+
A make target called world is also defined. Building this target (i.e.,
53+
"make world") will generate the document in additional formats, including
54+
PDF format, but requires that LaTeX be installed.
55+
56+
The build process performs spell checking.
57+
The build will fail if any spelling errors are detected.
58+
59+
# Spell Checking
60+
61+
Words that are flagged as having spelling errors can be classified
62+
into two categories:
63+
64+
1. valid English words (such as technical terms) that are not in
65+
the spell checker's dictionary
66+
2. words that are not really "proper" English words but are also not
67+
really errors either (e.g., people's names)
68+
69+
Words in category 1 should be added to the file
70+
config/spellcheck/wordlist.
71+
Words in category 2 should be added to the file
72+
config/spellcheck/ignored_words.txt
73+
74+
# Repository Organization
75+
76+
The files in this repository are organized into directories as follows:
77+
78+
- config:
79+
This directory contains configuration files that control various
80+
aspects of how the guidelines document is built.
81+
- pandoc_templates:
82+
This directory contains document templates used by pandoc during
83+
the document build process.
84+
- spellcheck:
85+
The directory contains lists of additional words and ignorable errors
86+
for spell checking.
87+
- sources:
88+
This directory hierarchy contains the source files for the document.
89+
- css:
90+
This directory contains CSS files used by the document when built
91+
in HTML format.
92+
- images:
93+
This directory contains images used in the document.
94+
- modules:
95+
The directory hierarchy contains the information for individual modules
96+
and topics. There is one directory per module and one file per topic.
97+
- tools:
98+
The directory hierarchy contains various scripts and other tools used for
99+
building and deploying the document to GitHub pages site.
100+
- build:
101+
This directory contains scripts used for building and deploying the
102+
document.
103+
- old:
104+
This directory hierachy needs to be reorganized. This directory
105+
should probably be renamed and its contents possibly reorganized
106+
or relocated elsewhere.
107+
- tools
108+
- tests
109+
- TEST_INPUTS
110+
- pandoc_filters:
111+
This directory contains various filters needed for pandoc. These
112+
filters do things such as allow markdown-aware spell checking.

‎TODO.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Some topics listed on GitHub are unclear as to their meaning.
2+
e.g. Heterogeneous Compiling
3+
[Is "Heterogeneous Computing" intended or "Cross Compiling"?]
4+
There are others too.
5+
6+
More thought is needed on naming conventions for labels for
7+
knowledge areas/units.

0 commit comments

Comments
 (0)