/HOMM3BG

Repository for rewriting the rule book.

Primary LanguageTeX

Heroes of Might & Magic III: The Board Game 🐴 🛡️ ⚔️️
Rule Book Rewrite Project 📜🪶

Please see the original thread on BoardGameGeek 🤓

Efforts are ongoing to translate the rule book to languages other than English. Please reach out if you'd like to help with translating. Click in the table to download the most recent builds in the chosen language:

Language Progress Version 1.2 🪨
(Stable)		 Latest Build ⚗️
(Experimental)
🌍 ✍️
Text		 🏞️
Images		 🖥️
Digital		 🖨️
Printable		 🖥️
Digital		 🖨️
Printable
🇬🇧 English - - download download ️download download
🇵🇱 Polski 100% 100% pobierz pobierz ️pobierz pobierz
🇪🇸 Español 100% 0% descargar descargar ️descargar descargar
🇫🇷 Français 100% 100% télécharger télécharger ️télécharger télécharger
🇷🇺 Русский ~39% 0% — — ️скачать скачать
🇺🇦 Українська 100% 0% завантажити завантажити ️завантажити завантажити
🇩🇪 Deutsch ~15% 0% — — ️speichern speichern

🪨 Stable release is the latest one officially released. It should be free of any major issues.
⚗️ Experimental builds are made from the main branch every time a new change is introduced. You can expect things to break, like having incorrect layout or not all the text translated.

🖥️ The digital build is intended to be read on electronic devices. It has convenient hyperlinks that navigate you around the text.
🖨️ The printable build introduces the following changes:

  • appends page numbers to clickable hyperlinks (stable) 👆
  • includes an index page at the end (stable) 📋
  • makes sure the document has 56 pages (stable) 🪄
  • makes margins asymmetric for easier binding/glueing (experimental) 📕
  • uses CMYK (experimental) 🎨

all of which to be print friendly. Best served for those who would like to have it on paper 🤞

This repository used to host Comprehensive Components List listing all the cards, minis, tokens, etc. for every box, but after a while ⚠️ ️️Archon released their own version of it, and you should use it instead. Find it on 👉 their website 👈 called "Content Guide".

💡 What Is This?

This project aims to rewrite the original rule book, in which the amount of vague language was just too vast to ignore.

This repository hosts a document that aims to explain the rules clearly and concisely, and should eventually have an answer for any basic rules query you might have.

🤔 Why?

The content in the official English rule book is, simply put, insufficient as a teaching tool for the game or as a general rules reference. If you read the thread linked above you should understand how frustrating this has been for me.

🛠️ How?

This is a communal effort. This repository serves both as a means for me to preserve my work, but also for others to contribute to it as writers, proofreaders, or layout designers.

💪 Contributing

Please discuss any and all factual errors, bad language or other errors you've found. You can do this by opening issues, pull requests with suggestions or writing in the BGG thread.

🔮 The Future

All new version of the rule book and their change logs will be published here and in the BGG thread.

💻 Local Development

To work on the document on your machine, you need the following:

  • MiKTeX for Windows, MacTeX for MacOS, TeX Live for Linux (required) to build the PDF file from LaTeX files
  • Inkscape (required) to render glyphs in the document (while installing on Windows, make sure to tick Add Inkscape to the System Path option)
  • TeXstudio (optional) to edit LaTeX files and rebuild the PDF file quickly
  • po4a (optional) to work on translating the document to other languages
  • pdftoppm (optional) to make screenshots of rendered PDF pages
  • ImageMagick (optional) to combine screenshots into convenient diffs
  • ghostscript (optional) to optimize PDF file sizes
  • GIMP or Krita (optional) to edit some images in assets directory
  • aspell (optional) for spellchecking

To build the document in English, either run this in the command line:

latexmk -pdf -silent -shell-escape "main_en"

or use the script:

tools/build.sh en

or press the Build & View ▶️ (F5) button in TeXstudio on the main_en.tex file.

