yax-lakam-tuun / maya-decipherment Goto Github PK

Github suggests to meet certain community standards.

Although some parts are already in place, there are still missing some including:

• CONTRIBUTING.md: Tell people how to contribute
• Issue templates: How to submit issues
• Pull request template

The project has many aspects which have to be document so that everyone can work with it.
Things which have to be added or improved:

• How to compile the document from scratch?
  • System requirements (Windows, Linux, macOS)
  • Tex center, tex live etc.
  • Describing the script files
• Folder structure
  • Each chapter - a separate folder
  • Integrate into big document
  • img folder
  • Sub/sub document support
• Version scheme
• CI workflow
• LaTeX internals
  • Subfiles
  • Preamble
  • Maya package
• Why open source
  • How to contribute?
  • Submit issues
• Documentation for Docker containers
• VSCode workflow
• File guidelines
  • Characters per line
• Graphics
  • Vector graphics svg

In order to built a big document, it is important to find a way to manage the huge amount of content.
Creating chapters, sections and paragraphs is one thing.
Having images, drawing etc. next to them is big must have.
Just having one file for all the content doesn't make sense here.
Fortunately, LaTeX has to the ability to split the content to different files.
And thanks to the package subfiles, it is even possible to have a folder structure which can be a complex document tree.
It's possible to compile "sub-documents" to avoid the necessity to build everything over and over again.
Creating an infrastructure with subfiles is subject of this ticket.
For now, I'd suggest that every chapter has a separate folder with all content belonging to that chapter in it including images etc.
Images should reside in sub-folder called img to keep the a little distinct from the tex files.

The very first page of the document should be some kind of cover.
It should contain:

• The title "Maya Hieroglyphs - The History of Decipherment"
• Maybe the long count date? (optional)
• The link to the github project
• Some Maya illustration

The numbers are deciphered at an very early stage.
This chapter should describe how this has been achieved.

It should include the following parts:

• Decipherment of dots and bars
• Numbers up to 19

It should contain the following points:

• Very short introduction to Maya civilization and hieroglyphs
• First decipherments and discoveries
• How this document is structured

The chapter 'ritual calendar' addresses the Tzolk'in calendar.

It should include the following:

• Trecena
• Tonalpohualli
  • Origin and naming (Nahuatl)
  • Aztec naming
  • Colonial sources (Bernardino de Sahagun among others)
  • Equivalents in Tzolk'in
• Why is it called Tzolk'in?
• Landa's list of day names and description
• Comparison day names Tonalpohualli and Tzolk'in

The chapter 'Long Count calendar' addresses the Long Count calendar.

It should include the following:

• Maya "vigesimal" system
• Glyphs for K'in, Winal/Winik, Haab'/Tun, Wink Haab'/K'atun, B'aktun...
• Head numerals
• Grand Long Count

Write a chapter describes the Terminology used throughout this work.
The first set of expressions should clarify hieroglyphs and its structural appearance.
The second part should focus on "Decipherment" and its fundamentals.

The chapter should address the following terms:

• Hieroglyphs
  • Grapheme/Sign
  • Glyph
  • Glyph block/Collocation
• Theory in decipherment (Zender 2017), "five pillars"
  • Script typology
  • Corpus
  • Language
  • Cultural context
  • Bilingual, biscript, or similar constraint
• Notation of logograms and syllables
• Hieroglyph catalogs
  • Thompson (T-numbers)
  • Macri/Looper
  • Mayawoerterbuch (classicmayan.org)
• The language of Maya Hieroglyphs
• Mesoamerican chronology
• Analysis of Maya texts
  • Transliteration of Maya signs
  • Transcribing of Maya texts
  • Reconstruction of sounds
  • Morphological analysis
• Phonemes
  • Complex vowels
  • Narrow versus broad transcription

Syntax and grammar of Classic Mayan and Maya languages in general:

• What is Classic Mayan?
• Word order
• Pronouns
• Verbs
• Nouns
• Prepositions
• Classifiers and plural
• Negation
• Relative clauses
• Clause coordination

Right now, README.md is pretty much empty.
Some more information about the project should be added here.

• What's the purpose of this project?
• What's the idea behind it?
• Why is it an open source project?
• Who should contribute?
• Why LaTeX?
• Who owns it?
• How can I contribute?
• The changelog format should be included, too.

Set up continuous integration workflow.
Only merge requests with no errors and warnings may pass to main branch.

Add check stage for generated PDF document:

• The generating stage could fail and not generate the required PDF file
• More checks for PDF file could be added in the future (e.g. header, keywords)

Add script to update document-version.tex:

• Currently, one has to pipe the output of ahpula script into the file
• Provide a script called update-document-version.sh which (optionally) takes a date in ISO format
• It generates the document-version.tex
• If a date is not provided, use the current date

When running on macOS using Apple M1, the ltex extension for LaTeX doesn't work.
The log looks something like this:

2023-04-24T07:33:09.822Z Info: Searching for ltex-ls in '/home/ajtzib/.vscode-server/extensions/valentjn.vscode-ltex-13.1.0/lib'...
2023-04-24T07:33:09.823Z Info: ltex-ls found in '/home/ajtzib/.vscode-server/extensions/valentjn.vscode-ltex-13.1.0/lib/ltex-ls-15.2.0'.
2023-04-24T07:33:09.823Z Info: 
2023-04-24T07:33:09.823Z Info: Using ltex-ls from '/home/ajtzib/.vscode-server/extensions/valentjn.vscode-ltex-13.1.0/lib/ltex-ls-15.2.0'.
2023-04-24T07:33:09.823Z Info: Using Java bundled with ltex-ls as ltex.java.path is not set.
2023-04-24T07:33:09.825Z Info: Testing ltex-ls...
2023-04-24T07:33:09.825Z Info:   Command: "/home/ajtzib/.vscode-server/extensions/valentjn.vscode-ltex-13.1.0/lib/ltex-ls-15.2.0/bin/ltex-ls"
2023-04-24T07:33:09.825Z Info:   Arguments: ["--version"]
2023-04-24T07:33:09.825Z Info:   env['JAVA_HOME']: undefined
2023-04-24T07:33:09.825Z Info:   env['JAVA_OPTS']: "-Xms64m -Xmx512m"
2023-04-24T07:33:09.835Z Error: Test failed.
2023-04-24T07:33:09.835Z Error: Error details:
2023-04-24T07:33:09.835Z Info: ltex-ls terminated with non-zero exit code 255.

The reason is, that the Java Runtime Environment (JRE) is not shipped with the extension for Apple Silicon (ARM64).
The problem can be somewhat mitigated when the JRE is installed manually (e.g. using brew).
The environment variable JAVA_HOME has to be set to the path of installation.
Additionally, inside the settings.json of VSCode, one has to specify the location using ltex.java.path

This issue also applies to Docker images as the Ubuntu guest system is also based on ARM64 on an Apple Silicon.
One part of a fix would be to install the JRE in the Docker container (adding an appropriate install command to Dockerfile.
However, adding the ltex.java.path to the general settings file is discouraged as other systems would not find the JRE automatically anymore.

I don't think it's worth requiring all users to have Java installed and setting the configuration in settings.json.
This would contradict the "it works out-of-the-box" approach here.

To be investigated...

Links regarding this topic:
valentjn/vscode-ltex#224
valentjn/vscode-ltex#634

Required steps to install Java (openjdk-18-jre) in Docker:

RUN apt-get -qq install \
        git git-lfs \
        inkscape vim \
        curl wget \
        openjdk-18-jre \
        apt-transport-https software-properties-common

ENV JAVA_HOME "/usr"

Line to install in settings.json:
"ltex.java.path": "/usr"

With the newest version of vscode (1.75), the devcontainer.json file is not valid anymore.
The file format has significantly changed.
This has to be adjusted to make the devcontainer workflow usable again.

There are still some minor things to be adjusted:

• Minor text adjustments, typos, text flow etc.
• Correct document version
• First change-log

The chapter 'Solar calendar' addresses the Haab' calendar.

It should include the following:

• Naming Haab'
• Haab' vs Tun?
• Terminology Winal vs Month
• Landa's list of winals and description
• Comparison Xiuhpōhualli and Haab'?
• Nemontemi and Wayeb
• Size, orientation, position, infixing, superposition and fusion of graphemes/glyphs
  • No change in meaning

Sometimes it is useful to see the calendar round for a certain date.
Therefore, add the possibility to calculate the Tzolk'in date and Haab' date.
Both dates can be enabled via command line argument --tzolkin and --haab.
The long count can be controlled by --long-count and --no-long-count.
In oder to shorten the arguments, an option called --calendar-round prints both Tzolk'in date and Haab' date.
The default should be the long count output only.

There are python scripts and bash scripts being used in the project.
That is somewhat ugly since not all platforms understand bash scripts.
Especially Windows users don't have native support for it.
In addition, one needs python to be installed.
Reducing the dependencies to a single language would be preferable.
Maybe using PowerShell would be good solution.
It is supported on all three platforms (Windows, Linux, macOS) and is also open source.
It might be a solution, but needs more insight into this topic.
Some links:
https://stackoverflow.com/questions/42362596/cross-platform-shell-scripts
https://github.com/PowerShell/PowerShell

• Calendar round - Haab' + Tzolk'in
• Long Count: Era base date 13.0.0.0.0 4 Ajaw 8 Kumk'u
• Correlation to Gregorian calendar
• Starting of the day
  • Puuc dates: Off by one in Tzolk'in
  • Tzolk'in dusk, Haab dawn
• Yearbearers
  • Aztec vs Maya
  • Discussion

ZSH is more powerful than bash.
Among other features, it supports to display git information like the current branch.
It would be nice to have that during authoring.
ZSH should be the default.
Good old bash should be available after all.

If one types python3 ahpula.py -cr 2023-01-08 in the terminal, the script crashes.
See traceback:

Traceback (most recent call last):
  File "/workspaces/maya-decipherment/ahpula.py", line 336, in <module>
    main(sys.argv)
  File "/workspaces/maya-decipherment/ahpula.py", line 323, in main
    print_plain(
  File "/workspaces/maya-decipherment/ahpula.py", line 278, in print_plain
    dates.append(f"{maya.haab.standard_notation()}")
  File "/workspaces/maya-decipherment/ahpula.py", line 232, in standard_notation
    return f"End of {month_name()}" if self.day() == HaabDate.WINAL_DAYS else f"{self.day()} {month_name}"
TypeError: 'str' object is not callable

It crashes if given date falls onto an end of a Haab month.