Skip to content

PROJECT_BOARD.md

Latest commit

 

History

History
264 lines (174 loc) · 11.5 KB

PROJECT_BOARD.md

File metadata and controls

264 lines (174 loc) · 11.5 KB
Raw

ThinkJava2 Project Board

Numbered tasks for tracking work. Each task has a permanent number; add new tasks at the end. Update status as work progresses.

Current focus (2026-08-20)

  • Task 5: Build Quarto PDF and decide which PDF is canonical — not started (distrib uses LaTeX thinkjava2.pdf until then).
  • Task 6: Done — GitHub-canonical PDF (PR #36); GTP mirrored.
  • Task 7: Done — defer + visible code fallback; remaining gains are upstream (see java-runner#3).
  • Task 3: Done — interactive coverage expanded (46 editors + 5 REPLs).
  • Task 4: Done — LaTeX TOC restored (issue #30); comment posted.
  • Task 1–2: Done on branch java-runner (see issue #31 / PR #32).

Task 1: Dev environment for Quarto HTML

Status: Done (2026-08-20)

Context: Interactive book HTML is built with Quarto (make html → quarto/_book/). Issue #31 replaces Trinket with client-side java-runner. That work needs a reproducible local HTML build. This is not a JDK project: java-runner runs in the browser; conda only covers Python tooling.

Goal: Document and modernize the toolchain so make html / quarto preview work reliably.

Done

  • Modernize environment.yml (Python 3.12, conda-forge; no Pillow — unused)
  • Makefile targets: create_environment, update_environment, delete_environment
  • README: Quarto install (external) + conda activate + make html; note no JDK needed
  • Smoke-check: make html → quarto/_book/index.html; mamba env create succeeded

Out of scope

  • JDK / OpenJDK in conda
  • Building java-runner from npm (vendored dist/ in Task 2)
  • HeVeA / legacy Trinket path changes

Task 2: Integrate java-runner (feature parity)

Status: Done (2026-08-20)

Context: 17 former \begin{trinket} programs in chapters 1–5, 7, 10. Quarto had flattened them to ordinary {.java language="Java"} fences.

Goal: Those 17 snippets become interactive editors in Quarto HTML via <script type="text/x-java">.

Done

  • Vendor javarunner.css + javarunner.js into quarto/assets/javarunner/
  • Wire _quarto.yml: CSS, include-in-header JS, resources:, Lua filter
  • quarto/filters/javarunner.lua — .javarunner → text/x-java (HTML only)
  • Annotate all 17 former-trinket fences
  • Rebuild: 17 <script type="text/x-java"> across ch01–05, 07, 10; assets in _book/assets/javarunner/; not wrapped in code-fold details

Former trinket map

Chapter Programs
ch01 Hello, Hello2, Goodbye×3, Hello3
ch02 Hello×2
ch03 Echo, Convert, GuessStarter
ch04 NewLine, PrintTwice, PrintTime
ch05 Logarithm
ch07 Doubloon
ch10 Surprise

Out of scope

  • Removing legacy make trinket

Task 3: Expand interactive coverage (extra mile)

Status: Done (2026-08-20)

Context: java-runner can run incomplete snippets and supports REPL via text/x-java-repl.

Goal: After Task 2 parity, selectively add more interactives and optional REPL blocks.

Added .javarunner (editors)

Initial pass: ch01 bare/escaped println; ch02 time / minutes / 0.1 sum / string +; ch06 countdown / for-appreciate / multiplication table.

Next pass (completed):

Chapter What
ch02 firstLine println; int + double fraction/percent of hour (added local minute)
ch03 println(System.out); print/printf of 4.0/3.0
ch05 switch (food) — added String food = "banana"
ch06 Collatz — added int n = 3; i++ / i += 2 whiles; Roman/Greek alphabets (for + while); compareTo names
ch07 println(a) on {1,2,3,4} (default array toString)
ch09 immutability pitfall + fix; Integer ==/equals; printf row of 2*i

Added .javarunner-repl

  • ch02: message / hour / minute (also supports trying minute/60 vs minute/60.0)
  • ch03: CM_PER_INCH + inch conversion sandbox
  • ch04: Math.sqrt / sin / round / pow assignments
  • ch06: fruit / charAt(0)
  • ch07: int[] a = {1, 2, 3, 4}

Kept static (intentionally)

  • Compiler-error demos (e.g. int x = 1.1)
  • Infinite-loop examples (e.g. while with no update; forever)
  • Fragments that still depend on undeclared prior state
  • Cautionary broken control flow (e.g. if (...); { empty-statement trap in ch05)
  • Method-only fences with no main / call site
  • Book-specific / AWT types in incomplete form (Point, Rectangle, Card, Time, Graphics, …)
  • ch08+ recursion / OOP stubs without a full self-contained program

Deliverables

  1. Candidate judgment + completed annotation lists above
  2. Editors + REPLs annotated in Quarto sources
  3. Re-test: make html after annotations

Task 4: Fix empty TOC in LaTeX PDF

Status: Done (2026-08-20)

Context: Issue #30 reports a missing table of contents in the PDF. Confirmed on the LaTeX release path (thinkjava2.pdf / Green Tea Press thinkjava7): a Contents heading appears, but no entries. The Quarto PDF (quarto/_book/Think-Java.pdf) already has a full TOC. A commenter reproduced from source. Assignee: Allen Downey.

Goal: Restore a populated \tableofcontents in the LaTeX PDF build.

Root cause

Empty Contents was a failed / incomplete LaTeX build problem, not a missing \tableofcontents. With TeX Live 2025:

  1. listings upquote=true needs T1 (\textquotedbl unavailable in encoding OT1) — build aborted before \end{document}, so .toc never got written (0 bytes). One completed pass without a prior .toc typesets a blank Contents page.
  2. In a ch05 exercise tabular, \java{... && ...} breaks on & (alignment tab). Fix: delimiter-form \lstinline|...| / \lstinline+...+ (same style as \java, which is already \lstinline).

Fix

  • \usepackage[T1]{fontenc} in latexonly.tex
  • Four ch05 table cells → \lstinline|...| (one with || uses +...+)
  • Makefile: pdflatex -interaction=nonstopmode; continue all 3 passes; require thinkjava2.pdf
  • Rebuild: 372 pages, full Contents (Preface + chapters/sections), 0 ! errors in log
  • Comment on issue #30

Deliverables

  1. Findings + fix on this board — done
  2. Working LaTeX PDF TOC — done (make pdf)
  3. Note on #30 — comment

Task 5: Quarto PDF vs LaTeX — choose canonical PDF

Status: Not started

Context: Two PDF pipelines exist. Quarto already produces a TOC; LaTeX is what Green Tea Press has shipped (thinkjava7/thinkjava2.pdf). After Task 4, we should consciously pick a canonical PDF for distribution.

Goal: Build the Quarto PDF, compare it to the (fixed) LaTeX PDF, and decide which is canonical for releases / thinkjava.org / GitHub.

Scope

  • quarto render PDF (or confirm quarto/_book/Think-Java.pdf) builds cleanly
  • Side-by-side notes: TOC, typography, page count, code listings, figures, front matter
  • Decision: canonical = Quarto | LaTeX | both for different channels
  • Document decision in README / this board; update distrib targets if needed

Deliverables

  1. Short comparison notes
  2. Explicit canonical choice recorded here
  3. Follow-up issues/PRs if distrib paths need switching

Task 6: Redesign distribution (ThinkDSP-style)

Status: Done (2026-08-20) — PR #36

Context: ThinkJava2 used bob-local make distrib → DEST = /home/downey/public_html/greenteapress/thinkjava7 + sh back. That is the same fragile pattern ThinkDSP moved away from (ThinkDSP Task 10 / Task 11): publish cannot run off one machine’s home directory tree.

ThinkDSP pattern:

Layer Role
GitHub Canonical PDF (thinkjava2.pdf committed after make pdf)
GTP greenteapress.com/thinkjava7/ Stable old URLs; rsync via Host gtp (make publish-gtp)
HTML Quarto / GitHub Pages; not part of the PDF release ritual

Goal: Replace bob-only make distrib with: build → commit PDF to GitHub → optional rsync to GTP.

Done

  • Stop depending on /home/downey/public_html/greenteapress/... and sh back for the default release path
  • make distrib stages/checks LaTeX PDF for GitHub commit; publish-gtp-dry / publish-gtp mirror to GTP
  • README: GitHub download link + GTP mirror docs
  • thinkjava2.pdf tracked on master (raw link)
  • HeVeA HTML left out of the PDF release ritual
  • Live GTP copy refreshed with make publish-gtp (same build as GitHub)
  • Optional later: one-time GTP inventory for thinkjava7 / thinkjava.org URLs

Canonical PDF (vs Task 5)

Until Task 5 finishes a formal Quarto-vs-LaTeX comparison, distribution uses the LaTeX thinkjava2.pdf (what GTP already serves).

Deliverables

  1. New distrib docs + Makefile targets
  2. PDF on GitHub and mirrored to GTP
  3. Board note: LaTeX PDF for distrib pending Task 5

Task 7: Improve java-runner page-load performance

Status: Done (ThinkJava2 side)

Context: The Quarto HTML now includes java-runner on pages with interactive Java editors and REPLs. java-runner can take noticeable time to load and initialize. The book content should render as quickly as possible even if the interactive Java environment is not ready yet.

Goal: Make java-runner non-blocking where possible, measure where the startup time is going, and identify optimizations that belong in ThinkJava2 versus upstream java-runner.

Investigation (light)

  • javarunner.js ≈ 793 KB on disk (~250 KB gzip-9); bundled, not fully minified
  • Auto-init supports deferred load (DOMContentLoaded / ready DOM)
  • Full browser Performance panel timing left to manual check
  • Upstream tracking: java-runner#3

ThinkJava2 changes

  • Load javarunner.js with defer in _quarto.yml
  • Lua filter wraps runners in .jr-pending with a visible <pre class="jr-pending-code"> fallback
  • CSS hides the fallback once .jr-widget appears (:has(.jr-widget))
  • Browser smoke-test of editors/REPLs (manual)

Possible upstream improvements

Tracked in java-runner#3:

  • Production minification of the distributed JavaScript
  • Lazy initialization / lazy-load heavy runtime
  • Code splitting if useful

Preferred loading model

HTML arrives
    ↓
book page renders immediately (code visible via .jr-pending-code)
    ↓
deferred javarunner.js runs
    ↓
.jr-widget replaces interactive blocks; fallback hidden
    ↓
(Run / runtime readiness still owned by java-runner)

Deliverables

  1. Non-blocking defer + visible code fallback in ThinkJava2
  2. Upstream issue for library-side optimizations (#3)
  3. Manual browser re-test of interactive editors and REPLs