/Homm3BG

Repository for rewriting the rule book.

Primary LanguageTeX

Heroes of Might & Magic III: The Board Game
Rule Book Rewrite Project

Join us on Discord to help with translating or just to get in touch!

Language Progress Version 1.2 🪨
(Stable)		 Latest Build ⚗️
(Experimental)
🌍 ✍️
Text		 🏞️
Images		 🖥️
Digital		 🖨️
Printable		 🖥️
Digital		 🖨️
Printable		 🤑
Economy Printable
🇬🇧 English - - download download ️download download download
🇵🇱 Polski 100% 100% pobierz pobierz ️pobierz pobierz pobierz
🇪🇸 Español 100% 0% descargar descargar ️descargar descargar descargar
🇫🇷 Français 100% 100% télécharger télécharger ️télécharger télécharger télécharger
🇷🇺 Русский 100% 0% — — ️скачать скачать скачать
🇺🇦 Українська 90% 0% завантажити завантажити ️завантажити завантажити завантажити
🇩🇪 Deutsch 50% 0% — — ️speichern speichern speichern
🇨🇿 Čeština 100% 0% — — stáhnout stáhnout stáhnout
🇮🇱 עברית 100% 0% — — הורדה הורדה הורדה
Click to see the details regarding every version

🪨 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 🤞
🤑 The economy printable build has no art backgrounds. Other than that, it's the same as the regular printable build. This is for people who want to save their toners or don't have printers that can print edge to edge where the white borders around the art backgrounds don't look that good.

💡 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. Its aim is to explain the rules clearly and concisely, and should eventually have an answer for any basic rules query you might have.

🤔 Why?

Please see the original thread on BoardGameGeek.

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 to preserve the 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/PRs with suggestions, writing in the BGG thread, or joining us on Discord.

🔮 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
Click to learn about the technicalities

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

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, de cs, and he are supported, en is the default), 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>

To make a printable version without any background images, add --no-bg flag

tools/make_printable.sh <LANGUAGE> --no-bg

🌍 Translations

Click to see details

Make sure you have po4a installed.

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.

  • Rebuild using the script:

    tools/build.sh <LANGUAGE>

  • 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

Click to see details

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

Screenshots will appear in ignored screenshots direcotry, in the form of en-05.png, en-06.png, etc.

🎭 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 -l <language> -r <range> [OPTIONS]

The script takes local main_<language>.pdf that you built and which contains your changes and compares it with the latest build of the same language in this repository (e.i. the baseline).

Imagine you want to compare pages 1, then range from 5 to 7, and page 30 in English version. Here's how to use it:

./tools/compare_pages.sh -l en -r 1,5-7,30

It will produce the following files in the screenshots directory: en-01.png, en-05.png, en-06.png, en-07.png and en-30.png.

Open help for more examples and detailed description:

tools/compare_pages.sh -h

This script requires pdftoppm and imagemagick utilities.

🗠 Optimizing PDF files

Click to see details

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.

✨ 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.

Star History

Star History Chart

🛡️ Other Community Projects