thecomamba / loretex

LoreTex is an extension to the Tex language for compiling pdf documents, providing an interface to define characters, places and more, and then generate a glossary containing those entities that are relevant to your story.

LoreTex

Have you ever struggled to keep your adventure notes organised? Did you copy and paste parts of your lore to different adventures set in the same world and then they ran out of sync? Do you wish to give your players an up-to-date handout but not reveal your secret details?

LoreTex may not be the answer to these problems, but it is my answer. It is an extension to the Tex language for compiling pdf documents, providing an interface to define characters, places and more, and then generate a glossary containing those entities that are relevant to your story.

Setup

Prerequisites

LoreTex assumes that you have the LuaLaTex compiler installed.

All required Tex packages are included at the beginning of main.tex. Currently, these are luacode and nameref.

Installation [Outdated!!!]

Clone this git repository to some place on your computer:

git clone https://github.com/TheComamba/LoreTex.git

Alternatively copy the contents of this repository to some place on your computer.

LoreTex uses the Lua scripting language, and can thus only be compiled using LuaLaTex. It further needs to load a library, which due to security reasons is only possible in shell-escape mode. Hence, to compile from a terminal you need to call:

lualatex -shell-escape <your tex document>

If you're running from a GUI that supports "magic comments"/"advanced headers", you can add the line

% !TeX TXS-program:compile = txs:///lualatex/{%.tex} -shell-escape "%.tex"

to your document.

(Note that this contains a bit of a hack, see this discussion.)

A note on security:

In principle, you could set your default compiler to the value provided above. Do not do this! This allows the execution of basically arbitrary code once you hit compile.

Usage

The tex file using LoreTex needs to be told where to find main.tex:

\documentclass{book/memoir}

...

\input{some/relative/path/to/main.tex}
\loadLuacode{some/relative/path/to/}

...

\begin{document}

A good place to start is the tutorials folder.

Contributing

Merge requests are welcome.

Please follow the gitflow naming convention of prefixing branches with "bugfix/" or "feature/". Currently I see no reason for a separate develop branch.

For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update the tests as appropriate.

Criticism of the coding style is very welcome. I find it tough to write clean code in Lua, and I am eager to improve.

And, of course, you are asked to comply with the code of conduct.

License

This software is distributed under the MIT license. In a nutshell this means that all code is made public, and you are free to use it without any charge.

loretex's Issues

Auto generated calendars

Using the information of months we can print out a table with an entry for every day (or maybe some smarter version of a calendar).

We could also define a new chronologies type named "holidays", which are automatically added to their affiliated calendars.

Make the functions of scoped_variables.lua part of the TexApi namespace

Can we disallow user-defined translations?

If the answer to #53 is yes, we probably do not need any translations.

Use all TexApi functions in the tests

Maybe change history latex commands.

To \birth, \death and \ignore.
Currently we have the latex command \birthof, which has a different casing than the protected descriptor birthOf.

Lifestages are added to sub-entities as well

Repro Steps:
1.: Create a new entity.
2.: Add a birth event by calling the \born{} command.
3.: Give the entity a species that exists and ages.
4.: Add a descriptor with a labeled subparagrah.

Test automatedChapters output before and after writing and reading to and from database

Why is the empty label check necessary in entities/species.lua, AddLifestageHistoryItems?

I thought every entity has a label?

Get rid of originator concept in history items.

Replace protected descriptors born and died with birthEvent and deathEvent

