Merge documentation/advanced-git-commands: BRF, Word, EPUB build pipeline

- BRF via python3-louis (liblouis Grade 2 braille, zero TTS required)
- Word (.docx) via pandoc
- EPUB 3 with preprocessed links
- All three uploaded as 90-day CI artifacts

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: taylorarndt

.github/workflows/build-epub.yml

@@ -1,4 +1,4 @@
-name: Build EPUB and Word
+name: Build EPUB, Word, and BRF
 
 on:
   push:
@@ -34,6 +34,17 @@ jobs:
       - name: Build EPUB and Word
         run: node scripts/build-epub.js
 
+      - name: Install liblouis (braille translator — no TTS needed)
+        run: sudo apt-get install -y liblouis-bin python3-louis
+
+      - name: Convert EPUB to BRF (Braille — no TTS required)
+        continue-on-error: true
+        run: |
+          mkdir -p epub/brf
+          pandoc epub/git-going-with-github.epub -f epub -t plain -o /tmp/book.txt
+          python3 scripts/build-brf.py /tmp/book.txt epub/brf/git-going-with-github.brf
+          ls -lh epub/brf/
+
       - name: Upload EPUB artifact
         uses: actions/upload-artifact@v4
         with:
@@ -48,14 +59,10 @@ jobs:
           path: epub/git-going-with-github.docx
           retention-days: 90
 
-      - name: Commit outputs to repository
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add epub/git-going-with-github.epub epub/git-going-with-github.docx
-          if [ -n "$(git status --porcelain)" ]; then
-            git commit -m "chore: rebuild EPUB and Word from latest docs"
-            git push
-          else
-            echo "No changes to commit"
-          fi
+      - name: Upload BRF artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: git-going-with-github-brf
+          path: epub/brf/
+          if-no-files-found: warn
+          retention-days: 90

.gitignore

@@ -167,3 +167,5 @@ podcasts/tts/samples/
 *.wav
 epub/git-going-with-github.epub
 epub/git-going-with-github.docx
+epub/git-going-with-github.brf
+epub/daisy/

scripts/build-brf.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""
+Convert plain text to BRF (Braille Ready Format) using liblouis.
+No TTS required — this is pure text-to-braille-dots translation.
+
+Usage: python3 build-brf.py input.txt output.brf
+"""
+import sys
+import louis
+
+# NABCC (North American Braille Computer Code) lookup table.
+# Maps 6-dot braille cell bitmask (0-63) to ASCII character.
+# bit 0=dot1, bit1=dot2, bit2=dot3, bit3=dot4, bit4=dot5, bit5=dot6
+NABCC = " A1B'K2L@CIF/MSP\"E3H9O6R^DJG>NTQ,*5<-U8V.%[$+X!&;:4\\0Z7(_?W]#Y)="
+
+
+def unicode_braille_to_brf(text):
+    """Convert Unicode braille characters (U+2800-U+283F) to NABCC ASCII."""
+    out = []
+    for ch in text:
+        code = ord(ch)
+        if 0x2800 <= code <= 0x283F:
+            out.append(NABCC[code - 0x2800])
+        elif code < 128:
+            out.append(ch)
+        else:
+            out.append(" ")
+    return "".join(out)
+
+
+def main():
+    input_file = sys.argv[1] if len(sys.argv) > 1 else "/tmp/book.txt"
+    output_file = sys.argv[2] if len(sys.argv) > 2 else "output.brf"
+
+    with open(input_file, encoding="utf-8", errors="replace") as f:
+        lines = f.read().split("\n")
+
+    brf_lines = []
+    for line in lines:
+        if line.strip():
+            try:
+                braille = louis.translateString(["en-ueb-g2.ctb"], line)
+                brf_lines.append(unicode_braille_to_brf(braille))
+            except Exception:
+                brf_lines.append(line[:80])
+        else:
+            brf_lines.append("")
+
+    output = "\n".join(brf_lines)
+    with open(output_file, "w", encoding="ascii", errors="replace") as f:
+        f.write(output)
+
+    print(f"BRF written: {len(output):,} bytes, {len(brf_lines):,} lines")
+
+
+if __name__ == "__main__":
+    main()

scripts/build-epub.js

@@ -119,7 +119,7 @@ const epubCmd = [
   '--toc',
   '--toc-depth=2',
   '--split-level=1',
-  '--syntax-highlighting=tango',
+  '--highlight-style=tango',
   '--wrap=none',
   fileArgs
 ].join(' \\\n  ');