C++ Logo

sg20

Advanced search

[SG20] Revised Teaching-Guidelines Document Prototype (With GitHub Pages Workflow) for Discussion

From: Michael Adams <mdadams_at_[hidden]>
Date: Fri, 23 Apr 2021 10:17:58 -0700 (PDT)
Hi JC,

Based on the feedback that I received in the last SG20 meeting, I have
made major revisions to the teaching-guidelines document prototype that
I partly presented in that meeting. I would ask that you please add a
discussion of this revised prototype as an agenda item for the upcoming
SG20 meeting.

The latest version of the teaching-guidelines document itself is available
via the GitHub Pages site URL:

      https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/latest/

The latest version of the document should include all of the topics
that have been merged to master in the official SG20 repository to date
(with static_assert being the most recent). Links to the document
in other formats, such as EPUB, are provided at the beginning of this
web document.

The source and scripts that generated the above online document can be
found in the mdadams-v2 branch of the following repository (which is
forked from the official SG20 repository):

      https://github.com/mdadams/SG20.git

I have tried my best to incorporate feedback that I received from others.
I brought the document more into alignment with P1725 and P2193, in order
to address comments from the previous SG20 meeting. Please note that
none of the documents that I was referred to in the last SG20 meeting
appear to have any explicit statement of how different versions of
the C++ standard are to be addressed. So, I added a note in the
teaching-guidelines document saying that module/topic content is to be
presented respect to the most recently ratified version of the C++
standard. I also fixed some spelling errors in the topic sections
taken from the SG20 repository, found by the automated spell checking
that I added.

In addition to the above, I have configured the following automatic
workflows:

      - each push to the repository ensures that the document can be
        successfully built in several formats and performs a spell check
        as well (where a spell check failure intentionally causes a
        build failure)

      - when the repository is tagged with a tag of the form "vX.Y.Z",
        the document is built from the repository and pushed to a separate
        GitHub pages site; the document is made available from this site
        in three formats:

          1) HTML format as a single HTML document;

          2) EPUB format; and

          3) HTML format split across multiple HTML documents

        [formats 1 and 2 currently look reasonably aesthetically pleasing,
        at least to me, as rendered in the web browsers that I have tried;
        format 3 needs more work though (work is ongoing)]

All releases of the teaching-guidelines document are maintained on the
GitHub pages site (not just the most recent release). In general,
release $VERSION of the document (where $VERSION corresponds to a Git tag)
is available from the URL:

      https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/$VERSION

For example, the older release v0.1.4 of the document is available from:

      https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/v0.1.4/

Regards,
Michael

---
Michael Adams, Associate Professor, Ph.D., P.Eng., IEEE Senior Member
Dept. of Electrical and Computer Engineering, University of Victoria
PO Box 1700 STN CSC, Victoria, BC, V8W 2Y2, CANADA
E-mail: mdadams_at_[hidden], Web: https://www.ece.uvic.ca/~mdadams

Received on 2021-04-23 12:18:03