ADR: Manual Build and Distribution for OmegaT

Status

Accepted – Partially Implemented

Context

The OmegaT project currently includes user manuals as part of its distribution. These manuals are stored as HTML files in language-specific subfolders located under the docs directory. This setup presents several challenges:

  1. Large Distribution Size:

    • The inclusion of manual files significantly increases the distribution size.

    • Redundant or unused assets—such as images, CSS, or JavaScript files—contribute to unnecessary bloat.

  2. Accessibility:

    • A proposed online manual aims to improve accessibility for users who prefer web access.

    • However, OmegaT is designed to function offline, requiring offline manual access for core functionality.

  3. Localization Inefficiencies:

    • Bundling language-specific resources (e.g., spellchecking dictionaries) with localized manuals is currently inefficient.

  4. Build System Complexity:

    • Manual builds rely on outdated tools (e.g., DocBook 4.5, XSLT 1.0, and Saxon 6).

    • The build process utilizes containerization, which reduces performance and consumes developer PC disk space.

  5. Repository Size Issues:

    • Owing to the low performance of the manual build process, the project stores prebuilt HTML files in the repository.

    • This practice inflates the repository size, increases download requirements for developers, and creates potential inconsistencies between source files and built artifacts.

Decision

To address these issues, the following decisions have been made regarding manual distribution and the build process:

  1. Distribution of Manuals as ZIP Archives:

    • Manuals will be packaged as ZIP files containing HTML files, optimized assets (images, CSS, JavaScript), and related language tools (e.g., spellchecking dictionaries).

    • Manuals will be extracted temporarily from ZIP files when accessed via Help > Manual in OmegaT or used offline for local browsing.

  2. Improved Accessibility:

    • Manuals will be accessible via the OmegaT website for those who prefer online browsing.

    • Offline access will remain available to ensure core functionality is preserved for offline users.

  3. Modernized Build System:

    • Replace the current container-based build process with a Gradle-based system.

    • Legacy dependencies (e.g., Saxon and DocBook) will be updated and repackaged in OmegaT’s Maven repository.

  4. Updated Folder Structure:

    • Restructure documentation files into a Gradle-compatible format (e.g., src/docs/manual/<lang>).

    • Align Java source files (src/) and testing files (test/) with Maven/Gradle directory layout standards (src/main/java, src/test/java).

    • Now it is interim status that is located in src_docs instead of src/docs/ and keep src/ and tset/ folders.

Consequences

Benefits

  • Reduced Distribution Size:

    • Switching to ZIP distribution minimizes distribution size by removing unnecessary and redundant files.

  • Enhanced Accessibility:

    • Users can choose between online and offline manuals, enhancing flexibility for different scenarios.

  • Improved Developer Workflow:

    • A Gradle-based system simplifies the build process and aligns with modern development practices.

  • Optimized Resources:

    • Shared assets (CSS, JS) and better-optimized images reduce file duplication and repository size.

  • Future Scalability:

    • A modular Gradle-based build system enables easier updates and enhancements.

Drawbacks

  • Increased Build Complexity:

    • Developers must familiarize themselves with Gradle and updated workflows, introducing a temporary learning curve.

  • Refactoring Effort:

    • Migration involves restructuring the existing source, test, and documentation directories.

  • ZIP Expansion in User Folder:

    • Manuals will be extracted into the user folder when accessed via the Help menu. These files can then be bookmarked in the user’s preferred browser.

Alternatives Considered

  1. Retain the Current System:

    • Pros: No new development required.

    • Cons: Fails to address distribution size, accessibility, and workflow challenges.

  2. Fully Web-Based Documentation:

    • Pros: Simplifies distribution entirely.

    • Cons: Removes offline functionality, which is vital for some users.

  3. Remove Manuals from the Distribution:

    • Pros: Significantly reduces the distribution size.

    • Cons: Severely impacts usability for offline users.

Implementation Details

  1. Manual Build Workflow:

    • Gradle will generate:

      • Language-specific ZIP archives for manual distribution.

      • Extracted HTML manuals for testing and development purposes.

    • Required libraries (e.g., Saxon, Libstemmer) will be hosted on OmegaT’s Maven repository.

  2. Manual Updates and Packaging:

    • Developers will contribute manual updates in an XML DocBook format.

    • Zipped manual archives will be published alongside OmegaT releases.

  3. Updated Folder Structure:

    • Manual source files will be located at: src/docs/manual/<lang>/.

    • Gradle build scripts (build.gradle, settings.gradle) will reflect the new structure.

Risks and Mitigation

  • Backward Compatibility:

    • Legacy manuals will be bundled in default language ZIP files to ensure accessibility.

    • Documentation will explain offline usage and ZIP file extraction.

  • Tooling Compatibility:

    • Extensive testing will ensure compatibility across all supported operating systems (Windows, macOS, Linux).

Adoption Plan

  1. Migrate existing manual sources to the updated Gradle-compatible folder structure (src/docs/manual/).

  2. Develop Gradle build scripts to automate manual generation and testing workflows.

  3. With OmegaT’s next release, distribute language-specific manual ZIP files to users.

References

Date: June 26, 2025
Author: Hiroshi Miura
Reviewers: OmegaT Development Team