LuaBill - standalone LuaLaTeX installation check
2026-10-27 | Copyright 2026 Vsevolod Shashkov & Mikhail Shashkov
SPDX-License-Identifier: Apache-2.0

DEUTSCH
=======
1. LuaBill_LaTeX_check.tex in einen beschreibbaren Ordner kopieren, zum Beispiel
   Dokumente\LuaBill-Test. Der Test funktioniert ohne LuaBill und ohne .bill.
2. Bei MiKTeX: MiKTeX Console oeffnen. Unter Settings > General die Option
   "Always install missing packages on-the-fly" waehlen. Alternativ "Ask me"
   verwenden und alle benoetigten Paketinstallationen bestaetigen.
   Eine Internetverbindung und eine erreichbare Paketquelle sind erforderlich.
   Falls MiKTeX noch nicht fertig eingerichtet ist, zuerst die Einrichtung und
   die angebotenen Updates in MiKTeX Console abschliessen.
3. Die .tex-Datei in TeXworks oeffnen, oben links LuaLaTeX auswaehlen und auf den
   gruenen Startknopf klicken. Paketinstallationen abwarten. Zweimal uebersetzen.
   Alternativ im Terminal im Ordner der .tex-Datei zweimal ausfuehren:

   lualatex -no-shell-escape -interaction=nonstopmode -halt-on-error -file-line-error LuaBill_LaTeX_check.tex

4. Ergebnis: LuaBill_LaTeX_check.pdf mit zwei Seiten, Zaehler 2/2 und ohne
   Fehlermeldungen. Die mitgelieferte _reference.pdf ist nur ein Vergleich;
   massgeblich ist die auf dem anderen Computer neu erzeugte PDF-Datei.
5. Danach den urspruenglichen Beleg in LuaBill erneut erstellen.
6. Bei einem Fehler LuaBill_LaTeX_check.log und die erste Fehlermeldung aus
   TeXworks schicken. Das Protokoll liegt neben der .tex-Datei.
   Die Warnung "Shell escape feature is not enabled" ist fuer diesen Test
   harmlos. Shell Escape muss nicht eingeschaltet werden.

WICHTIG ZU SCHRIFTEN
MiKTeX kann fehlende TeX-Pakete und darin enthaltene Schriften nachinstallieren,
aber keine beliebigen Windows-/macOS-/Linux-Systemschriften. Der Test verwendet
dieselbe Auswahl wie LuaBill: Noto Sans, dann DejaVu Sans, dann Arial.
Monospace: Noto Sans Mono, DejaVu Sans Mono, dann Courier New; andernfalls bleibt
die TeX-Standardschrift. Fuer alle Tests muss die ausgewaehlte Schrift auch die
kyrillischen Zeichen und Waehrungssymbole enthalten. Falls diese fehlen, bitte
Noto Sans und Noto Sans Mono installieren und TeXworks/LuaBill neu starten.
Die in der PDF und im Protokoll genannten Familien sind die verwendeten Fonts.

TeX Live/MacTeX: Der Test laedt Pakete normalerweise NICHT beim Uebersetzen nach.
Fehlende Pakete ueber den Paketmanager derselben TeX-Installation installieren.
TUG-TeX-Live/MacTeX: TeX Live Manager (tlmgr); Ubuntu/Debian: apt.
Nicht beide Installationsarten miteinander vermischen.

Der Test laedt alle 19 direkten LuaBill-LaTeX-Pakete, prueft EN/DE/FR/IT/RU,
Schriftschnitte, Kyrillisch, Waehrungen, Formeln, farbige Tabellen, Kontakticons,
Links, Lua, PNG-Einbindung, TikZ, Wasserzeichen und Positionierung.
Er prueft nicht Java, Ghostscript, XML oder ZUGFeRD und fuehrt keine
LuaBill-Rechnung aus. Die mathematischen Unicode-Zuordnungen von LuaBill sind
fuer die spaetere PDF/A-Verarbeitung bestimmt und keine Paketabhaengigkeit.
Der Test erzeugt zusaetzlich eine kleine *-image.png als eigene Testgrafik.

РУССКИЙ
=======
1. Скопируйте LuaBill_LaTeX_check.tex в доступную для записи папку, например
   Документы\LuaBill-Test. Файл работает отдельно от LuaBill и документов .bill.
