# My PreTeXt Course This README was generated by running `pretext new course`. You should feel free to edit this to describe your project. ## Instructions 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 course ``` and view it with ```bash pretext view course ``` 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 slides -i source/slides/chapter2.ptx ``` In either case, you will need to uncomment the "slide" targets inside `project.ptx`. ### Creating a landing page for multiple targets Build the entire course with: ```bash pretext build --deploys ``` This will build the course "book" (and the slide deck if you uncomment that target in `project.ptx`). You can create a landing page with links to each of these automatically with the command, ```bash pretext deploy --stage-only ``` and then view the results with, ```bash pretext view -d ``` If you then run ```bash pretext deploy ``` everything will be pushed to github pages. --- Below you will find some advice for working with PreTeXt, including help with using the [PreTeXt Codespace](https://github.com/PreTeXtBook/pretext-codespace) online editor through GitHub if you don't want to install the required software on your own computer. ## Learning PreTeXt See the [PreTeXt documentation](https://pretextbook.org/documentation.html) for links to a variety of resources. We also recommend browsing through the [annotated sample article](https://pretextbook.org/examples/sample-article/annotated) and [annotated sample book](https://pretextbook.org/examples/sample-book/annotated/) if you want to find examples and see the PreTeXt source for those examples quickly. ## Using GitHub Codespaces GitHub Codespaces are a way to set up your whole authoring system entirely in your browser. In case you are not already reading this inside a codespace, you can create one specifically designed for authoring in PreTeXt by using [this template](https://github.com/PreTeXtBook/pretext-codespace). ### Important: how to save your files The most important thing to remember when authoring in a codespace is that you are making all your edits on a *virtual machine* off in some remote server farm. This means there is an extra step to save your files. You can save files in the editor (in your browser), but this just saves them to that virtual machine. To make sure you can access these files, even if the virtual machine goes away, you need to sync them to github.com. This is done by *committing* your changes and then *pushing* those commits (or "syncing" them). You might see a warning when you restart your codespace that you have "uncommitted changes" -- make sure you commit them when you are done working. ### Troubleshooting: Latex-images and pdfs 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 `` 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. a. If you know that the package is called `mypackage` then enter the following two lines: ```bash tlmgr install mypackage tlmgr path add ``` b. If you don't know the name of the package, but know it should contain `mypackage.sty`, then you can search using ```bash tlmgr search --global --all "mypackage.sty" ``` 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. 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", ``` 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.