We could point to either (anonymous) history items that must contain a year and may or may not contain a day, or we could use a label of a historyItem entity (once they're implemented).

Implement a build and test workflow

\makeEntityAndChildrenPrimary should have a recursive option

Make sorting in lists configurable

Currently, affiliated entities are sorted alphanumerically. This is probably useful for most cases, but not all. Take, for example, a dynasty that lists all its rulers. Here I'd like chronological sorting (Henry VIII before Elizabeth II).

One possible solution is to add a protected descriptor "sorting" to entities, which contains either an empty string or another protected descriptor, by which affiliated entities are sorted. One drwaback is that currently not all contents of protected descriptors are sortable. For example, sorting by the role of an affiliation member is not directly possible with this setup.

More thoughts required!

Create an example adventure document

Ideally this should contain at least one usage of every TexApi function.
Maybe we can add the usage measurement currently only used in the tests to the Debug namespace and thus check which Api functions are not yet used.

This document should also be compiled by the pipeline scripts.

Make location captions point to their description

At the moment the captions for entities which sort them by location are generated from the location's shortnames. It would be nice to have some link to the location. One solution would be to use nameref commands instead of the shortname in the caption, but then the shortname in the optional argument of the caption (otherwise the table of contents contains links in links, which screws it up.)

Another solution would be to add a "Compare \nameref{some-location}." between header and entity.

Both solutions only make much sense if the locations are primary refs, and not only mentioned.

Allow generated subentities with shortnames

Something like
\subpagraph[short]{long} \label{sub}
should work.

And then we also need an optional shortname argument for setDescriptor.

Make error messages modal cards

Compare https://github.com/iced-rs/iced_aw#modal

Make some historyItems full-fledged entities

They then contain a label. These entities could even contain sub-history items. This might be useful for important events lasting several days.

Maybe we need a new chronologies type for this feature.

Remove setDefaultLocation

Print warning if an entity has no location set.
Setting location explicitly to empty string is ok, because some top-level entities have no location.

makeEntityAndChildrenPrimary is buggy

Make planetRadius modifiable by user

Implement Dictionaries

A little code for this feature already exists in the file dictionary.lua, from the time before feature branches and pull requests.

It would nice to give RpgTex a table input and have it print that table in a user defined version. For example, you can give it a dictionary for a fictional language containing the columns "English", "Grey Elvish", "Elvish Spelling" and "Pronounciation", and then make it print the table in that column order, with rows sorted alphanumerically by the "English" column, and then print it again with only the columns "Grey Elvish" and "English", rows sorted by the (now) first column.

Make generated label flag an underscore

Move absolutely all logic to Rust

Lua then becomes a thin layer merely calling the rust library.

Make labels lowercase and check for non-unicode characters

The year of the descriptors string is not adjusted properly if the year format has an offset

Repro Steps:

1. Create a year format with a year offset.
2. Create an entity with some birth year.
3. Add a second entity as the parent of the first.
4. Make the second entity primary and print it.
5. The birthyear printed with the first entity is not displayed correctly.

Make DebugPrint multiline

Analogous to test code.

grep for LogError and DebugPrint, needs to become a table, otherwise we try to concat strings with tables.

Do we need the mentions field when we have the concerns field?

Additionally write LoreTex errors in logfile

Using
texio.write_nl( message )

Command MakeMentionsPrimary

Relevant for history entries.

Can we turn LoreTex into a Tex-package?

This would significantly lower the entry-bar for new users, especially those without a programming background.

Add debug option to print all descriptors where they are defined.

This makes debugging in tex much easier, because any undefined command in any descriptor will otherwise just lead to the error message "command automatedChapters is unknown".

Support SQL Databases?

Managing around a thousand entities is quite annoying when they are sorted in files. I often find myself using grep to find out what file a specific entity is defined in.
It would be much cooler to store all my entities in a database, with a small GUI to access it. It should contain a search field, and maybe some checkboxes generated from the content (e.g. "show me only entities of type npc").

Run the pipeline scripts upon pull request and only allow the merge upon success.

Do we even need metatypes?

Or could we just print one chapter per type?
Then we could remove the need to declare types beforehand - they are just deduced from the types that appear in entities.

If declarePC is called before the creation of the pc, they merely become an npc.

Store parent-child relationship in extra SQL table

Columns "parent", "child", "relationship"

Temperature gradients

A list which stores "day of year" and associated "average temperature". If the current day is globally set, we can linearly interpolate between the points to display the expected current temperature.

More generalised functions for IsPast or IsFuture (event -> bool), also considering the day of the event

We do not need to store the yearFmt in the history item.

Error with secret history

Adding a secret history item and then a non secret history item, and then printing without secrets, the date is not shown.

Offer option to use Python instead of LuaLaTex

Prerequisite: #32

Python can generate PDF documents as well. This would create another channel for users to access the functionality.

In that case the repo should probably be split up into LoreTex, LorePy, and a subrepo containing the rust code.

Support for Typst instead of Latex

https://github.com/typst/typst

Properties for Descriptors

Now that descriptors can be sub-entities, they could for example be secret, have their own association, their own ageFactor, etc.

More than one location for an entity?

This might be relevant for rivers, which are often the border between two countries. Should they be part of both?

Output shows weird behaviour when descriptor contains nested itemize environments

Rename RpgTex -> LoreTex

RpgTex already exists as a template for a DnD5e inspired look and feel: https://github.com/rpgtex

Repo is already renamed, but the former name still persists through the code.

Can we delete all hard-coded types?

All types would need to be defined by the user.

Entities should be of the same category even if the casing is different.

Is that already the case? Write a test!