2. Для MiKTeX откройте MiKTeX Console > Settings > General и включите
   "Always install missing packages on-the-fly". Можно выбрать "Ask me" и
   подтверждать установку каждого требуемого пакета. Нужны Интернет и доступный
   репозиторий пакетов. Завершите первоначальную настройку и обновления MiKTeX,
   если они ещё не выполнены.
3. Откройте .tex в TeXworks, выберите LuaLaTeX в списке слева вверху и нажмите
   зелёную кнопку запуска. Дождитесь загрузки пакетов. Выполните компиляцию
   два раза. Команда для терминала приведена выше; выполнять в папке файла.
4. Должен получиться LuaBill_LaTeX_check.pdf из двух страниц со счётчиком 2/2,
   без ошибок. Файл _reference.pdf в архиве - только образец для сравнения.
5. Повторите генерацию исходного документа в LuaBill.
6. Если тест завершился ошибкой, пришлите LuaBill_LaTeX_check.log из той же
   папки и первую ошибку из вывода редактора.
   Предупреждение "Shell escape feature is not enabled" для этого теста
   допустимо. Включать Shell Escape не требуется.

Дозагружаются TeX-пакеты и содержащиеся в них шрифты. Системные шрифты так не
устанавливаются: поиск по имени Noto Sans не вызывает загрузку этого шрифта.
Выбор совпадает с LuaBill: Noto Sans -> DejaVu Sans -> Arial. Для моноширинного
текста: Noto Sans Mono -> DejaVu Sans Mono -> Courier New -> шрифт TeX по
умолчанию. Если не хватает кириллицы или символов валют, установите Noto Sans
и Noto Sans Mono отдельно, затем перезапустите TeXworks/LuaBill.
Проверка охватывает все пять языков и строже, чем документ только на английском.

В TeX Live/MacTeX пакеты обычно нужно устанавливать отдельно через менеджер
пакетов: tlmgr для установки TUG/MacTeX, apt для TeX Live из Ubuntu/Debian.
Инструкция Linux и список apt-пакетов есть в документации LuaBill:
docs/CROSS_PLATFORM.md, раздел Linux.
Java, Ghostscript и форматы XML/ZUGFeRD в этот тест не входят.
Настройки системы, программы и пользовательские документы тест не меняет.
Он создаёт собственные PDF, журнал, служебные файлы и маленькую PNG-картинку.

ENGLISH
=======
Copy the .tex file to a writable folder. In MiKTeX Console > Settings > General,
enable "Always install missing packages on-the-fly", or use "Ask me" and accept
the necessary installations. Complete initial MiKTeX setup/updates if required.
Open the file in TeXworks, select LuaLaTeX and compile twice. The command above
can also be run twice from a terminal in that folder. No shell escape is needed.
Expect a new two-page LuaBill_LaTeX_check.pdf with a 2/2 page counter and no
errors. The reference PDF is only for comparison. Retry your LuaBill document.
On failure, send LuaBill_LaTeX_check.log and the first compiler error.
The "Shell escape feature is not enabled" warning is harmless for this test;
leave shell escape disabled.

TeX Live/MacTeX generally needs packages installed separately using the package
manager belonging to that installation. System fonts are a separate dependency;
font-name probes do not install Noto/DejaVu/Arial. If necessary install Noto Sans
and Noto Sans Mono, then restart the editor and LuaBill. The test checks every
current LuaBill document language, including Cyrillic, and text/math/icon fonts.
It does not check the external Java/Ghostscript/XML/ZUGFeRD stages.

OFFICIAL HELP / ОФИЦИАЛЬНЫЕ ИСТОЧНИКИ
===================================
MiKTeX automatic package installation and Console settings:
https://miktex.org/howto/miktex-console
https://docs.miktex.org/manual/autoinstall.html
TeX Live package management (native installation vs operating-system packages):
https://tug.org/texlive/pkginstall.html
Noto Sans and Noto Sans Mono:
https://fonts.google.com/specimen/Noto+Sans
https://fonts.google.com/specimen/Noto+Sans+Mono
LuaBill license:
https://www.apache.org/licenses/LICENSE-2.0
