Course template updates

CHANGELOG.md

@@ -9,6 +9,10 @@ Instructions: Add a subsection under `[Unreleased]` for additions, fixes, change
 
 ## [Unreleased]
 
+### Changed
+
+- Improved `course` template and updated readme's for main templates.
+
 ## [2.33.0] - 2025-12-06
 
 Includes updates to core through commit: [1c97959](https://github.com/PreTeXtBook/pretext/commit/1c97959297d51749717f9b34ce5da131c960b92d)

templates/article/README.md

@@ -35,7 +35,7 @@ The most important thing to remember when authoring in a codespace is that you a
 
 We have tried to keep the codespace small (so it starts up quickly and doesn't eat through your monthly storage allotment), so we do not include a full TeXLive distribution.  We have tried to include most packages and fonts you are likely to need to generate images using `<latex-image>` elements, and to generate PDF print output.  However, if you run into a situation where the LaTeX gives errors about packages missing (like it cannot find a `mypackage.sty` file), here is what you should do.
 
-1. To quickly resolve the issue yourself, open a terminal (``Ctrl+Shift+` ``) and use the TeXLive Package Manager to install the missing package.  
+1. To quickly resolve the issue yourself, open a terminal (``Ctrl+Shift+` ``) and use the TeXLive Package Manager to install the missing package.
     a. If you know that the package is called `mypackage` then enter the following two lines:
 
     ```bash
@@ -48,12 +48,21 @@ We have tried to keep the codespace small (so it starts up quickly and doesn't e
     tlmgr search --global --all "mypackage.sty"
     ```
 
-2. To ensure that you don't have to repeat this step every time you recreate the codespace, add the package name to the list of installs inside the file `.devcontainer/installLatex.sh` which gets run every time a codespace is created.
-
-3. Better yet, post the name of the missing package to this [GitHub issue](https://github.com/PreTeXtBook/pretext-codespace/issues/21) and we will add it to the devcontainer.  This has the advantage that you will still get updates that other authors submit (if you edit the `installLatex.sh` file, then it won't be updated when you run `pretext update`).
+2. Then please post the name of the missing package to this [GitHub issue](https://github.com/PreTeXtBook/pretext-codespace/issues/21) and we will add it to the devcontainer.  This has the advantage that you will still get updates that other authors submit.  The next time you update PreTeXt, you should get the better version of the devcontainer and everyone else will benefit as well.
 
 ### Troubleshooting: sageplot images
 
-By far the largest space-hog in a PreTeXt authoring environment is SageMath, which is only required if you generate images using sageplots.  By default, SageMath is not installed in a PreTeXt codespace, but it should be easy to install if you need it.  
+By far the largest space-hog in a PreTeXt authoring environment is SageMath, which is only required if you generate images using sageplots.  By default, SageMath is not installed in a PreTeXt codespace, but it should be easy to install if you need it.
+
+Open the file `.devcontainer/devcontainer.json` and edit the line that contains
+
+```
+  "image": "pretextbook/pretext:latest",
+```
+(or perhaps instead of `latest`, you have a version number).  Change this to
+
+```
+  "image": "pretextbook/pretext-full:latest",
+```
 
-Just open the command palette (`Ctrl+Shift+P` of `F1`) and search for "PreTeXt: Install SageMath".  This will also update the `.devcontainer/devcontainer.json` file so that the next time you create a codespace for this project, it should install automatically.
+VS Code should prompt you to rebuild your codespace, which you should do (you do not need to do a "full rebuild" though).  This docker image contains sagemath and you should be able to add sageplots and generate them successfully now.

templates/book/README.md

@@ -36,7 +36,7 @@ The most important thing to remember when authoring in a codespace is that you a
 
 We have tried to keep the codespace small (so it starts up quickly and doesn't eat through your monthly storage allotment), so we do not include a full TeXLive distribution.  We have tried to include most packages and fonts you are likely to need to generate images using `<latex-image>` elements, and to generate PDF print output.  However, if you run into a situation where the LaTeX gives errors about packages missing (like it cannot find a `mypackage.sty` file), here is what you should do.
 
-1. To quickly resolve the issue yourself, open a terminal (``Ctrl+Shift+` ``) and use the TeXLive Package Manager to install the missing package.  
+1. To quickly resolve the issue yourself, open a terminal (``Ctrl+Shift+` ``) and use the TeXLive Package Manager to install the missing package.
     a. If you know that the package is called `mypackage` then enter the following two lines:
 
     ```bash
@@ -49,12 +49,21 @@ We have tried to keep the codespace small (so it starts up quickly and doesn't e
     tlmgr search --global --all "mypackage.sty"
     ```
 
-2. To ensure that you don't have to repeat this step every time you recreate the codespace, add the package name to the list of installs inside the file `.devcontainer/installLatex.sh` which gets run every time a codespace is created.
-
-3. Better yet, post the name of the missing package to this [GitHub issue](https://github.com/PreTeXtBook/pretext-codespace/issues/21) and we will add it to the devcontainer.  This has the advantage that you will still get updates that other authors submit (if you edit the `installLatex.sh` file, then it won't be updated when you run `pretext update`).
+2. Then please post the name of the missing package to this [GitHub issue](https://github.com/PreTeXtBook/pretext-codespace/issues/21) and we will add it to the devcontainer.  This has the advantage that you will still get updates that other authors submit.  The next time you update PreTeXt, you should get the better version of the devcontainer and everyone else will benefit as well.
 
 ### Troubleshooting: sageplot images
 
-By far the largest space-hog in a PreTeXt authoring environment is SageMath, which is only required if you generate images using sageplots.  By default, SageMath is not installed in a PreTeXt codespace, but it should be easy to install if you need it.  
+By far the largest space-hog in a PreTeXt authoring environment is SageMath, which is only required if you generate images using sageplots.  By default, SageMath is not installed in a PreTeXt codespace, but it should be easy to install if you need it.
+
+Open the file `.devcontainer/devcontainer.json` and edit the line that contains
+
+```
+  "image": "pretextbook/pretext:latest",
+```
+(or perhaps instead of `latest`, you have a version number).  Change this to
+
+```
+  "image": "pretextbook/pretext-full:latest",
+```
 
-Just open the command palette (`Ctrl+Shift+P` of `F1`) and search for "PreTeXt: Install SageMath".  This will also update the `.devcontainer/devcontainer.json` file so that the next time you create a codespace for this project, it should install automatically.
+VS Code should prompt you to rebuild your codespace, which you should do (you do not need to do a "full rebuild" though).  This docker image contains sagemath and you should be able to add sageplots and generate them successfully now.

templates/course/README.md

@@ -1,43 +1,56 @@
 # My PreTeXt Course
 
-This README was generated by running `pretext new course`.  You should feel free to edit this to describe your project.  Thanks to Mitch Keller for his contributions to this template.
+This README was generated by running `pretext new course`.  You should feel free to edit this to describe your project.
 
 ## Instructions
 
-Build the entire course with:
+The course template includes a single PreTeXt "book" that contains (as chapters) different course documents you might want to share with students.  What is included is determined by the `main.ptx` file in the `source` folder.  The starts of files for a syllabus, weekly notes, activities (worksheets), handouts, and homework are also included.
+
+You can build the course using
 
 ```bash
-pretext build --deploys
+pretext build course
 ```
 
-and then view it with 
+and view it with
 
 ```bash
-pretext deploy --stage-only
-pretext view -d
+pretext view course
 ```
 
-If you want to build just a single activity, say the "Magic Beans" activity, run:
+Also included is the start of a slide deck.  This is a single file in the `source/slides` folder.  You could use this for all the slides in a course (as a single slideshow), or create separate slideshows.  In that case, you might want to build those separate ones with something like,
 
 ```bash
-pretext build  pdf -i ./source/activities/magic-beans.ptx
+pretext build slides -i source/slides/chapter2.ptx
 ```
 
-This will create a pdf inside the `output/pdfs` directory.
+### Creating a landing page for multiple targets
 
-Another thing to try:
+Build the entire course with:
 
 ```bash
-pretext build scorm -i ./source/activities/magic-beans.ptx
+pretext build --deploys
 ```
 
+This will build both the course "book" and the slide deck.  You can create a landing page with links to each of these automatically with the command,
 
-### How this is done
+```bash
+pretext deploy --stage-only
+```
 
-Look at the source files, in particular `source/acitivies.ptx` and `source/activities/magic-beans.ptx` to see how the activities are included in the main document and can also build on their own.
+and then view the results with,
 
-The use of `xpointer="/1/1/1"` is a little mysterious; we could have also used `xpoint="Activity-magic-beans"` to refer to the activity by its `xml:id`, although this would require us changing that for each included activity.
+```bash
+pretext view -d
+```
 
+If you then run
+
+```bash
+pretext deploy
+```
+
+everything will be pushed to github pages.
 
 ---
 
@@ -61,7 +74,7 @@ The most important thing to remember when authoring in a codespace is that you a
 
 We have tried to keep the codespace small (so it starts up quickly and doesn't eat through your monthly storage allotment), so we do not include a full TeXLive distribution.  We have tried to include most packages and fonts you are likely to need to generate images using `<latex-image>` elements, and to generate PDF print output.  However, if you run into a situation where the LaTeX gives errors about packages missing (like it cannot find a `mypackage.sty` file), here is what you should do.
 
-1. To quickly resolve the issue yourself, open a terminal (``Ctrl+Shift+` ``) and use the TeXLive Package Manager to install the missing package.  
+1. To quickly resolve the issue yourself, open a terminal (``Ctrl+Shift+` ``) and use the TeXLive Package Manager to install the missing package.
     a. If you know that the package is called `mypackage` then enter the following two lines:
 
     ```bash
@@ -74,12 +87,21 @@ We have tried to keep the codespace small (so it starts up quickly and doesn't e
     tlmgr search --global --all "mypackage.sty"
     ```
 
-2. To ensure that you don't have to repeat this step every time you recreate the codespace, add the package name to the list of installs inside the file `.devcontainer/installLatex.sh` which gets run every time a codespace is created.
-
-3. Better yet, post the name of the missing package to this [GitHub issue](https://github.com/PreTeXtBook/pretext-codespace/issues/21) and we will add it to the devcontainer.  This has the advantage that you will still get updates that other authors submit (if you edit the `installLatex.sh` file, then it won't be updated when you run `pretext update`).
+2. Then please post the name of the missing package to this [GitHub issue](https://github.com/PreTeXtBook/pretext-codespace/issues/21) and we will add it to the devcontainer.  This has the advantage that you will still get updates that other authors submit.  The next time you update PreTeXt, you should get the better version of the devcontainer and everyone else will benefit as well.
 
 ### Troubleshooting: sageplot images
 
-By far the largest space-hog in a PreTeXt authoring environment is SageMath, which is only required if you generate images using sageplots.  By default, SageMath is not installed in a PreTeXt codespace, but it should be easy to install if you need it.  
+By far the largest space-hog in a PreTeXt authoring environment is SageMath, which is only required if you generate images using sageplots.  By default, SageMath is not installed in a PreTeXt codespace, but it should be easy to install if you need it.
+
+Open the file `.devcontainer/devcontainer.json` and edit the line that contains
+
+```
+  "image": "pretextbook/pretext:latest",
+```
+(or perhaps instead of `latest`, you have a version number).  Change this to
+
+```
+  "image": "pretextbook/pretext-full:latest",
+```
 
-Just open the command palette (`Ctrl+Shift+P` of `F1`) and search for "PreTeXt: Install SageMath".  This will also update the `.devcontainer/devcontainer.json` file so that the next time you create a codespace for this project, it should install automatically.
+VS Code should prompt you to rebuild your codespace, which you should do (you do not need to do a "full rebuild" though).  This docker image contains sagemath and you should be able to add sageplots and generate them successfully now.

templates/course/project.ptx

@@ -1,32 +1,32 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- This file, the project manifest, provides the overall configuration for your PreTeXt project. To edit the content of your document, open `source/main.ptx`. See https://pretextbook.org/doc/guide/html/processing-CLI.html#cli-project-manifest. -->
+
 <project ptx-version="2">
   <targets>
-    <target name="syllabus-web" source="syllabus.ptx" format="html"
-            publication="publication-syllabus.ptx" deploy-dir="syllabus" />
-    <target name="syllabus-canvas" source="syllabus.ptx" format="html"
-            compression="scorm" publication="publication_scorm_syllabus.ptx"
-            output-filename="syllabus.zip" />
-    <target name="syllabus-print" source="syllabus.ptx" format="pdf"
-            output-filename="syllabus.pdf" publication="publication-syllabus.ptx" />
+    <!-- Main course for html or pdf -->
+    <target name="web" source="main.ptx" format="html"
+            publication="publication.ptx" deploy-dir="course" />
+    <target name="print" source="main.ptx" format="pdf"
+            output-filename="course.pdf" publication="publication.ptx" />
+
+    <target name="slides" source="slides/slides.ptx" format="revealjs"
+            publication="publication-slides.ptx" deploy-dir="slides"
+            output-filename="index.html"/>
+    <target name="slides-annotated" source="slides/slides.ptx" format="revealjs"
+            publication="publication-slides-annotated.ptx" deploy-dir="slides-annotated"
+            output-filename="index.html"/>
 
-    <target name="activities-web" format="html" source="activities.ptx"
-            publication="publication.ptx" deploy-dir="worksheets" />
-    <target name="activities-print" format="pdf" source="activities.ptx"
-            output-filename="activities.pdf" publication="publication.ptx" />
 
-    <target name="notes-web" format="html" source="notes.ptx"
-            publication="publication.ptx" deploy-dir="notes" />
-    <target name="notes-print" format="pdf" source="notes.ptx"
-            publication="publication.ptx" output-filename="notes.pdf"/>
 
-  <!-- The following targets are used to create stand-alone documents, -->
-  <!-- either scorm archives or pdfs. Run with `pretext build scorm -i source/[filename.ptx]`-->
-    <target name="scorm" standalone="yes" format="html" compression="scorm"
-            output-dir="scorms" publication="publication_standalone.ptx"
-            />
-    <target name="pdf" standalone="yes" format="pdf"
-            output-dir="pdfs" publication="publication_standalone.ptx" />
+  <!-- The following targets are used to create stand-alone documents, which could be additional slide decks, pdfs, or SCORM archives. Run with `pretext build slides -i source/slides/[filename.ptx]`, for example. -->
+  <target name="pdf" standalone="yes" format="pdf"
+          output-dir="pdfs" publication="publication_standalone.ptx"/>
+  <target name="slides" standalone="yes" format="revealjs"
+          output-dir="slides" publication="publication-slides.ptx"/>
+  <target name="slides-annotated" standalone="yes" format="revealjs"
+          output-dir="slides" publication="publication-slides-annotated.ptx"/>
+  <target name="scorm" standalone="yes" format="html" compression="scorm"
+          output-dir="scorms" publication="publication_standalone.ptx"/>
   </targets>
 </project>
 
@@ -89,4 +89,4 @@
           />
         </targets>
 </project>
--->
+-->

templates/course/publication/publication-slides-annotated.ptx

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<!-- This is for annotated versions of slides. -->
+<!-- Adapted from work of Mitch Keller -->
+<publication>
+    <source>
+        <directories external="../assets" generated="../generated-assets"/>
+        <!-- add component="a" to parts of the slides that should show up in the "annotated" version.  The next line makes sure this is included. -->
+        <version include="a" />
+    </source>
+
+    <revealjs>
+        <appearance theme="white"/>
+        <!-- these are "resources" defaults, but best for a sample -->
+        <!-- @minified is not even necessary with @host = 'cdn'    -->
+        <resources host="cdn"/>
+        <!-- display="yes" is the default so we can see arrows          -->
+        <!-- tutorial="yes" is the default                              -->
+        <!-- layout="bottom-right" is the default, "edges" is an option -->
+        <!-- backarrows="faded" is the default,                         -->
+        <!--     "hidden and "visible" are options                      -->
+        <controls display="yes" tutorial="yes" layout="bottom-right" backarrows="faded"/>
+        <!-- mode="default" is horizontal/vertical two-level navigation              -->
+        <!--   mode="grid" allows direct movement between adjacent vertical segments -->
+        <!--   mode="linear" is more traditional left/right movement for all slides  -->
+        <navigation mode="default"/>
+    </revealjs>
+
+</publication>

templates/course/publication/publication-slides.ptx

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<publication>
+    <source>
+        <directories external="../assets" generated="../generated-assets"/>
+        <!-- add component="b" to parts of the slides that should show up in the "blank" (unannotated) version.  The next line makes sure this is included -->
+        <version include="b" />
+    </source>
+    <common>
+        <fillin mathstyle="underline" />
+    </common>
+    <revealjs>
+        <appearance theme="white"/>
+        <!-- these are "resources" defaults, but best for a sample -->
+        <!-- @minified is not even necessary with @host = 'cdn'    -->
+        <resources host="cdn"/>
+        <!-- display="yes" is the default so we can see arrows          -->
+        <!-- tutorial="yes" is the default                              -->
+        <!-- layout="bottom-right" is the default, "edges" is an option -->
+        <!-- backarrows="faded" is the default,                         -->
+        <!--     "hidden and "visible" are options                      -->
+        <controls display="yes" tutorial="yes" layout="bottom-right" backarrows="faded"/>
+        <!-- mode="default" is horizontal/vertical two-level navigation              -->
+        <!--   mode="grid" allows direct movement between adjacent vertical segments -->
+        <!--   mode="linear" is more traditional left/right movement for all slides  -->
+        <navigation mode="default"/>
+    </revealjs>
+</publication>