Add option to skip Katla syntax highlighting in build-book script

[gemmaro]

Hello, thank you for maintaining this project!

Summary

Add an option to the build-book script to skip Katla syntax highlighting execution, allowing for faster setup and preview of mdBook documentation.

Background

I'm currently working on updating translation of this project from the original project (ref). During the translation process, both Pack compilation of the Idris project and Katla execution via the build-book script are performed. However, for translation work, I only need mdBook setup and execution to review the content.

Being able to skip Katla processing would significantly speed up the feedback loop when reviewing translation progress, as I can focus on the text content without waiting for syntax highlighting to complete.

Proposed Solution

Add support for skipping Katla execution through either:

1. Environment variable (e.g., SKIP_KATLA=yes)
2. Command-line argument (e.g., --skip-katla)

This would allow users to quickly preview their work while still being able to enable full Katla processing for final builds.

Current Workaround

I'm currently using this temporary patch to skip Katla processing:

diff --git a/scripts/build-book b/scripts/build-book
index 965bb86..2e512f5 100755
--- a/scripts/build-book
+++ b/scripts/build-book
@@ -45,6 +45,11 @@ for paths("src").race(batch => 1, degree => Kernel.cpu-cores * 16) -> $path {
     my $ttc-path = $ttc.add($path.IO.relative: "src").extension: "ttm";
     given $path.IO.extension {
         when "md" {
+            if %*ENV<SKIP_KATLA> {
+                say "Skip Katla for ", $rel-path;
+                copy-to-dest $rel-path;
+                next;
+            }
             # Use the presense of a ttm file to detect if this markdown file was a regular
             # markdown file or a literate idris document
             if $ttc-path ~~ :e {

[nmccarty]

I'm going to leave this issue open for now to remind me that the eventual long term solution needs a quick-build function, but at the moment I'm not planning on making any alterations to the build-book script at this point in time.

build-book is a bit of a stopgap, I plan on replacing it with at least a proper mdbook preprocessor, if not replacing mdbook entirely as soon as we've got a workable solution for parsing markdown from Idris, which should hopefully be in the very near future.

[nmccarty]

Also while I appreciate your translation efforts, I would honestly advise holding off for a little bit, I'm still in the middle of a pretty major editing pass that's probably going to take another week or two.

After I've caught up with editing work, I'm going to introduce some structured method for maintaining the translations in the same repository, likely either using mdbook-i18n-helpers if we stick with mdbook, or a similar workflow if we migrate to a pure Idris solution.

[gemmaro]

Thank you for your reply. An mdBook preprocessor sounds great, and I'm looking forward to having the quick-build function.

Regarding translation, thank you for letting me know about the current situation. I'll postpone updating the translation for now.

Also, having translations in this repository sounds excellent since switching languages should be easier for readers. I wasn't aware of the i18n helper for mdBook, but it looks useful. I'm currently using po4a to localize sources and gather files to build with mdBook. Both methods share the fact that the translation source is Gettext PO format, so I hope the migration shouldn't be too difficult.

[nmccarty]

I wound up making a modification to the build-book script anyway, because I realized I had totally forgotten how race works when writing it and it wasn't actually doing any parallelism as written, and while its way faster now as a result, I went ahead and added a --skip-katla flag since I was in there anyway. Still recommend waiting a bit on the translation due to the ongoing major edits though.

As for mdbook-i18n-helpers at least, its designed to be used with some sort of addition on top of gettext, seeing as that's basically the only sane way to use gettext. Their documentation recommends poedit, but largely because poedit is roughly standard in the subset of the translation industry that produced mdbook-i18n-helpers, and I don't think it particularly cares which you use. As I understand po4a and poedit can roughly coexist, but we may wish to coordinate such that all maintainers for any particular translation are using the same tools.

[gemmaro]

I acknowledge the plan to modify the script.

We seem to be mostly on the same page regarding internationalization. What follows is a bit of nitpicking on details. Since my writing ("... I'm currently using po4a to localize sources...") was somewhat confusing, let me clarify my understanding of the tools.

mdbook-i18n-helpers and po4a are tools for internationalization (i18n). On the other hand, poedit is a tool for localization (l10n).
The former refers to the process aimed at making source documents (in English) easier to translate. In this case, this involves extracting text from documents like Markdown into Gettext PO format, or generating translated documents from Gettext PO files with translations and the original source documents.
The latter (l10n), however, refers to the process of editing Gettext PO format files - that is, the actual translation work itself. poedit is essentially like a text editor that makes it easy to edit files in Gettext PO format and similar formats.

source -----> PO -----> PO'
  |     i18n      l10n   |
  |                      |
  +---------<------------+
  |
  | i18n
  |
  v
translation

Based on these terminology distinctions, I think we should use consistent internationalization tools across the project (like mdbook-i18n-helpers for mdBook), but localization tools can be whatever the translators prefer to use (such as PO Mode for Emacs, which comes with Gettext).