yoshinoPDF 1.4.24 — source and build instructions

These instructions are for rebuilding the public distribution. End users should
run the Setup executable. Copyright (C) 2026 Harukazu YOSHINO.

Runtime and source execution
----------------------------
Use 64-bit Python 3.10 or later. The Windows installer uses embedded CPython
3.13.12 with PyMuPDF 1.26.6, PySide6-Essentials 6.12.0 and shiboken6 6.12.0.
Exact upstream download URLs and hashes are in installer/runtime-lock.json.
Source versions and component licenses are described in SOURCE_INFO.txt,
sources-lock.json and THIRD_PARTY_NOTICES.txt.
On Windows, setup.bat creates a private development environment; start.bat runs
it. Alternatively, install requirements.txt and run viewer.py. The installed
launcher loads its private Python DLL in the same process, without a console.

Application layout
------------------
viewer.py implements the UI and document workspace. Supporting modules handle
annotations, formulas, instance routing, cropping, deskew, perspective.
annotation_tools.py implements text markup properties, sticky comments and the
independent right annotation sidebar; annotation_clipboard.py preserves markup
appearance widths in the editable clipboard format.
localization.py, translations_en.json and locales/*.json provide 21 languages.
Japanese messages are stable translation keys; all translation entries and placeholders
must agree. LATINA_NOTES.txt documents the Latin translation approach.
No PDF content is sent to a translation service.

Rebuild on Windows
------------------
1. Install x64 MinGW-w64 and NSIS 3, with gcc, windres and strip on PATH.
2. Build the printing bridge on Windows with native_print/build.ps1. See
   native_print/README.md for MSVC and Windows SDK requirements. Supply the
   development runtime expected by the build script.
3. Run launcher/build_launcher.bat to rebuild yoshinoPDF.exe.
4. Rebuild installer/shortcut_identity.exe if its source changes:
   gcc -municode -mwindows -O2 -static-libgcc installer/shortcut_identity.c \
       -lole32 -luuid -lpropsys -lshell32 -o installer/shortcut_identity.exe
   The helper's source and required compiler/library flags are included.
5. Run python installer/make_guides.py after documentation/version changes.
   This developer tool uses ReportLab and docs/NotoSansJP-Regular.ttf.
6. Run installer/build_installer.bat. The default output is
   yoshinoPDF-1.4.24-Setup.exe in this source folder.
The installer contains application code and notices, and downloads verified
upstream runtime packages during installation. It is not an offline runtime bundle.

Cross-build and package
-----------------------
On Linux, use x86_64-w64-mingw32 gcc/windres/strip for the native launcher and
helper, and makensis for installer/setup.nsi. Use a matching Windows-built
yoshino_print.dll for the NSIS package. Set OUTPUT_FILE with makensis
-DOUTPUT_FILE=/absolute/path/yoshinoPDF-1.4.24-Setup.exe if required.
Extract the finished installer with 7-Zip, then run:
  python installer/package_release.py --setup /path/to/Setup.exe \
      --extracted /path/to/extracted --output /path/to/yp_1.4.24.zip
The packager checks extracted files against these sources, validates Python/JSON,
and includes editable sources, tests, build tools, fonts and component notices.
Private handoff/investigation/test-result records are excluded from the public
archive and its source.zip. No private documents are needed to rebuild it.
Publisher-only management archives can be created with the optional packaging
arguments documented by --help. Do not publish those management archives.

Tests and assets
----------------
Run python -m unittest discover -p "test*.py". For headless Linux testing, set
QT_QPA_PLATFORM=offscreen. Native Windows behavior still requires Windows testing.
Use temporary QSettings files or accounts to isolate application preferences.
The icon can be regenerated with installer/make_icon.py and Pillow. Noto fonts
are unmodified distributions with their included licenses. MathJax sources,
package locks and build entry are in mathjax/ and third_party_sources/; rebuilding
that bundle requires Node.js/npm, but the app itself uses Qt's local JS engine.

Publication
-----------
Keep source.zip, source information and all component license notices with the
public distribution. If signing executable files, package and hash them after
signing. Application build and guide generation do not download private records.

Japanese speech control
-----------------------
voice_control.py owns one microphone worker for the workspace. voice_commands.py
parses standalone Japanese commands while enabled. voice_worker.py uses Vosk
and sounddevice. Windows dependencies and the model are pinned in runtime-lock.json.
For source execution, install requirements.txt, then download the speech_model
entry using installer.install_wheels.cached_archive and unpack it into speech-model/.
Do not enable the microphone during application startup or installation checks.
The installed check loads the model and DLLs without opening an input stream.


Speech number tables: install num2words==0.5.14 in a development environment and run installer/generate_speech_numbers.py. No additional runtime dependency.
