From e585bf4141b1809fdb7a326a631860236a3cf945 Mon Sep 17 00:00:00 2001 From: Sebastian Bauer <75776786+yax-lakam-tuun@users.noreply.github.com> Date: Mon, 24 Apr 2023 10:24:28 +0000 Subject: [PATCH 1/5] [#26] Better default behavior in Docker container and compile script --- Compile-Document.ps1 | 4 ++-- container/Dockerfile | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Compile-Document.ps1 b/Compile-Document.ps1 index cafdadf..ad86436 100644 --- a/Compile-Document.ps1 +++ b/Compile-Document.ps1 @@ -28,7 +28,7 @@ param ( [string] # The TeX file to be compiled. [Parameter(HelpMessage="Enter LaTeX file to compile.")] - $TexFile = "main.tex", + $TexFile = "$(Resolve-Path -Path $PSScriptRoot)/main.tex", [string] # The path to the TeX source files. Usually the root of a TeX project. @@ -38,7 +38,7 @@ param ( [string] # The path to the output directory. The final document will be placed there, too. [Parameter(HelpMessage="Enter path in which output files can be stored.")] - $BuildPath="$((Get-Item $TexFile).Directory)/build", + $BuildPath="$(Resolve-Path -Path $(Get-Item $TexFile).Directory)/build", [string] # The file name of the PDF document. diff --git a/container/Dockerfile b/container/Dockerfile index 0619309..51d2f85 100644 --- a/container/Dockerfile +++ b/container/Dockerfile @@ -41,4 +41,4 @@ USER root # Compile document when container is executed with defaults SHELL [ "pwsh" ] -CMD ["pwsh", "-c", "/opt/sources/Compile-Document.ps1"] \ No newline at end of file +CMD ["pwsh", "-Command", "/opt/sources/Compile-Document.ps1 -DocumentName \"Maya Hieroglyphs - The History of Decipherment\""] \ No newline at end of file From 438c6c3901601e289fa1ab20738a088f286c7356 Mon Sep 17 00:00:00 2001 From: Sebastian Bauer <75776786+yax-lakam-tuun@users.noreply.github.com> Date: Mon, 24 Apr 2023 10:25:07 +0000 Subject: [PATCH 2/5] [#26] Some text improvements --- container/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/container/README.md b/container/README.md index 7c63cd6..2495ac9 100644 --- a/container/README.md +++ b/container/README.md @@ -1,7 +1,7 @@ -# What does it do? +# Docker container A Docker container is a virtual encapsulated environment. -The so-called host which is usually the computer, note-book or similar, creates and runs the Docker +The so-called host which is usually the computer, notebook or similar, creates and runs the Docker containers. Unlike the host system, everything which can be installed and executed remains in the container and cannot alter the configuration of the host in any way. @@ -47,10 +47,11 @@ To run the container, please enter the following line: docker run -v$(pwd)/:/opt/sources maya-hod +It will create a PDF document called `Maya Hieroglyphs - The History of Decipherment.pdf`. In this project, a volume is used to map all files, documents, images etc. into the container. The container works directly with the files on the host. That means, once the git project is cloned locally, the Docker container can interact with the -checked out folder structure and run LaTeX completely independent from the host. +checked out folder structure and run LaTeX completely independent of the host. Everything outside the specified folder (aka volume) cannot be touched (or even be seen) though. # Usage in continuous integration From cd2d589857a395b5c4d2a04788ad414fd5fc70cb Mon Sep 17 00:00:00 2001 From: Sebastian Bauer <75776786+yax-lakam-tuun@users.noreply.github.com> Date: Mon, 24 Apr 2023 10:41:44 +0000 Subject: [PATCH 3/5] [#26] Some text improvements --- documentation/continuous-integration.md | 2 +- documentation/latex.md | 20 ++++++++++---------- documentation/vscode.md | 13 +++++++------ 3 files changed, 18 insertions(+), 17 deletions(-) diff --git a/documentation/continuous-integration.md b/documentation/continuous-integration.md index c48e747..7b2c7c8 100644 --- a/documentation/continuous-integration.md +++ b/documentation/continuous-integration.md @@ -19,7 +19,7 @@ The release version is the long count representation of the document's date (see [Releases](releases.md)). ## Short-lived feature branch -One or more persons work on a branch branched from `main` over a small periods of time, flowing through pull requests including code-review and build automation before "integrating" +One or more persons work on a branch created from `main` over a small period of time, flowing through pull requests including code-review and build automation before "integrating" aka merging into `main`. The `main` branch is protected, so the only way for code to get merged, is via pull requests. diff --git a/documentation/latex.md b/documentation/latex.md index 61ea525..6488c86 100644 --- a/documentation/latex.md +++ b/documentation/latex.md @@ -26,7 +26,7 @@ See the [project site of LaTeX](https://www.latex-project.org//) for more inform There are many guides out there which explain in detail how to install LaTeX on your system. LaTeX is usually shipped in so-called distributions. MikTex is one of them and is available for Windows, Linux and macOS. -Fully integrated editors with syntax highlighting and auto completion are also available. +Fully integrated editors with syntax highlighting and autocompletion are also available. (for example TeXstudio or TEXMAKER). Integrated Development Editors(IDE) like [VSCode](vscode.md) can be used in conjunction with LaTeX extensions. Despite the claims above that LaTeX is written in plain text, there are indeed WYSIWYG editors @@ -38,27 +38,27 @@ On how to use Docker containers with LaTeX, please see chapter [Docker](../container/README.md) and [VSCode](vscode.md). # Folder structure -All LateX code is written in files ending with `.tex`. +All LaTeX code is written in files ending with `.tex`. Some code also resides in `.sty` files, but that's just a small portion of LaTeX projects. In less complex projects, it can be sufficient to have all the text in one single tex file. But for bigger projects, it makes sense to split the content to more files. This is useful to keep the context as clean as possible. It also makes editing much easier. -Therefore, this project is also split in many different files. +Therefore, this project is also split in different files. ## Chapters Every chapter resides in a separate sub folder. -The chapter's tex file is named after the chapter's title +The chapter's TeX file is named after the chapter's title (e.g. introduction.tex for the introduction chapter). The advantage is that with this approach every chapter can be compiled separately. -This greatly reduces compilation times and it might be useful to ``publish'' +This greatly reduces compilation times, and it might be useful to ``publish'' single chapters if necessary. Then, the main document [main.tex](../main.tex) combines all chapters by including the according subfolders. If necessary, a chapter can also be split into two or more sub folders. ## Graphics -Images are put into a separate sub folder named 'img' next to the tex file. +Images are put into a separate sub folder named 'img' next to the TeX file. To ensure proper scaling, drawings like hieroglyphs etc. shall be stored as `Scalable Vector Graphics` (SVG). SVGs are not natively supported by LaTeX. @@ -68,7 +68,7 @@ Usage: `ConvertFrom-Svg.ps1 -SvgFiles `. This will produce a PDF named `path/to/file.pdf`. Other images like photos and such should be stored as JPG. Formats like PNGs are discouraged since there pictures take a lot of space and -have to be converted by LaTeX during the compile process which might be very time consuming. +have to be converted by LaTeX during the compile process which might be very time-consuming. ## References This project uses BibLaTeX to organize and display all used sourced and references. @@ -79,9 +79,9 @@ the single file [references.bib](../references.bib). The tex files should have a maximum of 100 characters per line. Exceptions are allowed if and only if the reading of the code would suffer from wrapping the lines (e.g. when using tables with many columns which exceed the limit). -Every sentences starts with new line. +Every sentence starts in a new line. This makes it easier to read the document line by line. -The real line wrapping etc. is done by LaTeX anyways. +The real line wrapping etc. is done by LaTeX anyway. As always, readability should be the most important criterion when writing the text. # Example structure @@ -104,5 +104,5 @@ Here's a short summary: Managed by [Edit-DocumentVersion.ps1](Edit-DocumentVersion.ps1). * [preamble.sty](../preamble.sty): Entry point for everything LaTeX in this project. Includes used LaTeX libraries and defines some settings used in the document. -* [maya.sty](../maya.sty): Library for maya specific LateX command (e.g. hieroglyph commands etc.) +* [maya.sty](../maya.sty): Library for Maya specific LaTeX command (e.g. hieroglyph commands etc.) * [references.bib](../references.bib): All references used by BibLaTeX. \ No newline at end of file diff --git a/documentation/vscode.md b/documentation/vscode.md index e95f7c4..9311c84 100644 --- a/documentation/vscode.md +++ b/documentation/vscode.md @@ -1,8 +1,8 @@ # What is VSCode? VSCode is a source code editor and development tool. It contains a project explorer where all the files and folders are displayed. -VSCode has a text editor with syntax highlighting, auto completion and spell checking. -In addition, it integrates terminals like Bash, ZSH or PowerShell and many more. +VSCode has a text editor with syntax highlighting, autocompletion and spell checking. +In addition, it integrates terminals like Bash, ZSH or PowerShell and many more to run commands, applications and scripts. Please refer to VSCode's website for more information: https://code.visualstudio.com/ @@ -15,10 +15,11 @@ Some useful extensions for this project are: * Previewer for *.md files (e.g. README.md) * LaTeX Workshop by James Yu * Compiling and create PDFs from LaTeX code - * LaTeX auto completion, snippets etc. + * LaTeX autocompletion, snippets etc. * LTeX – LanguageTool grammar/spell checking - * Offline spell and grammar checker for markup languages like LaTeX, BibTex and XHTML - * Caveat: Doesn't work on Apple M1/M2 as this extension doesn't support ARM architectures (yet?) + * Offline spell and grammar checker for markup languages like LaTeX, BibTeX and XHTML + * Caveat: Doesn't work properly on Apple Silicon (M1/M2) as this extension doesn't install + ARM64 version of Java. See issue #25 for the problem description and some possible workaround. Another advantage is its seamlessly integration of Git. This make it easy to author new files, alter existing ones etc. and @@ -36,6 +37,6 @@ It's an easy and isolated way to create a LaTeX environment and everything a con needs in order to compile the final PDF file. This project fully supports Dev Containers. The configuration can be found here [devcontainer.json](../.devcontainer/devcontainer.json). -It configures the Docker container and install some extensions (e.g. for LaTeX) for VSCode. +It configures the Docker container and installs some extensions (e.g. for LaTeX) for VSCode. The same Docker recipe (see [Dockerfile](../container/Dockerfile)) is also used during the continuous integration cycle (see [CI chapter](continuous-integration.md)). From 36b3142f4c3ddcff2630e2ba4f45f1036bc47e0b Mon Sep 17 00:00:00 2001 From: Sebastian Bauer <75776786+yax-lakam-tuun@users.noreply.github.com> Date: Mon, 24 Apr 2023 10:49:31 +0000 Subject: [PATCH 4/5] [#26] Update document version to current date --- CHANGELOG.md | 8 +++++--- document-version.tex | 8 ++++---- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 870d101..e338d4c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,12 @@ # Changelog -## [13.0.10.2.18] - 2022-12-30 +## [13.0.10.8.13] - 2023-04-24 ### Added - Initial project setup -- Support for development in Docker container +- Detailed project documentation - Main LaTeX file +- Chapter 'Introduction' +- Support for development in Docker container - Workflows for continuous integration (CI) and releases - +- Build and maintenance scripts diff --git a/document-version.tex b/document-version.tex index 3e02fe5..4fb728f 100644 --- a/document-version.tex +++ b/document-version.tex @@ -1,4 +1,4 @@ -\newcommand{\documentversiongregoriandate}{2023--01--10\xspace} -\newcommand{\documentversionlongcount}{13.0.10.3.9\xspace} -\newcommand{\documentversiontzolkin}{7 Muluk\xspace} -\newcommand{\documentversionhaab}{2 Muwan\xspace} +\newcommand{\documentversiongregoriandate}{2023--04--24\xspace} +\newcommand{\documentversionlongcount}{13.0.10.8.13\xspace} +\newcommand{\documentversiontzolkin}{7 B'en\xspace} +\newcommand{\documentversionhaab}{1 Wo'\xspace} From 03aad62a8121d1e38e82c84a896c1771753f20fc Mon Sep 17 00:00:00 2001 From: Sebastian Bauer <75776786+yax-lakam-tuun@users.noreply.github.com> Date: Mon, 24 Apr 2023 10:49:39 +0000 Subject: [PATCH 5/5] [#26] Some text improvements --- documentation/releases.md | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/releases.md b/documentation/releases.md index ef72bc4..3cf260d 100644 --- a/documentation/releases.md +++ b/documentation/releases.md @@ -17,6 +17,7 @@ For example, `2022-12-30` would be written as `13.0.10.2.18`. # Changelog The changelog format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to a variant of [Calendar Versioning](https://calver.org/). +It can be found [here](../CHANGELOG.md). Every changelog entry consists of the long count date and its Gregorian equivalent (using ISO format YYYY-MM-DD). Here's an example: