Alphabetical order of terms in non-English version

[ichsteffen]

When the glossary is created with a target language other than English (i.e. currently German), the entries are (logically) not currently assigned to the correct letter.

Example: "Schicht" is under L for Layer

Does this cause a problem that should be corrected?

[gernotstarke]

It's a consequence of the following design decision:

1. to have distinct files for all terms, and make EN the primary language for that. Therefore, "Schicht" goes within the "layer.adoc" file, and will be included under the "L" header.
2. to use the "0-structure.adoc" files and the asciidoc include config mechanism to organize larger documents

Originally we only produced an EN version of the glossary with only translation tables instead of DE explanations, these came later, provided partially by a translator, partially by Mike Sperber and colleagues.

In case there are volunteers for creating a sorted DE version -> I'm open for this. Otherwise, I don't care, as both PDF and HTML versions are searchable, and many terms will be hyperlinked from curricula anyway. Therefore, people will be able to find "Schichten" whereever it's located physically within the glossary.

[ichsteffen]

The causes of the " issue" are known and understood.

Suggestion for a solution:
We could create a language-specific version of the structure file in ./docs/1-terms (e.g. 0-structure-DE.adoc) and include it in 0-structure.adoc inside the language tags.

The language-specific file can be created and filled automatically. A bash script is sufficient for this. I would put this script under /src/bash.

A structure file for German could be like this: 0-structure-DE.adoc.txt
It results into: glossary-de.pdf

Known drawbacks:

• one large language specific structure file in ./docs/1-terms is not the same structure as separate structure files per letter
• If the language specific structure files are created automatically the build process becomes more complex (and in a first step may be platform dependent)
• If the creation/update of the language-specific structure files is triggered manually, there is a risk that the version is not up-to-date and does not reflect changes in the term.

But a manual maintenance of language-specific files appears very error-prone and time consuming, so doing it by some kind of script seams to be the better way.

[gernotstarke]

deeply impressed I am - Yoda would say.

For the drawbacks you mention above:

• one large lang-specific structure file -> we could rename those to 0-structure-DE, and update their includes accordingly, by means of DE- and/or EN-tags.
• build-process complexity... as long it runs in CI, all is fine. Only VERY few people need to touch or understand the build.
• in case it gets too nasty with platform specific stuff, we can provide a Docker container encapsulating everything.
• Updates to the glossary won't happen THAT often - in the past, and handful per year.

thanx - and you (@ichsteffen ) definitely need to become "official author", see #154

[programming-wolf]

Fixed quite elegantly with #155