{eb}'
+ return (f'
{logo}{eb}'
f'
{escape(ptitle)} ')
def main(argv: list[str] | None = None) -> int:
- ap = argparse.ArgumentParser(description="Build Firefly for Java by Example (EPUB + PDF).")
+ ap = argparse.ArgumentParser(description="Build jafly by example (EPUB + PDF).")
ap.add_argument("--config", default="book.yaml",
help="Manifest file at the repo root (default: book.yaml).")
ap.add_argument("--out", default=None,
@@ -141,44 +142,106 @@ def main(argv: list[str] | None = None) -> int:
(THEME / "pygments.css").read_text()]
items = _items_from_manifest(cfg, man, contents_label=contents_label)
+ covers = []
+ for kind, key, label_key, default_label in (
+ ("cover", "cover_png", "cover", "Cover"),
+ ("backcover", "back_cover_png", "back_cover", "Back cover"),
+ ):
+ if not cfg.get(key):
+ continue
+ path = BOOK / cfg[key]
+ if not path.is_file():
+ raise FileNotFoundError(f"Required {kind} artwork is missing: {path}")
+ label = cfg.get("labels", {}).get(label_key, default_label)
+ alt = cfg.get(label_key + "_alt", f"{label}: {cfg['title']}")
+ covers.append((kind, path, label, alt))
+
+ interior_assets = {}
+ if cfg.get("interior_logo"):
+ interior_assets["brand-logo"] = BOOK / cfg["interior_logo"]
+ for it in items:
+ if it.get("opener"):
+ interior_assets[f'opener-{it["id"]}'] = BOOK / it["opener"]
+ for path in interior_assets.values():
+ if not path.is_file():
+ raise FileNotFoundError(f"Required interior artwork is missing: {path}")
+
+ def interior_image(key: str, *, pdf: bool = False) -> str:
+ if key not in interior_assets:
+ return ""
+ path = interior_assets[key]
+ src = path.as_uri() if pdf else f"art/{key}{path.suffix}"
+ cls = "brand-logo" if key == "brand-logo" else "chapter-opener"
+ alt = "jafly by Firefly" if key == "brand-logo" else ""
+ return f'
'
+
# ---- EPUB ----
epub = EpubBuilder(title=cfg["title"], author=cfg["author"], language=cfg["language"],
- identifier=cfg["identifier"], css=css_text)
- cover_png = BOOK / cfg["cover_png"]
- if cover_png.exists():
- epub.add_file(cover_png, "art/cover.png", "cover-img", properties="cover-image")
+ identifier=cfg["identifier"], css=css_text,
+ publisher=cfg.get("publisher", ""), rights=cfg.get("rights", ""),
+ contents_title=contents_label)
+ for key, path in interior_assets.items():
+ epub.add_file(path, f"art/{key}{path.suffix}", key)
+ cover_docs = {}
+ for kind, path, label, alt in covers:
+ href = f"art/{kind}.png"
+ epub.add_file(path, href, f"{kind}-img",
+ properties="cover-image" if kind == "cover" else "")
+ cover_docs[kind] = Doc(id=kind, title=label, in_nav=False, kind=kind,
+ xhtml_body=f'
')
+ if "cover" in cover_docs:
+ epub.add_doc(cover_docs["cover"])
for it in items:
if it["kind"] == "toc":
body = _toc_html(items, href_fmt="{cid}.xhtml", label=contents_label)
epub.add_doc(Doc(id=it["id"], title=it["title"], xhtml_body=body,
in_nav=True, kind="toc"))
elif it["kind"] == "divider":
- body = _divider_html(it["eyebrow"], it["ptitle"])
+ body = _divider_html(it["eyebrow"], it["ptitle"], interior_image("brand-logo"))
epub.add_doc(Doc(id=it["id"], title=it["part"], xhtml_body=body,
in_nav=False, kind="divider", part=it["part"]))
else: # front | chapter
body = render_markdown(Path(it["path"]).read_text(encoding="utf-8"), BOOK)
+ if (it["kind"] == "chapter" or it.get("in_nav")) and not re.search(r"
)", body):
+ body = f'{escape(it["title"])} ' + body
+ body = interior_image("brand-logo" if it["id"] == "title" else f'opener-{it["id"]}') + body
epub.add_doc(Doc(id=it["id"], title=it["title"], xhtml_body=body,
in_nav=it.get("in_nav", True), kind=it["kind"],
part=it.get("part"), num=it.get("num")))
+ if "backcover" in cover_docs:
+ epub.add_doc(cover_docs["backcover"])
DIST.mkdir(exist_ok=True)
epub.build(DIST / f"{out_base}.epub")
# ---- PDF (single concatenated document) ----
parts_html: list[str] = []
- if cover_png.exists():
- parts_html.append(f')", body):
+ body = f'{escape(it["title"])} ' + body
+ body = interior_image("brand-logo" if it["id"] == "title" else f'opener-{it["id"]}', pdf=True) + body
parts_html.append(f'')
- full = ("{escape(cfg["title"])} '
+ f'{escape(d.title)} \n{links}\n\n'
- f''
+ f'\n\n')
def _nav(self) -> str:
@@ -90,8 +95,8 @@ def _nav(self) -> str:
return ('\n'
'Contents '
- f'Contents {items} {escape(self.contents_title)} '
+ f'{escape(self.contents_title)} {items} {escape(self.title)} '
f'{escape(self.author)} '
f'{self.language} '
+ f'{escape(self.publisher)} '
+ f'{escape(self.rights)} '
f'{"".join(man)} '
f'{spine} ')
diff --git a/build/gen_cover.py b/build/gen_cover.py
index 2fef766..f07266f 100644
--- a/build/gen_cover.py
+++ b/build/gen_cover.py
@@ -1,347 +1,54 @@
-"""Generate art/cover.svg and art/cover.png for *Firefly for Java by Example*.
+"""Validate or import canonical Framework by Firefly book artwork.
-A clean, self-contained typographic cover in the "Reactive Java at dusk" palette:
-a warm espresso base, amber-gold as the hero color (Java's warmth) and
-firefly-green as the spark (brand continuity) — a deliberate green+amber duotone,
-distinct from PyFly (light/green) and the Rust book (navy/amber). There is NO
-external logo dependency: the firefly mark is drawn inline as SVG, so the
-generator needs nothing under ~/Downloads or art/logo/. The canvas is
-1500 x 2100 px (7.5 x 9.25 in at 200 dpi) — the book's trim size.
-
-Run: build/.venv/bin/python build/gen_cover.py (writes art/cover.{svg,png})
+The shared digital brand kit owns the design. This tool cannot recreate the
+retired cover. Import all four localized covers with --source /path/to/11-Books/java,
+or run without arguments to validate the checked-in artwork. Missing PNGs are
+rasterized from the outlined SVG originals.
"""
from __future__ import annotations
-import math
+import argparse
from pathlib import Path
-from xml.sax.saxutils import escape as _xml_escape
+import shutil
+import xml.etree.ElementTree as ET
+
import cairosvg
+from PIL import Image
ART = Path(__file__).resolve().parents[1] / "art"
-W, H = 1500, 2100 # 7.5 x 9.25 in at 200 dpi
-
-# ---------------------------------------------------------------------------
-# Palette ("Reactive Java at dusk" — espresso base, amber hero, green spark)
-# ---------------------------------------------------------------------------
-INK = "#1B1610" # espresso base — background
-DEEP = "#2A2014" # deeper espresso layer — layering / accent nodes
-AMBER = "#E8A23A" # amber hero — Java's warmth
-AMBER_BRT = "#F4C24E" # bright amber — highlights / pulse glints
-AMBER_DEEP = "#C8801F" # deep amber — dim network lines / shadowed strokes
-GREEN = "#43B02A" # firefly green (spark) — brand continuity
-GREEN_DEEP = "#2C8A1C" # deep green
-GREEN_MID = "#2C8A1C" # mid green — node fills (kept name for callers)
-GREEN_DIM = "#2C8A1C" # dim green — subtle peer-ring lines
-CREAM = "#F3ECDD" # cream — body / title text on dark
-WHITE = "#F3ECDD" # title text (cream, kept name for callers)
-LIGHT = "#F3ECDD" # cream — "by Example" sits in green, motes in cream
-MUTED = "#C9B896" # warm muted — publisher / secondary text
-MUTED_LT = "#C9B896" # warm muted — subtitle
-
-FONT = "Avenir Next,Avenir,Helvetica Neue,Helvetica,Arial,sans-serif"
-
-
-# ---------------------------------------------------------------------------
-# Network motif helpers
-# ---------------------------------------------------------------------------
-def hex_points(cx: float, cy: float, r: float) -> str:
- """Return SVG polygon points string for a flat-top hexagon."""
- pts = []
- for i in range(6):
- angle = math.radians(30 + 60 * i) # flat-top orientation
- pts.append(f"{cx + r * math.cos(angle):.2f},{cy + r * math.sin(angle):.2f}")
- return " ".join(pts)
-
-
-def node(cx: float, cy: float, r: float, fill: str, stroke: str,
- stroke_w: float = 2.0, opacity: float = 1.0) -> str:
- pts = hex_points(cx, cy, r)
- op = f' opacity="{opacity}"' if opacity < 1.0 else ""
- return (
- f''
- # ambient bloom rings
- f''
- f' '
- # satellite motes — amber glints + one green spark
- f' '
- )
-
-
-# ---------------------------------------------------------------------------
-# Build SVG
-# ---------------------------------------------------------------------------
-def build_svg() -> str:
- # -------------------------------------------------------------------------
- # EDA Network motif (illustration zone: y = 80 ... 1080)
- # Hub: center, slightly above midpoint of illustration zone
- # -------------------------------------------------------------------------
- HUB_X, HUB_Y, HUB_R = 750, 580, 72
-
- # Satellite nodes: (cx, cy, radius, label)
- SATS = [
- (260, 210, 44, "CMD"),
- (650, 185, 40, "EVT"),
- (1080, 240, 44, "SAGA"),
- (1220, 540, 38, "Q"),
- (1110, 870, 44, "HTTP"),
- (390, 930, 40, "DATA"),
- (150, 610, 38, "MSG"),
- ]
-
- # Small accent nodes (no labels, atmospheric depth)
- ACCENT_NODES = [
- (500, 100, 22),
- (930, 130, 18),
- (1350, 360, 20),
- (1370, 760, 17),
- (980, 1020, 19),
- (200, 990, 16),
- (80, 400, 18),
- ]
-
- # Peer-to-peer connections (satellite ring, one hop)
- CONNECTIONS_PEER = [(0, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 0)]
-
- # SVG fragment list
- parts: list[str] = []
-
- # 1. Background fill
- parts.append(f'')
- for row in range(15):
- for col in range(10):
- gx = col * 185 - 60
- gy = row * 165 + (80 if col % 2 else 0) - 30
- pts = hex_points(gx, gy, 78)
- parts.append(f' ')
-
- # 3. Radial amber glow behind hub (defined inline; hoisted to )
- grad_id = "hubglow"
- parts.append(
- f''
- f' '
- )
- parts.append(f''
- )
- for (a, b) in CONNECTIONS_PEER:
- sx, sy = SATS[a][0], SATS[a][1]
- ex, ey = SATS[b][0], SATS[b][1]
- parts.append(f' ')
-
- # 5. Hub spokes — amber, brighter and thicker (the hero radiates)
- parts.append(
- f''
- )
- for (sx, sy, _, _) in SATS:
- parts.append(f' ')
-
- # 6. Event-pulse dots along spokes at 1/3 and 2/3
- PULSE_COLORS = [AMBER, GREEN, AMBER, GREEN, AMBER, GREEN, AMBER]
- for i, (sx, sy, _, _) in enumerate(SATS):
- col = PULSE_COLORS[i % len(PULSE_COLORS)]
- for t, r_dot, op_dot in [(0.32, 6, 0.90), (0.65, 4, 0.55)]:
- px = HUB_X + (sx - HUB_X) * t
- py = HUB_Y + (sy - HUB_Y) * t
- parts.append(
- f'{lbl} '
- )
-
- # 9. Hub node — the firefly mark sits at the network's heart.
- # Green rims for brand continuity, an amber inner ring for the hero glow.
- parts.append(node(HUB_X, HUB_Y, HUB_R + 16, "none", GREEN, 1.8, opacity=0.42))
- parts.append(node(HUB_X, HUB_Y, HUB_R + 4, "none", GREEN, 2.8, opacity=0.78))
- parts.append(node(HUB_X, HUB_Y, HUB_R, GREEN_MID, AMBER, 3.8))
- # the drawn firefly emblem, centered on the hub
- parts.append(firefly_mark(HUB_X, HUB_Y, scale=0.62))
-
- # 10. Atmospheric micro-labels (subtle, spaced out)
- MICRO = [
- (500, 76, "EVENTS"),
- (1320, 315, "ASYNC"),
- (160, 375, "REACTIVE"),
- (960, 1050, "CQRS"),
- ]
- for (mx, my, mlbl) in MICRO:
- parts.append(
- f'{mlbl} '
- )
-
- # -------------------------------------------------------------------------
- # Amber + green divider rules
- # -------------------------------------------------------------------------
- RULE_Y = 1110
- parts.append(
- f''
- f'FIREFLY SOFTWARE FOUNDATION '
- )
-
- # -------------------------------------------------------------------------
- # Title block
- # -------------------------------------------------------------------------
- TY = RULE_Y + 68 # baseline anchor of first title line
-
- # "Firefly for" — heavy, cream
- parts.append(
- f'Firefly for '
- )
-
- # "Java" — the BIG amber-gold hero (the standout word)
- parts.append(
- f'Java '
- )
-
- # Thin green spark separator under "Java" (brand continuity)
- RULE2_Y = TY + 326
- parts.append(
- f'by Example '
- )
-
- # Subtitle (two lines)
- SUB_Y = RULE2_Y + 188
- for i, line in enumerate([
- "Reactive Microservices with Spring Boot,",
- "WebFlux & the Firefly Framework",
- ]):
- parts.append(
- f'{_xml_escape(line)} '
- )
-
- # -------------------------------------------------------------------------
- # Assemble: hoist gradient elements into
- # -------------------------------------------------------------------------
- defs_tags = ("\n'
- f'{"".join(defs_parts)} \n'
- + "\n".join(body_parts)
- + "\n"
- )
- return svg
-
-
-def main() -> None:
+NAMES = ("cover", "cover-es", "back-cover", "back-cover-es")
+SIZE = (1500, 1850)
+
+
+def main(argv: list[str] | None = None) -> None:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--source", type=Path, help="Canonical brand-kit 11-Books/java directory")
+ args = parser.parse_args(argv)
+ source = args.source or ART
+ for name in NAMES:
+ svg = source / f"{name}.svg"
+ root = ET.fromstring(svg.read_bytes())
+ if [float(n) for n in root.get("viewBox", "").split()] != [0, 0, *SIZE]:
+ raise ValueError(f"{svg}: expected 1500 × 1850 viewBox (7.5 × 9.25 inch trim)")
+ if any(node.tag.rsplit("}", 1)[-1] == "text" for node in root.iter()):
+ raise ValueError(f"{svg}: canonical cover typography must be outlined")
+ png = source / f"{name}.png"
+ if png.exists():
+ with Image.open(png) as image:
+ if image.size != SIZE:
+ raise ValueError(f"{png}: expected {SIZE} pixels")
ART.mkdir(parents=True, exist_ok=True)
- svg = build_svg()
- (ART / "cover.svg").write_text(svg, encoding="utf-8")
- cairosvg.svg2png(
- bytestring=svg.encode(),
- write_to=str(ART / "cover.png"),
- output_width=W,
- output_height=H,
- )
- print("wrote cover.svg and cover.png")
+ for name in NAMES:
+ svg, png = source / f"{name}.svg", source / f"{name}.png"
+ target_svg, target_png = ART / svg.name, ART / png.name
+ if svg.resolve() != target_svg.resolve():
+ shutil.copyfile(svg, target_svg)
+ if png.exists():
+ if png.resolve() != target_png.resolve():
+ shutil.copyfile(png, target_png)
+ else:
+ cairosvg.svg2png(bytestring=svg.read_bytes(), write_to=str(target_png),
+ output_width=SIZE[0], output_height=SIZE[1])
+ print("Validated EN/ES front and back covers: 1500 × 1850, outlined canonical artwork")
if __name__ == "__main__":
diff --git a/build/gen_diagrams.py b/build/gen_diagrams.py
index de6b32f..e5d8964 100644
--- a/build/gen_diagrams.py
+++ b/build/gen_diagrams.py
@@ -1,4 +1,4 @@
-"""Generate the on-brand inline concept diagrams for *Firefly for Rust by Example*.
+"""Generate the on-brand inline concept diagrams for *jafly by example*.
These are the in-text technical figures (NOT the chapter openers — see
``gen_openers.py`` for those). Each diagram is a self-contained ````
@@ -7,14 +7,14 @@
Design language (shared with the cover, the openers, and ``theme/tokens.css``):
- * Cards are rounded rects ``rx=9..10``, cream fill ``#fdf6ea`` (or ``#fffaf0``),
- stroke ``#e0cda8`` width ``1.5``. Accent/highlight cards use fill ``#fff6e6``
- stroke ``#e0b96a``.
- * Connectors are rust ``#d4793a`` ``stroke-width=3`` with arrowheads drawn as
+ * Cards are rounded rects ``rx=9..10``, cream fill ``#f3f1eb`` (or ``#ffffff``),
+ stroke ``#bfb8ab`` width ``1.5``. Accent/highlight cards use fill ``#fff0d9``
+ stroke ``#ffb34a``.
+ * Connectors are rust ``#855414`` ``stroke-width=3`` with arrowheads drawn as
explicit ```` triangles (never ````).
- * Titles ``#2a1d10`` / ``#3a2a1c`` in the sans stack; sub-labels ``#7a6450``
- smaller; code/type tokens in the mono stack. Gold accents ``#f6a821`` /
- ``#ffc24a`` used sparingly.
+ * Titles ``#10110f`` / ``#272820`` in the sans stack; sub-labels ``#62645b``
+ smaller; code/type tokens in the mono stack. Gold accents ``#ffb34a`` /
+ ``#ffb34a`` used sparingly.
WeasyPrint SVG constraints (violating these breaks PDF rendering):
@@ -29,7 +29,8 @@
computed from a few constants, not hand-tuned per figure.
Run: python build/gen_diagrams.py (writes art/diagrams/*.svg, bare SVG)
-The book EMBEDS the inline ``figure_*()`` strings; the bare files are for preview.
+These legacy concept previews are not included in the Java manifests.
+Do not insert them into the manuscript without a separate technical review.
"""
from __future__ import annotations
@@ -40,26 +41,26 @@
ART = Path(__file__).resolve().parents[1] / "art" / "diagrams"
# --- palette (mirrors tokens.css + the existing inline figures) --------------
-FIELD = "#fdf6ea" # cream card fill
-FIELD2 = "#fffaf0" # lighter cream card fill
-ACCENT = "#fff6e6" # highlight/accent card fill
-ACCENT_S = "#e0b96a" # highlight/accent card stroke
-CARD_S = "#e0cda8" # default card stroke
-RUST = "#d4793a" # connectors, accent stroke
-RUST_D = "#b5531f" # deeper rust (arrowheads/emphasis)
-AMBER = "#f6a821"
-AMBER_B = "#ffc24a"
+FIELD = "#f3f1eb" # cream card fill
+FIELD2 = "#ffffff" # lighter cream card fill
+ACCENT = "#fff0d9" # highlight/accent card fill
+ACCENT_S = "#ffb34a" # highlight/accent card stroke
+CARD_S = "#bfb8ab" # default card stroke
+RUST = "#855414" # connectors, accent stroke
+RUST_D = "#855414" # deeper rust (arrowheads/emphasis)
+AMBER = "#ffb34a"
+AMBER_B = "#ffb34a"
GREEN = "#1f8a4c" # query / success accent (matches admin "green" badges)
GREEN_BG = "#ecf9f0"
BLUE = "#2563c9" # command / note accent (matches admin "blue" badges)
BLUE_BG = "#eef4ff"
RED = "#b03a2e" # failure / compensation (matches existing saga figs)
RED_BG = "#fdecea"
-TITLE = "#2a1d10" # card titles
-TITLE2 = "#3a2a1c" # secondary titles
-SUB = "#7a6450" # sub-labels
-LANE_BG = "#f7ecd8" # swimlane background
-LANE_S = "#e6d4b0" # swimlane stroke
+TITLE = "#10110f" # card titles
+TITLE2 = "#272820" # secondary titles
+SUB = "#62645b" # sub-labels
+LANE_BG = "#f3f1eb" # swimlane background
+LANE_S = "#bfb8ab" # swimlane stroke
FONT = "Avenir Next,Avenir,Helvetica Neue,Helvetica,Arial,sans-serif"
MONO = "SF Mono,JetBrains Mono,Menlo,Consolas,monospace"
@@ -100,7 +101,7 @@ def card(x, y, w, h, title, *, sub=None, mono=False, accent=False,
out = [
# soft drop shadow plate, then the card
f''
- )
-
-
-def defs() -> str:
- # NOTE: WeasyPrint's SVG engine drops gradients when a /
- # shares the , and resolves objectBoundingBox gradients unreliably.
- # So we use ONLY userSpaceOnUse gradients here and fake glows with stacked
- # translucent circles.
- return (
- ''
- f''
- f' '
- # the darker panel gradient:
- f''
- f' '
- # root-space vertical amber gradient for the accent bar (the hero spark):
- f''
- f' '
- ' '
- )
-
-
-def emblem() -> str:
- """The constant glowing-firefly emblem on the panel (right), matching the
- cover's bioluminescent mark."""
- cx, cy = 601, 150
- return (
- f''
- # ambient bloom on the panel
- f''
- f' '
- # satellite motes (one bioluminescent green, matching the cover)
- f' '
- )
-
-
-def frame(num: str) -> str:
- """Forest-green field, green accent bar, darker panel + motes, kicker."""
- return (
- f'{esc(num)} '
- f'')
- for (sx, sy, _) in sats:
- parts.append(f' ')
- # peer ring (satellite to next satellite), dim
- parts.append(f'')
- for i in range(len(sats)):
- a, b = sats[i], sats[(i + 1) % len(sats)]
- parts.append(f' ')
- # pulse dots travelling along the spokes
- for j, (sx, sy, _) in enumerate(sats):
- col = AMBER if j % 2 == 0 else GREEN_B
- for t, r_dot, op in [(0.34, 4.5, 0.9), (0.66, 3.0, 0.55)]:
- px = hub[0] + (sx - hub[0]) * t
- py = hub[1] + (sy - hub[1]) * t
- parts.append(f'F '
- )
- return "".join(parts)
-
-
def build_one(num: int) -> str:
- """num is the 1-based chapter number (1..N_CHAPTERS)."""
- kicker = f"CHAPTER {num}"
- label = f"Firefly for Java by Example — opener for chapter {num}"
- return (
- header(label) + defs() + frame(kicker)
- + constellation(seed=1000 + num)
- + emblem() + " \n"
- )
+ logo = base64.b64encode((ROOT / "art/brand/logo-dark.png").read_bytes()).decode()
+ return (f''
+ '{num:02d} '
+ f' \n')
def main() -> None:
ART.mkdir(parents=True, exist_ok=True)
for num in range(1, N_CHAPTERS + 1):
(ART / f"ch{num:02d}.svg").write_text(build_one(num), encoding="utf-8")
- print(f"wrote {N_CHAPTERS} chapter openers (ch01..ch{N_CHAPTERS:02d}) to {ART}")
+ print(f"Wrote {N_CHAPTERS} approved-brand chapter openers to {ART}")
if __name__ == "__main__":
diff --git a/build/md.py b/build/md.py
index c09e2c0..26e2fd9 100644
--- a/build/md.py
+++ b/build/md.py
@@ -1,4 +1,4 @@
-"""Markdown -> HTML for *Firefly for Java by Example*.
+"""Markdown -> HTML for *jafly by example*.
Custom block directives on top of python-markdown:
::: figure | (single line; inlines the SVG)
@@ -86,21 +86,21 @@ def _listing(self, file_label: str, cap: str | None, code: str) -> str:
# Professional inline SVG icons injected into callout titles (no emoji).
_ADM_ICON = {
"note": ''
- ' ',
+ ''
' ',
+ 'c.06-.52.33-.99.78-1.32A5.6 5.6 0 0 0 10 2.4z" fill="none" stroke="#855414" stroke-width="1.5"/>'
+ ''
- ' ',
+ ''
' ',
}
diff --git a/build/pdf.py b/build/pdf.py
index 368478f..070857c 100644
--- a/build/pdf.py
+++ b/build/pdf.py
@@ -6,5 +6,5 @@
def render_pdf(full_html: str, base_url: Path, css_paths: list[Path], out: Path) -> Path:
out = Path(out); out.parent.mkdir(parents=True, exist_ok=True)
HTML(string=full_html, base_url=str(base_url)).write_pdf(
- str(out), stylesheets=[CSS(filename=str(p)) for p in css_paths])
+ str(out), stylesheets=[CSS(filename=str(p)) for p in css_paths], custom_metadata=True)
return out
diff --git a/build/requirements.txt b/build/requirements.txt
index fd80996..8a11c5b 100644
--- a/build/requirements.txt
+++ b/build/requirements.txt
@@ -3,4 +3,5 @@ markdown==3.10.3
pygments==2.21.0
pyyaml==6.0.3
cairosvg==2.9.1
+pillow==12.3.0
pytest==9.1.1
diff --git a/build/verify_code.py b/build/verify_code.py
index 30c618d..5aac7e9 100644
--- a/build/verify_code.py
+++ b/build/verify_code.py
@@ -1,7 +1,7 @@
"""Verify that every ``::: listing `` whose label ends in .java / .xml is
a verbatim slice of the file ``/`` in the built Maven reactor.
-This is the load-bearing guarantee of *Firefly for Java by Example*: the code on
+This is the load-bearing guarantee of *jafly by example*: the code on
the page is exactly the code that compiles and runs in the sample reactor, never
a hand-edited paraphrase that has silently drifted.
diff --git a/manuscript-es/00-front/00-title.md b/manuscript-es/00-front/00-title.md
index f768ae2..7e9b456 100644
--- a/manuscript-es/00-front/00-title.md
+++ b/manuscript-es/00-front/00-title.md
@@ -1,5 +1,5 @@
-# Firefly para Java con ejemplos {.chtitle}
+# jafly by example {.chtitle}
-### Microservicios reactivos con Spring Boot, WebFlux y el framework Firefly
+### De Spring Boot a una arquitectura empresarial conectada
**Firefly Software Foundation**
diff --git a/manuscript/00-front/00-title.md b/manuscript/00-front/00-title.md
index 07273c1..f915952 100644
--- a/manuscript/00-front/00-title.md
+++ b/manuscript/00-front/00-title.md
@@ -1,5 +1,5 @@
-# Firefly for Java by Example {.chtitle}
+# jafly by example {.chtitle}
-### Reactive Microservices with Spring Boot, WebFlux & the Firefly Framework
+### From Spring Boot to a connected enterprise architecture
**Firefly Software Foundation**
diff --git a/tests/test_covers.py b/tests/test_covers.py
new file mode 100644
index 0000000..e2041ed
--- /dev/null
+++ b/tests/test_covers.py
@@ -0,0 +1,194 @@
+"""Cover integration: localization, reading order, metadata and full-page layout."""
+from pathlib import Path
+import sys
+import xml.etree.ElementTree as ET
+import zipfile
+
+import pytest
+import yaml
+from PIL import Image
+from weasyprint import HTML
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "build"))
+import build as book_build
+import gen_cover
+
+
+@pytest.fixture
+def edition(tmp_path, monkeypatch):
+ art = tmp_path / "art"
+ art.mkdir()
+ manuscript = tmp_path / "manuscript"
+ manuscript.mkdir()
+ (manuscript / "chapter.md").write_text("# A short chapter\n\nBody text.")
+ for name, color in (("front", "red"), ("back", "blue")):
+ Image.new("RGB", (1500, 1850), color).save(art / f"{name}.png")
+ config = {
+ "title": "Java & arquitectura", "author": "Firefly Software Foundation",
+ "publisher": "Firefly Software Foundation", "language": "es",
+ "identifier": "urn:uuid:cover-test", "rights": "Apache-2.0",
+ "cover_png": "art/front.png", "back_cover_png": "art/back.png",
+ "cover_alt": "Portada: Java & arquitectura", "back_cover_alt": "Contraportada: Java",
+ "trim_width": "7.5in", "trim_height": "9.25in",
+ "manuscript_dir": "manuscript", "output_basename": "edition",
+ "labels": {"contents": "Contenido", "cover": "Portada", "back_cover": "Contraportada"},
+ "front": [], "parts": [{"title": "Parte I — Arquitectura", "chapters": [
+ {"id": "ch1", "file": "chapter.md", "num": 1, "title": "A short chapter"}]}],
+ }
+ (tmp_path / "book.yaml").write_text(yaml.safe_dump(config))
+ monkeypatch.setattr(book_build, "BOOK", tmp_path)
+ monkeypatch.setattr(book_build, "DIST", tmp_path / "dist")
+ return tmp_path, config
+
+
+def test_localized_covers_bookend_epub_spine_and_preserve_navigation(edition):
+ root, _ = edition
+ book_build.main([])
+ ns = {"opf": "http://www.idpf.org/2007/opf", "dc": "http://purl.org/dc/elements/1.1/",
+ "x": "http://www.w3.org/1999/xhtml"}
+ with zipfile.ZipFile(root / "dist/edition.epub") as archive:
+ opf = ET.fromstring(archive.read("OEBPS/content.opf"))
+ spine = [node.attrib["idref"] for node in opf.findall("opf:spine/opf:itemref", ns)]
+ assert spine == ["cover", "toc", "parte-i", "ch1", "backcover"]
+ assert opf.findtext("opf:metadata/dc:publisher", namespaces=ns) == "Firefly Software Foundation"
+ assert opf.findtext("opf:metadata/dc:rights", namespaces=ns) == "Apache-2.0"
+ assert opf.findtext("opf:metadata/dc:language", namespaces=ns) == "es"
+ cover_images = opf.findall("opf:manifest/opf:item[@properties='cover-image']", ns)
+ assert len(cover_images) == 1
+ for filename, expected in (("cover.xhtml", "Portada: Java & arquitectura"),
+ ("backcover.xhtml", "Contraportada: Java")):
+ page = ET.fromstring(archive.read(f"OEBPS/{filename}"))
+ assert page.find(".//x:img", ns).attrib["alt"] == expected
+ nav = ET.fromstring(archive.read("OEBPS/nav.xhtml"))
+ assert nav.find(".//x:h1", ns).text == "Contenido"
+ assert "ch1.xhtml" in archive.read("OEBPS/nav.xhtml").decode()
+
+
+def test_pdf_covers_fill_trim_without_headers_or_extra_pages(edition, monkeypatch):
+ root, _ = edition
+ rendered = []
+ pdf_options = []
+ original = HTML.write_pdf
+
+ def capture(self, *args, **kwargs):
+ pdf_options.append(kwargs)
+ rendered.append(self.render(stylesheets=kwargs.get("stylesheets")))
+ return original(self, *args, **kwargs)
+
+ monkeypatch.setattr(HTML, "write_pdf", capture)
+ book_build.main([])
+ document = rendered[0]
+ assert len(document.pages) == 5 # front, contents, part, chapter, back
+ assert document.metadata.title == "Java & arquitectura"
+ assert document.metadata.custom["publisher"] == "Firefly Software Foundation"
+ assert pdf_options[0].get("custom_metadata") is True
+ for page in (document.pages[0], document.pages[-1]):
+ assert (page.width, page.height) == (720, 888)
+ images = [box for box in page._page_box.descendants()
+ if getattr(box, "element_tag", None) == "img"]
+ assert len(images) == 1
+ image = images[0]
+ assert (image.position_x, image.position_y, image.width, image.height) == (0, 0, 720, 888)
+ assert not any(getattr(box, "text", "").strip() for box in page._page_box.descendants())
+
+
+def test_declared_missing_cover_fails_instead_of_publishing_incomplete_book(edition):
+ root, _ = edition
+ (root / "art/back.png").unlink()
+ with pytest.raises(FileNotFoundError, match="back.png"):
+ book_build.main([])
+
+
+def test_cover_tool_refuses_missing_canonical_artwork(tmp_path, monkeypatch):
+ monkeypatch.setattr(gen_cover, "ART", tmp_path / "art")
+ monkeypatch.setattr(sys, "argv", ["gen_cover.py", "--source", str(tmp_path / "missing")])
+ with pytest.raises(FileNotFoundError):
+ gen_cover.main()
+
+
+def test_cover_tool_imports_localized_canonical_assets_without_redesign(tmp_path, monkeypatch):
+ source = tmp_path / "canonical"
+ source.mkdir()
+ target = tmp_path / "art"
+ svg = '= 74
+ assert images[0].position_x + images[0].width <= 646
+ assert images[0].position_y + images[0].height < 806
+
+
+def test_manifest_chapter_heading_is_visible_once_when_manuscript_has_no_title(edition):
+ root, config = edition
+ (root / "manuscript/chapter.md").write_text("Body text without a duplicated manuscript title.")
+ config["parts"][0]["chapters"][0]["title"] = "Arquitectura & límites"
+ (root / "book.yaml").write_text(yaml.safe_dump(config))
+ book_build.main([])
+ with zipfile.ZipFile(root / "dist/edition.epub") as archive:
+ doc = ET.fromstring(archive.read("OEBPS/ch1.xhtml"))
+ headings = doc.findall(".//{http://www.w3.org/1999/xhtml}h1")
+ assert len(headings) == 1
+ assert headings[0].text == "1. Arquitectura & límites"
+ assert headings[0].attrib["class"] == "chtitle"
diff --git a/theme/book.css b/theme/book.css
index b9b35d3..96266ff 100644
--- a/theme/book.css
+++ b/theme/book.css
@@ -19,29 +19,29 @@ h1,h2,h3,h4{ color:var(--ink); line-height:1.22; font-weight:800; }
h1.chtitle{ font-size:2.3rem; line-height:1.08; margin:.1rem 0 1.15rem; color:var(--amber-deep);
letter-spacing:-.015em; }
h2{ font-size:1.4rem; font-weight:800; color:var(--bronze); margin:2rem 0 .7rem;
- padding-bottom:.35rem; border-bottom:2px solid #f0e2c8; }
-h3{ font-size:1.08rem; font-weight:700; margin:1.35rem 0 .4rem; color:#3a2c14; }
+ padding-bottom:.35rem; border-bottom:2px solid var(--rule); }
+h3{ font-size:1.08rem; font-weight:700; margin:1.35rem 0 .4rem; color:var(--ink-soft); }
h2+p,h3+p{ margin-top:0; }
/* ============ text ============ */
p{ margin:0 0 .9rem; }
-strong,b{ color:#3a2c14; font-weight:700; }
+strong,b{ color:var(--ink-soft); font-weight:700; }
em{ color:inherit; }
-a{ color:var(--green-deep); text-decoration:underline; text-decoration-color:#bcd9a8;
+a{ color:var(--amber-deep); text-decoration:underline; text-decoration-color:var(--code-border);
text-underline-offset:2px; }
ul,ol{ margin:.3rem 0 1rem; padding-left:1.45rem; }
li{ margin:.28rem 0; }
-li::marker{ color:var(--green); }
+li::marker{ color:var(--amber-deep); }
hr{ border:none; border-top:1px solid var(--rule); margin:1.7rem 0; }
-/* inline code — warm tint, firefly-green text */
-code{ background:#f3ecda; color:#2c6e22; padding:.06em .36em; border-radius:4px;
+/* inline code — paper tint, charcoal text */
+code{ background:var(--code-bg); color:var(--ink-soft); padding:.06em .36em; border-radius:4px;
font-family:"SF Mono","JetBrains Mono",Menlo,Consolas,monospace; font-size:.85em;
word-break:break-all; overflow-wrap:anywhere; }
/* ============ code listings ============ */
.listing{ margin:1.2rem 0; }
-.filetab{ display:inline-block; background:#f3e9d2; color:var(--bronze);
+.filetab{ display:inline-block; background:var(--code-bg); color:var(--bronze);
font:600 .72rem/1 "SF Mono","JetBrains Mono",Menlo,monospace;
padding:.44rem .72rem; border:1px solid var(--code-border); border-bottom:none;
border-radius:8px 8px 0 0; }
@@ -66,35 +66,35 @@ figcaption b,figcaption strong{ color:var(--bronze); }
/* ============ tables ============ */
table{ width:100%; border-collapse:collapse; margin:1.15rem 0; font-size:.9rem; line-height:1.5; }
-th,td{ border:1px solid #e7dcc4; padding:.5rem .72rem; text-align:left; vertical-align:top; }
-thead th{ background:#fbf6ea; color:#5a4314; font-weight:700; }
-tbody tr:nth-child(even){ background:#fbf6ea; }
-td code,th code{ background:#f3ecda; }
+th,td{ border:1px solid var(--code-border); padding:.5rem .72rem; text-align:left; vertical-align:top; }
+thead th{ background:var(--code-bg); color:var(--ink-soft); font-weight:700; }
+tbody tr:nth-child(even){ background:var(--code-bg); }
+td code,th code{ background:var(--code-bg); }
/* ============ callouts ============ */
.admonition{ border-radius:10px; padding:.8rem 1rem; margin:1.2rem 0; font-size:.92rem;
- line-height:1.6; border:1px solid var(--rule); border-left-width:4px; background:#f6f8f1; }
+ line-height:1.6; border:1px solid var(--rule); border-left-width:4px; background:var(--page); }
.admonition>:last-child{ margin-bottom:0; }
.admonition>:first-child{ margin-top:0; }
.admonition-title{ font-weight:800; font-size:.7rem; letter-spacing:.08em; text-transform:uppercase;
margin:0 0 .35rem; display:flex; align-items:center; gap:.45rem; }
.adm-ico{ flex:none; width:15px; height:15px; }
-.admonition.note{ background:var(--note-bg); border-color:#cfe3fb; border-left-color:var(--note); }
+.admonition.note{ background:var(--note-bg); border-color:var(--rule); border-left-color:var(--note); }
.admonition.note>.admonition-title{ color:var(--note); }
-.admonition.tip{ background:#eefaed; border-color:#cdeccd; border-left-color:var(--tip); }
+.admonition.tip{ background:var(--amber-soft); border-color:var(--code-border); border-left-color:var(--tip); }
.admonition.tip>.admonition-title{ color:var(--tip); }
-.admonition.warning{ background:var(--warn-bg); border-color:#fcd9c2; border-left-color:var(--warn); }
+.admonition.warning{ background:var(--warn-bg); border-color:var(--code-border); border-left-color:var(--warn); }
.admonition.warning>.admonition-title{ color:var(--warn); }
-.admonition.spring{ background:#f1fae6; border-color:#d4e9bd; border-left-color:var(--green); }
-.admonition.spring>.admonition-title{ color:var(--green-deep); }
+.admonition.spring{ background:var(--page); border-color:var(--code-border); border-left-color:var(--amber-deep); }
+.admonition.spring>.admonition-title{ color:var(--amber-deep); }
/* ============ recap / exercises (applied to the section H2) ============ */
-h2.recap,h2.exercises{ color:var(--bronze); border-bottom-color:#f0e2c8;
+h2.recap,h2.exercises{ color:var(--bronze); border-bottom-color:var(--rule);
display:flex; align-items:center; gap:.5rem; }
h2.recap::before{ content:"\2713"; color:var(--amber-deep); font-size:1.05rem; }
h2.exercises::before{ content:"\270E"; color:var(--amber-deep); font-size:1.05rem; }
-/* ============ Table of Contents (Packt style) ============ */
+/* ============ Table of Contents (grouped by part) ============ */
.toc{ padding:0 0 2.5rem; }
.toc h1.chtitle{ margin-bottom:1.4rem; }
.toc-part-group{ margin:1.5rem 0 .4rem; }
@@ -109,7 +109,7 @@ ol.toc-chapters > li{ margin:.18rem 0; }
.toc-link{ /* readable chapter row; leader fills to the page number */
display:block; color:var(--ink); text-decoration:none; font-size:.98rem; line-height:1.75;
}
-.toc-link:hover{ color:var(--green-deep); }
+.toc-link:hover{ color:var(--amber-deep); }
/* ============ EPUB nav (part-grouped) ============ */
nav#toc ol{ list-style:none; padding-left:1rem; }
@@ -133,3 +133,12 @@ nav#toc li.toc-part > ol a{ font-weight:400; color:var(--ink); }
font-size:2.9rem; line-height:1.1; font-weight:800; color:var(--bronze);
letter-spacing:-.02em; margin:0; border:none; padding:0;
}
+
+/* Standalone cover documents also scale to the EPUB reading viewport. */
+.cover-page{ margin:0; padding:0; }
+.cover-page img{ display:block; width:100%; height:auto; margin:0; }
+
+/* Canonical outlined identity and restrained, numbered chapter openers. */
+.brand-logo{ display:block; width:1.5in; height:auto; margin:0 0 1.2rem; }
+.part-divider-inner .brand-logo{ width:2in; margin:0 auto 2rem; }
+.chapter-opener{ display:block; width:100%; height:auto; margin:0 0 1.2rem; break-after:avoid; }
diff --git a/theme/print.css b/theme/print.css
index c0a1cb3..f9c549b 100644
--- a/theme/print.css
+++ b/theme/print.css
@@ -2,9 +2,9 @@
@page{
size: 7.5in 9.25in;
margin: 0.82in 0.78in 0.86in;
- @bottom-center{ content: counter(page); font:9pt -apple-system,"Segoe UI",sans-serif; color:#9aa6a0; }
+ @bottom-center{ content: counter(page); font:9pt -apple-system,"Segoe UI",sans-serif; color:#62645b; }
@top-center{ content: string(runhead); font:8pt -apple-system,"Segoe UI",sans-serif;
- letter-spacing:.12em; text-transform:uppercase; color:#a7b0a0; }
+ letter-spacing:.12em; text-transform:uppercase; color:#62645b; }
}
@page :first{ @top-center{ content:none; } @bottom-center{ content:none; } }
@@ -12,8 +12,16 @@ html{ font-size: 11pt; } /* map rem-based sizes to print */
body{ background:#fff; }
/* the cover image is its own first page (no header/number) */
-.cover-page{ break-after:page; text-align:center; }
-.cover-page img{ width:100%; height:auto; }
+@page cover{
+ size: 7.5in 9.25in;
+ margin:0;
+ @top-center{ content:none; }
+ @bottom-center{ content:none; }
+}
+.cover-page{ page:cover; break-before:page; break-after:page; margin:0; padding:0; width:7.5in; height:9.25in; }
+.cover-page img{ display:block; width:7.5in; height:9.25in; max-width:none; margin:0; }
+.cover-page.cover{ break-before:auto; }
+.cover-page.backcover{ break-after:auto; }
/* each front-matter doc and each chapter starts on a fresh page */
.chapter{ break-before:page; padding-bottom:0; }
@@ -21,6 +29,7 @@ body{ background:#fff; }
/* running head from the chapter title */
h1.chtitle{ string-set: runhead content(text); }
+section#title h1.chtitle{ string-set: runhead ""; }
/* keep blocks intact across page boundaries */
table,figure.fig,.admonition{ break-inside:avoid; }
@@ -36,12 +45,12 @@ pre.code,.code pre{ white-space:pre-wrap; overflow-wrap:anywhere; word-break:bre
/* ============ Contents page (print) ============ */
/* start on its own page; suppress the running head (no chtitle here) */
section.toc{ break-before:page; break-after:page; }
-section.toc h1.chtitle{ string-set:runhead "Contents"; }
+section.toc h1.chtitle{ string-set:runhead content(text); }
/* dotted leader + the resolved page number of the linked chapter */
.toc-link{ text-decoration:none; color:var(--ink); }
.toc-link::after{
content: leader('.') ' ' target-counter(attr(href url), page);
- color:#6b7768;
+ color:#62645b;
}
/* ============ Part-divider page (print) ============ */
diff --git a/theme/tokens.css b/theme/tokens.css
index 0dd4413..a19e6ec 100644
--- a/theme/tokens.css
+++ b/theme/tokens.css
@@ -1,10 +1,7 @@
:root{
- /* "Reactive Java at dusk" — warm espresso pages, amber-gold accent, green spark.
- Variable NAMES are stable; only the values are warm. */
- --green:#43b02a; --green-bright:#5fd13a; --lime:#86dd4c; --lime-soft:#a7e76a;
- --green-deep:#2c8a1c; --green-ink:#1f5e16;
- --amber:#e8a23a; --amber-soft:#f4c24e; --amber-deep:#b5791a; --bronze:#8a5a12;
- --ink:#211a10; --ink-soft:#4a3b22; --muted:#8a7a58; --page:#fffdf5;
- --code-bg:#faf6ec; --code-border:#e7dcc4; --rule:#ece3d2;
- --note:#1f6fd6; --note-bg:#eef6ff; --tip:#2f8f3f; --warn:#c2410c; --warn-bg:#fff4ec;
+ /* Framework by Firefly: paper, charcoal and amber. Gold remains readable on light pages. */
+ --amber:#ffb34a; --amber-soft:#fff0d9; --amber-deep:#855414; --bronze:#855414;
+ --ink:#10110f; --ink-soft:#272820; --muted:#62645b; --page:#f3f1eb;
+ --code-bg:#f3f1eb; --code-border:#bfb8ab; --rule:#dcd8ce;
+ --note:#272820; --note-bg:#f3f1eb; --tip:#855414; --warn:#9c3d1c; --warn-bg:#fff0e7;
}
+