Merge pull request #27 from yax-lakam-tuun/26-polish-before-making-re…

…pository-public

[#26] Polish before making repository public

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

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.

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"]
+CMD ["pwsh", "-Command", "/opt/sources/Compile-Document.ps1 -DocumentName \"Maya Hieroglyphs - The History of Decipherment\""]

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

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}

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.
 

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 <path/to/file.svg>`.
 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.

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: 
 

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)).