latex/latex-skript
5
0
Fork 0
Code Issues 2 Pull Requests Releases 2 Wiki Activity

Update README

Browse Source
This commit is contained in:
Knoch 2022-01-10 17:14:52 +01:00
parent 6ecf6267bd
commit ad8139d623
1 changed files with 43 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
README.md
View File

@ -10,7 +10,7 @@ This script introduces the most fundamental LaTeX mechanisms to get learners sta
* formatting paragraphs * formatting paragraphs
* lists * lists
* maths and formulas * maths and formulas
* sourcecode listings * source code listings (`minted` + `listings`)
* graphics * graphics
* tables * tables
* footnotes * footnotes
@ -19,17 +19,40 @@ This script introduces the most fundamental LaTeX mechanisms to get learners sta
Most chapters contain exercises to be performed within the script itself, practically teaching the aspects that are introduced by the text. Most chapters contain exercises to be performed within the script itself, practically teaching the aspects that are introduced by the text.
## Requirements ## Getting started
Compiling the script requires a working [LaTeX installation](https://tug.org/texlive/). ### For beginners
For sourcecode listings, we are using [Pygments](https://pygments.org/) and [Python3](https://www.python.org/). A PDF version of the script can be found [in the “releases” section](https://github.com/fs-wiai/latex-script/releases). It will give you an overview of how to approach any, but especially this LaTeX project. For this, have a look at the “First steps with LaTeX” section.
The Makefile comes in handy for compiling the different versions of the script (see usage section).
For learners, we recommend using [TeXstudio](https://www.texstudio.org/) to compile the script. **Optionally**, the `minted` package can be used for source code listings. This requires some additional configuration (including the installation of [Python3](https://www.python.org/)). Please refer to the chapter on “Source code listings” in the aforementioned PDF file.
### Command line usage
The project can be compiled by running a LaTeX compiler on `main.tex`. A simple command would be:
```sh
$ pdflatex main.tex
```
Run the command twice to generate the table of contents and other registers. Once the literature tasks are being worked on, compilation requires an additional call to BibTeX:
```sh
$ pdflatex main.tex
$ bibtex main.aux
$ pdflatex main.tex
$ pdflatex main.tex
```
If you decide to use the optional `minted` package (see section above), don't forget to add the `--shell-escape` flag:
```sh
$ pdflatex --shell-escape main.tex
```
## Project Structure ## Project Structure
``` ```
latex-skript/ latex-script/
├── commands.tex ├── commands.tex
├── compile_listings ├── compile_listings
├── compile_tasks ├── compile_tasks
@ -53,33 +76,31 @@ latex-skript/
├── Makefile ├── Makefile
├── praeamble.tex ├── praeamble.tex
├── public ├── public
├── setup.tex
└── README.md └── README.md
``` ```
## Relevant files for learners
* **`main.tex`** is the entry point. It includes the preamble (`preamble.tex`), our custom commands (`commands.tex`) as well as all sections. * **`main.tex`** is the entry point. It includes the preamble (`preamble.tex`), our custom commands (`commands.tex`) as well as all sections.
* **`content`** comprises the individual chapters of this script. * **`content`** comprises the individual chapters of this script.
* Most chapters include a task that can be found in the **`exercises`** folder. * Most chapters include a task that can be found in the **`exercises`** folder.
* **`public`** is the folder where all packed-up versions of the script are moved to, once they have been created using the `Makefile` and the command `make publication`. There are two zip archives of this repository (one containing only the exercises and one with solutions included) as well as three PDF versions (one with the content only, one with exercises, and one with exercises and solutions).
* `compile_listings` and `compile_commands` are two **utility bash scripts**. They produce a rendered and cropped PDF version of all `.tex` files within the `listings`/`exercises` folders and their sub folders. Rendered listings remain in `listings` whereas tasks are moved to the **`graphics`** folder afterwards. The compiled tasks are necessary for students who receive the project archive, but should not be given the sourcecode of tasks, e.g., if an exercise demands them to code up a table based on a pre-coded example.
## Usage Please don't feel overwhelmed by the amount of files in this repository. You will get to know the most important parts of the project step by step by [following the script](https://github.com/fs-wiai/latex-script/releases) or our workshop. What's more, by using this larger projects you get accustomed to the complexity of real LaTeX projects – bachelor's/master's theses and the like.
**For beginners**: A PDF version of the script can be found in the “releases” section. It will give you an overview of how to use any LaTeX project. For this, have a look at the “Erste Schritte mit LaTeX” section. ## Further information for maintainers
**Commandline usage**: The project can be compiled by running a LaTeX compiler on `main.tex`. Note that we make (heavy) use of the Pygments package, which requires additional installation (see section above) and a flag (`--shell-escape`) that has to be passed to the compiler. To configure TeXstudio with Pygments, see the chapter “Quelltext-Listings” (especially “10.2 – Compilerbefehl ändern”) in the script. A simple command would be: ### Listings mode
**`setup.tex`** is used to configure which package to use for source code listings. All listings in the script are set using custom commands that can internally switch between the `listings` and the `minted` package.
```sh **`listings-mode.tex`** is the file that determines the listings mode. If this file is non-existent or contains the line `\newcommand\listingsmode{default}`, `listings` is used. `\newcommand\listingsmode{minted}` switches it to `minted`. We decided to add this abstraction to deal with learners having trouble to install Pygments on their machine.
$ pdflatex --shell-escape main.tex
```
Run the command twice to generate the table of contents and other registers. Once the literature tasks are being worked on, compilation requires an additional call to BibTeX: ### Including rendered images of source code
**`compile_listings`** and **`compile_commands`** are two utility bash scripts. They produce a rendered and cropped PDF version of all `.tex` files within the `listings`/`exercises` folders and their sub folders. Rendered listings remain in `listings` whereas exercise renderings are moved to the **`graphics`** folder afterwards.
```sh The compiled tasks are necessary for students who receive the project archive, but should not be given the source code of tasks, e. g., if an exercise demands them to code up a table based on a pre-coded example.
$ pdflatex --shell-escape main.tex
$ bibtex main.aux ### Publishing the script
$ pdflatex --shell-escape main.tex **`public`** is the folder where all packed-up versions of the script are moved to, once they have been created using the `Makefile` and the command `make publication`. There are two zip archives of this repository (one containing only the exercises and one with solutions included) as well as three PDF versions (one with the content only, one with exercises, and one with exercises and solutions).
$ pdflatex --shell-escape main.tex
```
## Contributing ## Contributing