diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md new file mode 100644 index 0000000..423cdae --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -0,0 +1,34 @@ +--- +name: Bug +about: Create a report to help improve the project's infrastructure +title: '' +labels: bug +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. +A bug should describe an infrastructure problem, for example: LaTeX reports an error, the virtualized environment fails etc. + +**To Reproduce** +Steps to reproduce the behavior: +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Environment (please complete the following information):** + - OS: [e.g. iOS] +- Virtualization [e.g. None or Docker] + - LaTeX distribution [e.g. TexLive] + - Document version [e.g. 13.0.10.8.13] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/suggestion.md b/.github/ISSUE_TEMPLATE/suggestion.md new file mode 100644 index 0000000..c0ca30f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/suggestion.md @@ -0,0 +1,26 @@ +--- +name: Suggestion +about: Create a suggestion to improve and enhance the document itself +title: '' +labels: enhancement +assignees: '' + +--- + +**Describe the suggestion** +A short summary what kind of content you'd like to change. + +**Changes in existing chapter ABC** +Either refer to the PDF page number or the chapter you'd like to address. +Cite the original text and add your comments or changes below it. + +**New text, new chapter etc.** +If you'd like to see a new chapter with some more exiting content, great! +Please write down what kind of chapter you think could help improving the project. +Any kind of suggestion, like keywords, notes or even prewritten texts would be of great help here. +Please add also where inside the document the new chapter should be arranged. + +**Scientific sources** +If you can, please add a scientific source like a paper, book or some other kind of source. +This helps to decide how the suggestion can be integrated. +It might be useful to provide the source if necessary so that a reviewer can understand the suggestion and act upon it. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..a37db6e --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,26 @@ +# Description + +Please include a summary of the change and which issue is fixed. +Please also include relevant motivation and context. +List any dependencies that are required for this change. + +Addresses # (issue) + +## Type of change + +Please delete options that are not relevant. + +- [ ] Bug fix (fixes issues with the infrastructure) +- [ ] New content (non-breaking change which adds new content) +- [ ] Breaking change (major refactoring which changes many aspects like whole chapters etc.) +- [ ] This change requires a documentation update +- [ ] Requires changelog update + +# Checklist: + +- [ ] My code follows the style guidelines of this project +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] All external files (like images, photos) are granted to be used and marked accordingly +- [ ] I checked all newly cited sources diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..f95d690 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..94916dc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +# Ways of contribution +Your input is more than welcome! Contributing to this project should be as easy and transparent +as possible, whether it's: + +* Reporting problems +* Discussing the current state of the document +* Suggesting changes +* Proposing new parts, be it chapters, sections or small additions. + +## Developing with GitHub +This project uses GitHub to host code, to track issues and feature requests, utilize pull requests +to ensure reviews and continuous integration. + +## Releases +The document itself will never really be completed as the decipherment is an ongoing +process with no foreseeable ending. +Therefore, there will be a continuous stream of releases once in a while. +Please see chapter [Release](documentation/releases.md) +for some more detailed information. + +## All changes happen through pull requests (PR) +Pull requests are the best way to propose changes to the codebase. +Please see chapter [Continuous Integration](documentation/continuous-integration.md) +for some more detailed information. + +## Any contributions you make will be under the MIT Software License +In short, when you submit changes, your submissions are understood to be under the same +[MIT License](LICENSE) that covers the project. +Feel free to contact the maintainers if that's a concern. + +## Report problems and suggestions +This project use issues to track public problems/suggestions. +Report a problem/suggestion by +[opening a new issue](https://github.com/yax-lakam-tuun/maya-decipherment/issues). +It's that easy! +The project distinguishes between `Bug` and `Suggestion`. + +A bug is some kind of infrastructure problem - not related to the content of the document. +Infrastructure can cover LaTeX specifics or PowerShell problems, automatization or virtualization +issues to name a few. + +A suggestion addresses the content of the document directly. +Please use this type to report mistakes, errors, but also improvements, additions etc. + +## Write issues for suggestions in detail, with background and sources +A good report should include the following things: + +* A quick summary and/or background +* Please refer to the chapter or TeX file you'd like to address. +* Cite the section which should be changed. +* Reason about the changes you'd like to see +* Add a possible suggestion which might include: + * A rephrasing of the section. Maybe you can rewrite some parts to it fits into the document. + * A citation of a paper/book or any other available scientific source which can back up + the suggestion or which could be used to be cited in the document. + * Images or figures for illustration + +People *love* thorough reports. I'm not even kidding. +Please use the `Suggestion` template for this kind of request when creating a new issue. + +## Consistent coding style +The codebase has only a few rules with respect to coding styles. +* Readability (of the source code) is the most important aspect +* 4 spaces for indentation rather than tabs +* 100 characters per line (exceptions permitted if readability would suffer, e.g. large tables) +Please the chapter [LaTeX](documentation/latex.md) for more information. + +## In-depth documentation +Everything documentation is located in the folder [documentation](documentation). + +## License +By contributing, you agree that your contributions will be licensed under its +[MIT License](LICENSE). diff --git a/README.md b/README.md index be31242..c1ea0c7 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# Purpose of this project +# Maya Hieroglyphs - The History of Decipherment +## Purpose of this project The Maya hieroglyphs and the Maya script have been a mystery for centuries. Scholars from all over the world tried to crack the `Mayan Code' since the early 1830s. But it took many decades until scholars made significant progress in the decipherment until to @@ -12,7 +13,7 @@ This project has the goal to collect all the breakthroughs in the decipherment o and illustrate them with examples from all available hieroglyphic sources like the great stela and stone inscriptions, the handwritings on pottery or the Maya books etc. -# Basic idea +## Basic idea The basic idea is to write a document which covers as much as possible from the history of decipherment of the Maya hieroglyphs. Every piece of decipherment is backed up and cited with the corresponding scientific paper, book @@ -29,14 +30,14 @@ educational purposes. But the general guideline (aka rule of thumb) should be, to start from the early stages of decipherment until today. -# Releases +## Releases All releases of the document can be found [here](https://github.com/yax-lakam-tuun/maya-decipherment/releases). Every release contains the source code the document is based on, a changelog with a description of the all changes which have been made and the final document as PDF. Please see the chapter about [releases](documentation/releases.md) for more information. -# Prerequisites +## Prerequisites This project supports all major operating systems: Windows, macOS and Linux. In order to generate the PDF document from the source code, one needs these components installed on the system: @@ -44,7 +45,7 @@ on the system: * PowerShell (see [PowerShell](#PowerShell)) * A platform-independent script language (created by Microsoft) which is used at several places in the code base. - * An install guide (from Microsoft) can be found here: + * An installation guide (from Microsoft) can be found here: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.3 * Optional: Inkscape * Tool which supports SVG(Scalable Vector Graphics) and PDF files @@ -53,22 +54,22 @@ on the system: As an alternative, a virtualized environment using Docker containers is also provided. Please see chapter [Docker](container/Readme.MD) for more information. -## Compiling the document -If the system is setup, open a PowerShell terminal and execute +### Compiling the document +If the system is set up, open a PowerShell terminal and execute the provided PowerShell script [Compile-Document.ps1](Compile-Document.ps1) in the root directory of this project. The generated PDF document can be found in the `build` folder named `main.pdf` (`build/main.pdf`). -# LaTeX +## LaTeX This project is written in LaTeX - a mark-up language which allows creating big scalable documents by writing unformatted text using commands to enrich texts, embed images and tables, cite and reference other sources like papers, books and websites scientifically and so on. That means, a LaTeX environment must be available on your system in order to generally compile -a PDF document from any given LateX source. -For more information on how to setup and use LaTeX, +a PDF document from any given LaTeX source. +For more information on how to set up and use LaTeX, please have a look at chapter [LaTeX](documentation/latex.md). -# PowerShell +## PowerShell All scripts are written in PowerShell. It's a script language created by Microsoft and open-sourced on GitHub: https://github.com/PowerShell/PowerShell. @@ -95,16 +96,16 @@ Some important scripts are: Manages current document version, release version and the next Git tag. See also [document-version.tex](document-version.tex). -# Open source +## Open source This document is open source which means everybody can work with it, improve it and give feedback. The history of decipherment of Maya hieroglyphs should be readable and understandable to anyone interested in this manner. -All texts, images and illustrations are be publicly available, so that the great +All texts, images and illustrations should be publicly available, so that the great process of decipherment can be shared with everyone around the world. The project uses the [MIT license](LICENSE) which basically allows everyone to use the code, the texts etc. the way they want as long as they credit this project. -# How can I send feedback? +## How can I send feedback? If you find problems within the document of any kind or with the infrastructure of this project, please feel free to create issues which address your findings. This will greatly help to improve the project. @@ -115,33 +116,35 @@ You can also get in touch via academia.edu It should be mentioned that it is preferred that every issue should cover a single problem. Create issues for each problem separately. This makes it easier to manage, respond and improve the project incrementally. +For more information about how you can contribute, +please see the [contribution guidelines](CONTRIBUTING.md). -# Source control management +## Source control management To keep track of all changes being applied to the project, it is useful to have a standard tool -which allows to store and manage the folder structure and development of the project. -One way to approach this, is to use an Source Code Management(SCM). +which allows storing and manage the folder structure and development of the project. +One way to approach this, is to use a Source Code Management(SCM). It is a tool which allows to maintain the project and keeps track of all the changes being applied to it. -[Github](github.com) uses GIT for that purpose. +[GitHub](github.com) uses GIT for that purpose. If you want to know more, you can look at some introduction of Atlassian: * https://www.atlassian.com/git/tutorials/source-code-management * https://www.atlassian.com/git/tutorials/what-is-git -# Trunk-based development and continuous integration +## Trunk-based development and continuous integration This project also uses a trunk-based development approach. All changes have to be pushed to the `main` branch in order to be compiled in to the final document. The process which controls and manages that is called `Continuous Integration`. Please see [CI](documentation/continuous-integration.md) chapter for more information. -# IDE +## IDE VSCode is an Integrated Development Editor(IDE). -It is one way to work with this this project. +It is one way to work with this project. However, there are many alternatives out there. Even a basic text editor is enough. If you would like to know more about VSCode, please see the [VSCode](documentation/vscode.md) chapter for more information. -# Docker +## Docker This project utilizes Docker to virtualize the LaTeX environment and everything which is needed to work as a user or author with the project. It is used by the infrastructure of the continuous integration process. diff --git a/documentation/latex.md b/documentation/latex.md index 84df2fd..5671f17 100644 --- a/documentation/latex.md +++ b/documentation/latex.md @@ -22,7 +22,7 @@ It's even possible to define your own commands which enables one to program and extensive tasks and simplifies the way one writes text. See the [project site of LaTeX](https://www.latex-project.org//) for more information. -# Installation +## Installation 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. @@ -32,12 +32,12 @@ Integrated Development Editors(IDE) like [VSCode](vscode.md) can be used in conj Despite the claims above that LaTeX is written in plain text, there are indeed WYSIWYG editors available (for example LyX). -## Docker +### Docker LaTeX can also be used in virtualized environments like Docker containers. On how to use Docker containers with LaTeX, please see chapter [Docker](../container/README.md) and [VSCode](vscode.md). -# Folder structure +## Folder structure 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. @@ -46,7 +46,7 @@ This is useful to keep the context as clean as possible. It also makes editing much easier. Therefore, this project is also split in different files. -## Chapters +### Chapters Every chapter resides in a separate sub folder. The chapter's TeX file is named after the chapter's title (e.g. introduction.tex for the introduction chapter). @@ -57,7 +57,7 @@ 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 +### Graphics 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). @@ -70,12 +70,12 @@ 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. -## References +### References This project uses BibLaTeX to organize and display all used sourced and references. Even though the chapters are split into several files, all referenced are maintained in the single file [references.bib](../references.bib). -# Tex file structure +## Tex file structure 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). @@ -84,7 +84,7 @@ This makes it easier to read the document line by line. 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 +## Example structure Simple tree structure featuring two chapters namely Introduction and reading order with image files: * introduction * introduction.tex @@ -96,7 +96,7 @@ Simple tree structure featuring two chapters namely Introduction and reading ord * img * palenque-tablet.svg -# Files +## Files There are some files like scripts which have a special function inside the project. Here's a short summary: * [document-version.tex](../document-version.tex): diff --git a/documentation/releases.md b/documentation/releases.md index 3cf260d..c2a42b2 100644 --- a/documentation/releases.md +++ b/documentation/releases.md @@ -8,13 +8,13 @@ Therefore, there will be a continuous stream of releases once in a while. This also means that a release is always a snapshot of what has been condensed from the past and the state the decipherment process is currently in. -# Version scheme +## Version scheme The version of the document is usually the date of the release. The release date is converted to a Maya Long Count date using the Martin-Skidmore correlation (584286) and then written out in the standard Long Count notation. For example, `2022-12-30` would be written as `13.0.10.2.18`. -# Changelog +## 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).