To build the document in any language (currently, pl, es, fr, ru, ua and de are supported), make sure you have po4a (version 0.70 or higher) and use the script:

tools/build.sh <LANGUAGE>

or press the Build & View ▶️ (F5) button in TeXstudio while having any main_<LANGUAGE>.tex file open, after running po4a (see Translations below for details).

To build the printable version in a given language, make sure you've built a regular one first at least once. Then, use the script:

tools/make_printable.sh <LANGUAGE>

🌍 Translations

Make sure you have po4a installed (MacOS instructions).

To translate a particular section:

  • Go to translations/<section_name> and open <lang>.po file, e.g., translations/introduction.tex/pl.po

  • Choose a fragment to translate. Those start with msgid. Write your new text in the line below starting with msgstr. Example:

    msgid "\\addsection{Introduction}{\\spells/magic_arrow.png}"
msgstr "\\addsection{Wprowadzenie}{\\spells/magic_arrow.png}"

    This text (msgstr) will replace the original (msgid) in your translation.

  • Regenerate your localized section:

    po4a --no-update po4a.cfg

    Disregard the errors about mismatched multicols, as this is an upstream parser issue.

  • Rebuild your PDF file (or press Build ▶️ in TeXStudio).

    latexmk -pdf -silent -shell-escape "main_<lang>"

  • Commit and repeat!

Finding fuzzy translations

In case an already translated text is changed, po4a marks such a translation as fuzzy in the *.po files. Those excerpts will be compiled just as they are in the original (English), until the translation is corrected, and the fuzzy mark is removed. To facilitate finding them, use the script:

tools/find_fuzzy.sh <lang>

It will show all the fuzzy translations in the *.po files for the specified language.

📸 Screenshots

It is a good practice to share screenshots of your work in pull requests. You can the script to make PNG images of specified page(s):

tools/pdf2image.sh <LANGUAGE> <FIRST_PAGE> <LAST_PAGE>

Example:

tools/pdf2image.sh en 5 7

To process a single page, use:

tools/pdf2image.sh en 5

🎭 Comparing two pages side by side

If you'd like to show a single image of two instances of the same page side-by-side (before|after style), you can use the following script:

tools/compare_pages.sh <FILE_COMPARED_AGAINST> <LANGUAGE> <FIRST_PAGE> <LAST_PAGE>

Let's assume you have main_en.pdf in your home directory downloaded from GitHub, and in your current working directory you have a build you're working on. You'd like to have images comparing pages 38 through 41. Here's how to use it:

tools/compare_pages.sh ~/main_en.pdf en 38 41

It will produce files: en-38.png, en-39.png, en-40.png and en-41.png.

This script requires pdftoppm and imagemagick utilities.

🗠 Optimizing PDF files

To reduce output PDF file size significantly, you can use the script utilizing ghostscript utility:

tools/optimize.sh <LANGUAGE>

It will output main_<LANGUAGE>_optimized.pdf file.

As of writing, for English it produces 23 MB main_en_optimized.pdf file without noticeable drop in quality compared to 78 MB main_en.pdf built by LaTeX.

🔎 Spellchecking

TeXstudio has built-in spellchecking, but the first steps have been made towards automated spellchecking with aspell. For local development, after installing the tool, you can run it from the command line for example with

aspell -d en_US -p=./.aspell.homm3.pws --mode=tex --dont-backup check main.tex

or when wanting to check all .tex files then with

find . -type f -name "*.tex" -exec aspell -d en_US -p=./.aspell.homm3.pws --mode=tex --dont-backup check {} \;

Please note that currently the tool will flag many parameters in LaTeX commands. We are currently looking into how best to remediate this.

The personal dictionary .aspell.homm3.pwd currently contains only game-related words. It does not contain names (e.g., "BoardGameGeek") or parameter values (e.g., "px", "svg") in order to minimize the chances of false-negatives in the main body of text.

✨ Assets

All assets come from publicly available sources. Some of the images in the rule book (all in the assets/examples directory as of writing) were generated by GIMP. Their respective XCF files reside in assets/gimp-files directory.