Book Writing Workspace

Book Writing Workspace

Create and maintain a reusable manuscript workspace with folders, writing agents, instructions, review rules, and optional Markdown -> Re:VIEW -> PDF support.

When to use

• Book writing, technical writing, 執筆プロジェクト, Re:VIEW
• Assessing or standardizing an existing book manuscript repository
• Creating a new technical writing project from templates when needed
• Setting up Markdown → Re:VIEW → PDF workflow
• Upgrading an existing manuscript workspace so it can generate Re:VIEW output and printable PDFs
• Standardizing chapter/section file layout, writing rules, review workflow, and page allocation
• Adding optional Re:VIEW/PDF support without turning the writing workspace into a general Git or publishing operations toolkit

Quick Start

Start by assessing the manuscript workspace, even when creating a new project:

1. Confirm the main manuscript lives in sections/ and uses one file per section. 2. Confirm outlines or key points live separately from final manuscript files. 3. Confirm chapter intro files use kebab-case naming (e.g. 00-introduction/00-introduction.md). 4. Confirm writing, heading, notation, page allocation, and review rules are available. 5. Decide whether Re:VIEW/PDF output is needed for this project; keep it optional unless the workflow requires it.

Operating Workflow

When the workspace already exists, do not stop at setup-oriented advice. This skill should also support:

1. Normalizing manuscript folders and section naming. 2. Keeping outlines, drafts, final manuscript, and images aligned by chapter. 3. Running focused writing and review loops until P1/P2 issues are resolved. 4. Checking word count targets and source confidence before finalizing text. 5. Enabling Re:VIEW/PDF support only when the project needs reproducible output.

Bootstrap Workflow

Use the setup script only when creating a new workspace or adding missing structure deliberately.

python scripts/setup_workspace.py `
  --name "project-name" `
  --title "Book Title" `
  --path "D:\target\path" `
  --chapters 8

# Include Re:VIEW/PDF scaffolding only when needed.
python scripts/setup_workspace.py `
  --name "project-name" `
  --title "Book Title" `
  --path "D:\target\path" `
  --chapters 8 `
  --with-review

1. Gather info: Project name, title, location, chapter count 2. Run script: scripts/setup_workspace.py 3. Review output: Confirm README, agents, instructions, and docs were created 4. Customize: Edit docs/page-allocation.md, docs/schedule.md, and .github/copilot-instructions.md. If --with-review is used, also customize config/review-metadata/project.yml.

Git workflows are project-specific. Do not add generic commit/push prompts here; follow the repository's existing version-control conventions.

Metadata, migration, converter verification, and sync-back rules live in references. Keep the main SKILL focused on manuscript structure and writing workflow.

Generated Workspace

• Manuscript folders under keypoints/, sections/, and images/
• AI workflow files under .github/agents/ and .github/instructions/
• Project docs such as README.md, docs/page-allocation.md, and docs/schedule.md
• Helper scripts such as scripts/count_chars.py
• Optional Re:VIEW scripts and metadata when --with-review is used

Recommended Writing Unit

• Use 1 file = 1 section as the default manuscript unit.
• Keep chapter intro in {NN}-{slug}/{NN}-{slug}.md and section files alongside it.
• For PDF/Re:VIEW output, heading levels define hierarchy, while file split mainly improves authoring and review workflow.

Agents Overview

Dependencies

Reference Map

Done Criteria

• [ ] Workspace folder structure created
• [ ] Writing and review agents deployed to .github/agents/
• [ ] docs/page-allocation.md configured
• [ ] README.md and docs/schedule.md customized
• [ ] Manuscript files follow the chapter/section naming convention
• [ ] scripts/count_chars.py works for target manuscript files
• [ ] Re:VIEW/PDF output is either explicitly out of scope or enabled and verified

Customization Points

These files are expected to be edited immediately after workspace creation.

Project Metadata

Writing Management

Outline vs Manuscript Presentation Rules

If the workspace uses both outline files and final manuscript files, define early which ideas should be planned as diagrams and which should be rendered as tables in the full text.

Recommended Rule

• Put diagram candidates in the outline or key-points side before drafting the full prose
• For each diagram candidate, capture the reader goal, not just the topic name
• Use tables in the final manuscript when comparing 3 or more terms, roles, plans, tools, or options
• Use diagrams for flow, direction, sequence, hierarchy, or source/target relationships
• Do not leave comparison-heavy sections as long bullet lists if a table would let the reader re-scan faster

Why This Matters

Diagram needs are often discovered too late if they are deferred until section drafting. Likewise, comparison-heavy sections become harder to read when they stay as prose or bullets instead of being normalized into tables.

Verification and Diagram Language Rules

Before large-scale drafting begins, decide two policy points explicitly.

Recommended Rule

• Keep unverified items in outline or key-points material as explicit follow-up notes
• Do not let unresolved facts drift into final prose as plausible-sounding explanation
• Decide whether diagrams should default to the manuscript language, and document the limited cases where original-language labels stay visible
• Keep operation names or official feature names in their original language only when readers are expected to recognize them that way

Why This Matters

Speculative prose becomes expensive to detect once it has spread across multiple chapters. Likewise, diagrams often drift into all-English labeling even when the manuscript is written for another language audience, which creates avoidable reading friction.

Automation

Metadata Layer

If the workspace uses a shared metadata layer for Re:VIEW/PDF output, separate stable defaults from project-specific fields.

Recommended Rule

• Put only stable shared defaults in config/review-metadata/common.yml
• Keep author lists, publisher, title, subtitle, and other project-specific fields in config/review-metadata/project.yml
• Do not place contributor-specific names in the common metadata file
• Keep cover author typography settings such as suffix, font size, and position in metadata/helper defaults
• If the repo contains a series, compare title patterns across books before finalizing one book's booktitle or subtitle
• Regenerate config.yml and cover assets from the metadata layer instead of editing generated files by hand

Why This Matters

People, publisher details, title wording, and cover readability vary per project. If they are stored in a common metadata file or fixed only in exported images, they leak across projects and are easy to forget during setup or retrofits.

LaTeX Style Injection Point

Build scripts that use vvakame/review Docker images typically copy the gem's default review-jsbook files into sty/ at the start of each build, overwriting any local edits.

Rule

• Never edit `sty/review-jsbook.cls` or `sty/review-base.sty` directly — changes will be lost
• Place all LaTeX customizations in the custom sty content that the build script injects as sty/review-custom.sty
• In PowerShell build scripts, this is typically a heredoc variable (e.g. $customStyContent) written to a file before the Docker run
• In shell-based workflows, append to sty/review-style.sty after the gem copy step

Why This Matters

If you add \usepackage{xurl} or other fixes directly to sty/review-jsbook.cls, the next build silently reverts those changes. The fix appears to work in manual testing but fails in CI or clean builds.

Heading Rename Safety

When changing chapter titles that are also reflected in folder names, file names, or planning docs, do not stop at the first rename.

Recommended Rule

• Rename the manuscript heading and every synchronized path together
• Check that the old folder or file no longer exists physically
• Grep the old chapter title after the rename to catch leftovers in docs, agents, or instructions
• Rebuild Re:VIEW/PDF output and confirm the old path is not still being converted

Why This Matters

If the old chapter path remains on disk, build scripts may pick up both old and new files. That can produce duplicated chapters or stale generated output that is hard to diagnose from PDF alone.

Sync-Back from Final Manuscripts to Author Drafts

If your workflow keeps both final manuscripts and author draft folders, define a clear sync-back rule before copying text from the final manuscript side back into drafts.

Recommended Rule

• Sync the prose that should stay aligned between final manuscript and draft
• Preserve draft-local relative asset paths if the draft folder uses a different image layout
• Do not blindly copy generated output back into draft folders
• Do not update unrelated sibling draft files just because they share the same author folder
• Keep keypoints, notes, and draft-only planning files as separate sources unless the task explicitly says to synchronize them
• After sync-back, verify matched manuscript pairs with git diff --no-index, hashes, or an equivalent exact comparison
• Treat chapter intro files such as ch*-00_*.md as mandatory sync-check targets because they drift easily

Typical Example

If the final manuscript uses:

![Azure Ops Dashboard GUI](images/image.png)

but the author draft keeps the image next to the draft file:

![Azure Ops Dashboard GUI](image.png)

then sync the prose but preserve the draft-local image path instead of copying the final path verbatim.

Why This Matters

Draft folders often serve as working sources for individual authors. They may have:

• different relative paths
• rough notes not intended for final manuscript
• additional sibling files such as keypoints or partial section drafts

Treat sync-back as a selective editorial sync, not as a raw mirror operation.

Workspace Folder Structure

Generated projects use the following top-level layout.

Required Folders

Optional Folders

Chapter Layout

Each chapter gets a matching subtree in the manuscript folders.

keypoints/
  00-introduction/
sections/
  00-introduction/
images/
  00-introduction/

This symmetry keeps outlines, drafts, and images aligned by chapter.

Re:VIEW PDF Build Tips

Practical tips for customizing PDF output with Re:VIEW 5.x and the vvakame/review Docker image.

Font Selection

Add jafont=<preset> to texdocumentclass options in config.yml:

texdocumentclass: ["review-jsbook", "media=ebook,paper=b5,...,jafont=noto-otf"]

Available Presets (vvakame/review:5.9)

noto-otf provides ExtraLight through Black weights and is pre-installed in the Docker image.

TOC Depth Control

Problem

config.yml's tocdepth setting maps to \def\review@tocdepth{N} in the generated .tex. However, Re:VIEW's \reviewtableofcontents macro applies this value after document begin, so neither direct \setcounter{tocdepth} nor \AtBeginDocument in review-style.sty can override it.

Solution

Redefine \review@tocdepth itself in review-style.sty:

\makeatletter
\def\review@tocdepth{1}
\makeatother

Depth Values

Build Script Integration

When using a build script that injects styles via printf >> sty/review-style.sty:

printf '%s\n' \
  '% TOC depth: show only chapter and section' \
  '\makeatletter' \
  '\def\review@tocdepth{1}' \
  '\makeatother' \
  >> /work/sty/review-style.sty

Header/Footer Customization

Chapter Number Duplication and Partial Build Renumbering

Problem 1: Chapter Number Appears Twice

If the manuscript Markdown H1 already contains a literal chapter prefix such as 第7章 ..., Re:VIEW may still add its own chapter number in the PDF or EPUB output. That produces headings like 第4章 第7章 ... when chapter numbering is also generated by the builder.

Recommended Rule

• Treat chapter numbering as a build concern, not as a hard-coded H1 prefix in generated output
• If author-facing Markdown keeps 第N章 for readability, strip that prefix in the Markdown-to-Re:VIEW converter for level-1 headings
• Do not patch generated .re files by hand; fix the converter or source side instead

Why This Matters

The duplication is easy to miss in raw Markdown because it only appears after Re:VIEW numbering is applied. Fixing it in the converter prevents the same problem from reappearing across PDF, EPUB, and TOC output.

Problem 2: Partial Builds Renumber Chapters

If you regenerate only a subset of chapters and also regenerate catalog.yml for that subset, Re:VIEW will number those chapters from 1 again. This is correct for the temporary partial catalog, but misleading for final numbering review.

Recommended Rule

• Use partial conversion/builds for fast iteration on layout, wording, and local rendering issues
• Do not treat chapter numbers or TOC numbering from a partial catalog as the final source of truth
• For chapter-number review, regenerate the full catalog and rebuild the full book range

Why This Matters

Partial build output is useful for speed, but it can make a later chapter look like Chapter 1 simply because the catalog was narrowed for debugging. Without an explicit rule, reviewers often misdiagnose the problem as a heading bug instead of a catalog-range effect.

Custom headers and footers can be injected into review-style.sty using fancyhdr:

\fancyhead{}
\fancyhead[LE]{\gtfamily\sffamily\bfseries\upshape \leftmark}
\fancyhead[RO]{\gtfamily\sffamily\bfseries\upshape \rightmark}
\fancypagestyle{plain}{%
  \fancyhead{}
  \fancyfoot{}
  \fancyfoot[LE,RO]{\thepage}
  \renewcommand{\headrulewidth}{0pt}
  \renewcommand{\footrulewidth}{0pt}
}

URL Line Breaking

Problem

Long URLs (especially reference links) overflow the page width in PDF output. The default review-jsbook.cls defines \UrlBreaks but does not cover all characters, and lacks aggressive line-break permissions.

Solution

Two changes are required — LaTeX side and Ruby side:

1. LaTeX: Add xurl + emergencystretch

Add xurl (a TeX Live standard package that extends url with permissive break points) and \emergencystretch to the custom sty:

\usepackage{xurl}
\emergencystretch=3em

2. Ruby: Override inline_href in review-ext.rb

Re:VIEW converts @<href>{url, text} to \href{url}{\texttt{text}}. xurl only affects \url{} commands, so it does not break URLs inside \href{\texttt{}}.

Override inline_href in review-ext.rb to emit \url{} when the display text equals the URL:

def inline_href(str)
  url, label = str.strip.split(/,\s*/, 2)
  if label.nil? || label.strip == url.strip
    "\\url{#{escape_url(url)}}"
  else
    "\\href{#{escape_url(url)}}{#{escape(label.strip)}}"
  end
end

Warning: Adding xurl alone will appear to fix the build (no compile errors),

but the PDF will still have overflowing URLs. Both changes are required.

Alternative: Converter-side label stripping

If you control the Markdown-to-Re:VIEW converter, a cleaner alternative to the review-ext.rb override is to strip the label when it equals the URL, so Re:VIEW emits a bare @<href>{url}:

• Re:VIEW 5.x compile_href: @<href>{url, label} -> \href{url}{label} (not breakable),

while bare @<href>{url} -> \url{url} (breakable once xurl is loaded).

• In the converter, when a Markdown [label](url) has label == url, emit @<href>{url}

(drop the label). Keep @<href>{url, label} for human-readable labels (e.g. table cells).

• With this approach, only the LaTeX-side xurl is needed; the Ruby inline_href override

becomes optional.

Gotcha: \reviewhref does not exist in Re:VIEW 5.9.0. Do not try to

\renewcommand{\reviewhref} in the custom sty — the build fails with an undefined

control sequence. Fix link breaking via xurl + bare \url{} (converter or review-ext.rb),

not by redefining a Re:VIEW href macro.

Where to Add

Place these lines in review-custom.sty or the build script's custom sty injection point. Do not edit sty/review-jsbook.cls directly — the build script overwrites sty/ from the gem defaults on every run.

Notes

• xurl is included in TeX Live and does not require separate installation in the Docker image
• \emergencystretch=3em gives LaTeX extra flexibility when it cannot find good break points
• xurl alone is not enough — the inline_href override is essential because Re:VIEW uses \href{\texttt{}} not \url{}

Debugging

• Add --debug to review-pdfmaker to keep the build directory for inspection
• Check sty/review-style.sty inside the build directory to verify injected settings
• Use grep -rn 'tocdepth' sty/ *.tex to trace where values are set
• Use pdftotext output.pdf - to verify TOC content without opening a viewer

Font Size Tuning

Changing font size requires adjusting multiple parameters together. Add all values to texdocumentclass in config.yml:

Example (9pt):

texdocumentclass:
  [
    "review-jsbook",
    "media=ebook,paper=b5,serial_pagination=true,openright,fontsize=9pt,baselineskip=13.5pt,line_length=43zw,number_of_lines=38,head_space=30mm,headsep=10mm,headheight=5mm,footskip=10mm,jafont=noto-otf",
  ]

Chapter Opening on Right Page

Use openright instead of openany in texdocumentclass options. This ensures every # (chapter) starts on an odd (right-side) page. If the previous chapter ends on an odd page, a blank even page is inserted automatically.

Chapter Title Page (Full Page)

Override \@makechapterhead in review-custom.sty to make the chapter title occupy a full page with centered layout and decorative rules:

\makeatletter
\renewcommand{\@makechapterhead}[1]{%
  \vspace*{3cm}%
  \begin{center}%
    {\Large\headfont \@chapapp\thechapter\@chappos}%
    \par\vskip 12pt%
    {\rule{0.6\textwidth}{0.5pt}}%
    \par\vskip 16pt%
    {\Huge\headfont #1}%
    \par\vskip 12pt%
    {\rule{0.6\textwidth}{0.5pt}}%
  \end{center}%
  \clearpage%
}
\makeatother

The \clearpage at the end forces the first ## (section) to start on the next page.

Pitfall: Do not use \renewcommand{\reviewchapterhead} — this macro does not exist

in Re:VIEW 5.x. Use \@makechapterhead (standard jsbook) instead.

Also avoid \\ (line break) in \@makechapterhead; use \par\vskip for spacing.

Code Block Auto-Wrapping with review-ext.rb

Long code lines that exceed the page width can be automatically wrapped at build time using a review-ext.rb extension with the unicode-display_width gem.

Setup

1. Place review-ext.rb in the Re:VIEW project root (same directory as config.yml) 2. Install the gem at build time:

gem install unicode-display_width --no-document

3. Adjust WRAP_WIDTH constants for your font size and line length:

How It Works

The extension overrides code_line and code_line_num in LATEXBuilder. When a line exceeds WRAP_WIDTH display columns, it should split at spaces or delimiters such as /, -, _, ., : when possible, and only fall back to character-level wrapping when no safe break point exists.

Do not inject visible continuation markers such as ↵ into the PDF output. They tend to look like mojibake or converter garbage in review screenshots.

See templates/review-ext.rb for a ready-to-use template.

Practical Rules

• Prefer delimiter-aware wrapping over raw character-count splitting
• Do not add visible wrap markers to wrapped code lines
• Keep a last-resort hard wrap for single long tokens that exceed line width

Code Fence Captions

Problem

If a Markdown code fence has a language but no explicit caption, some converters accidentally promote the language name itself (text, json, markdown) into a visible list caption. This looks like converter noise in the final PDF.

Recommended Rule

• Treat the first fence token as the syntax/language only
• Only emit a visible Re:VIEW list caption when the fence info contains an explicit caption
• When the caption is omitted, still emit the required Re:VIEW block arguments, but keep the caption empty

Example:

```markdown ``json API response example { "ok": true }

should produce a visible caption, while:

````markdown

{ "ok": true }

````

should not show json as the caption.

Reference URLs Inside Bullet Lists

Problem

In Markdown manuscripts, authors often write references as a bullet title followed by a URL on the next indented line. During Markdown -> Re:VIEW -> LaTeX conversion, that newline may collapse back into a space inside list items, causing long URLs to run across the page and get clipped.

Recommended Rule

• Write manuscript references in two lines inside the same list item
• Put the title on the first line
• Put the URL itself as a link on the next indented line
• In the converter, emit an explicit line break before link-only continuation lines

Example manuscript form:

- GitHub Docs: GitHub Copilot policies
  [https://docs.github.com/en/copilot/concepts/policies](https://docs.github.com/en/copilot/concepts/policies)

This keeps the title readable and prevents long URLs from relying on implicit line wrapping alone.

Footnote ID Collisions Across Combined Markdown Files

Problem

Some book workflows concatenate multiple Markdown section files into one chapter-level .re file. If each source file uses local footnote labels such as [^1], [^2], the same labels can repeat across files. If the converter normalizes those labels directly into a shared namespace, later definitions may overwrite earlier ones or references may point to the wrong footnote body.

Another trap is treating any [^id]: substring as a footnote definition. Inline prose such as See note[^4]: or list items ending with [^1]: still contain a reference followed by punctuation, not a footnote definition.

Recommended Rule

• Namespace Markdown footnote labels per source file before converting them to final Re:VIEW footnote IDs
• Detect footnote definitions only at the start of a line
• Keep reference replacement active even when a colon immediately follows the closing bracket in prose or list items

Example Strategy

If both section-a.md and section-b.md contain [^1], rename them to source-scoped labels such as:

• section_a_1
• section_b_1

Do this before any final ID sanitization for Re:VIEW output.

Verification

• Inspect a representative .re snippet and confirm that each @<fn>{...} points to the intended //footnote[...]
• Rebuild the final PDF after converter changes; checking only .re output is not enough when references can silently resolve to the wrong note body

Table Notes and Footnotes

Problem

In a Markdown -> Re:VIEW -> LaTeX -> PDF workflow, a note may semantically belong to a whole table, but footnote markers placed inside table cells or even in the table header do not reliably become page-bottom footnotes in the final PDF. Depending on the converter and LaTeX table environment, the marker may disappear, remain inline, or fail to render as a normal bottom note.

Recommended Rule

• If a note applies to the whole table, do not place the footnote marker inside a table cell
• Do not rely on table-header footnote markers for bottom-of-page notes
• Add one short prose sentence immediately before or after the table, and attach the footnote marker there
• Write the footnote body so it explicitly says the note applies to the table

Example Strategy

Prefer this:

#### Representative built-in classifiers

Note that, in the table below, Agreements, Resume, and Financial Statement are English-only as of May 2026[^1].

| Classifier | Description |
| ---------- | ----------- |
| Threat     | ...         |
| Agreements | ...         |

[^1]: In the table below, Agreements, Resume, and Financial Statement are English-only as of May 2026.

Avoid this:

| Classifier[^1] | Description |
| -------------- | ----------- |
| Agreements     | ...         |

Why This Works

• The note still reads as table-specific to the human reader
• The footnote marker stays in normal prose, which Re:VIEW and LaTeX handle more reliably
• The final PDF is less likely to lose the note or render it in an unexpected place

Odd/Even Running Headers and Side Markers

Problem

When designing chapter/section markers for the top margin or the left/right side margins, it is easy to focus on fancyhdr slot configuration (LE, RO, etc.) and miss that the LaTeX document class is still running in oneside mode. In that case, odd/even-specific placements do not behave as expected, and layout experiments can appear to "do nothing".

Another trap is trying to derive chapter, section, and subsection labels from only one mark stream. If multiple hierarchy levels need to be displayed at the same time, overloading a single mark variable tends to produce blanks or stale labels.

Recommended Rule

• Use twoside in texdocumentclass whenever odd/even page layout should differ
• Treat chapter and lower-level markers as separate responsibilities
• Prefer leftmark for stable chapter-level display
• Use rightmark for the currently active lower-level heading when appropriate
• If the design needs multiple hierarchy levels at once, keep separate stored values instead of trying to infer everything from one mark

Practical Notes

• oneside can make odd/even fancyhdr settings appear broken even when the style file is correct
• Re:VIEW/jsbook-based stacks often behave more predictably when chapter-level display uses leftmark
• Verify the actual PDF result, not just the style file text

Fastest Way to Isolate Header Problems

If an odd/even running header still does not show the expected chapter or section title, first verify the slot itself before changing mark logic again.

• Temporarily replace the intended header content with a fixed literal such as CHAPTER-TEST
• Rebuild the PDF and check whether that literal appears in the target slot
• If the literal appears, the page-style slot is working and the remaining bug is in mark propagation or title capture
• If the literal does not appear, the issue is page style selection, twoside configuration, or viewer caching, not the mark text itself

This avoids repeated changes to \chaptermark, \sectionmark, or custom state variables when the real problem is elsewhere.

Margin Labels: Prefer fancyhdr Before Page Overlay Packages

For vertical chapter/section labels placed in the side margins, prefer a fancyhdr-based approach first.

• Use rotatebox plus horizontal offset inside the appropriate LE / RO header slots
• Treat page-overlay packages such as eso-pic as a fallback, not the first choice

In Re:VIEW/jsbook-based stacks, eso-pic can conflict with other page-layout helpers such as pxesopic / gentombow, causing LaTeX build failures even when the layout idea itself is valid.

If a margin-label experiment unexpectedly breaks the build, remove the overlay package first and return to a plain fancyhdr implementation before debugging other parts of the style.

PDF Viewer Cache During Layout Verification

Problem

Running-header, footnote, or spacing changes are often verified by repeatedly rebuilding the same PDF output filename. Some PDF viewers continue to show a cached version of the file even after the build succeeded, which makes it look as though the latest style change had no effect.

Recommended Rule

• Do not trust a same-name PDF tab alone when verifying layout changes
• Check the updated file timestamp after each build
• If the workflow archives previous builds into timestamped directories, compare against the newly archived copy as well
• When a result seems unchanged, verify the generated .re or .tex snippet before assuming the style edit failed

Verification

• Confirm the output PDF modification time changed
• Open the latest archived/timestamped PDF when available
• Compare one representative .re snippet to the PDF page before continuing with further style changes

Explicit Blank Lines Between Paragraphs

Problem

In a Markdown -> Re:VIEW -> LaTeX -> PDF workflow, plain blank lines usually only mark paragraph boundaries. They do not reliably create a visibly larger vertical gap in the final PDF. Likewise, forcing line breaks with @<br>{} may end up as paragraph-internal \\ and still fail to produce the intended blank line.

Recommended Rule

• If you need a visibly larger gap in the PDF, do not rely on Markdown blank lines alone
• Use a hidden manuscript marker such as <!-- review:br -->
• Convert that marker in the Markdown-to-Re:VIEW script into a raw LaTeX vertical-space command

Recommended conversion target:

//raw[|latex|\\par\\vspace{1em}]

This keeps the Markdown source readable while producing an explicit blank gap in PDF output.

Why This Works

• Markdown blank lines: paragraph split only
• @<br>{}: may become \\, which is just a line break
• \par\vspace{1em}: ends the paragraph and inserts actual vertical space

Example

Manuscript source:

本文の締めです。

<!-- review:br -->
<!-- review:br -->

次の視点へ切り替えます。

Converter output:

本文の締めです。

//raw[|latex|\\par\\vspace{1em}]
//raw[|latex|\\par\\vspace{1em}]

次の視点へ切り替えます。

Practical Notes

• Keep the marker name stable across the workspace so authors can reuse it consistently
• Tune 1em to 1.5em or 2em only after checking the actual PDF result
• Prefer this technique only when visual separation matters; for normal prose, paragraph breaks are usually enough

Markdown Backslash Escapes in PDF Output

Problem

Markdown allows backslash escapes such as \_, \*, ` \ `, \\ to prevent special characters from being interpreted as formatting. When converting Markdown to Re:VIEW (.re), these escapes may pass through literally, producing visible backslashes in the PDF output (e.g. yuyanz\_ instead of yuyanz_`).

Solution

Add an unescape step in the Markdown-to-Re:VIEW conversion script's inline processing, after protecting code spans but before applying bold/italic transformations:

# Unescape Markdown backslash escapes (e.g. \_ -> _)
text = re.sub(r"\\([_*`\\])", r"\1", text)

This must run before bold/italic regex matching so that \_ is reduced to _ before the *...* patterns are evaluated.

Affected Elements

• Headings (## Yuya（yuyanz\_） → shows backslash in section title)
• Body text (e.g. file\_name → shows backslash in prose)
• Any inline context processed by replace_inline()

Markdown Image Caption vs Layout Metadata

Problem

When Markdown images are converted to Re:VIEW, the image alt text and optional title often get mixed together. If authors put manual figure numbering such as Image: ... or 図 01 into alt text, the final PDF can end up with duplicated numbering because Re:VIEW already manages figure numbering.

Another common issue is using the title field as if it were a second caption. For example, ![Caption](images/foo.png "scale=0.80") should treat scale=0.80 as layout metadata, not as visible caption text.

Recommended Rule

• Use alt text for the visible caption only
• Do not put manual numbering such as 図 01, Figure 1, or Image: into alt text
• Use the Markdown image title only for layout metadata such as scale=0.80
• If no caption is provided, let the converter fall back to the file stem or another deterministic rule

Markdown Tables Need //tsize for PDF Wrapping

Problem

When Markdown pipe tables are converted to plain Re:VIEW //table{} blocks without a matching //tsize, LaTeX PDF output often falls back to fixed-width-free columns such as |l|l|l|. In that mode, long Japanese prose inside cells does not wrap correctly and can run past the page edge.

This tends to surface in tables where the last column contains explanatory sentences, for example:

• tool comparison tables
• role / usage / notes matrices
• long scenario descriptions in 3-column tables

Solution

Emit a LaTeX-specific //tsize immediately before the generated //table{} block:

//tsize[|latex||L{27mm}|L{36mm}|L{63mm}|]
//table{
項目	説明	利用シーン
------------------------------------------------------------
...
//}

Practical Rule

• Use L{...mm} columns for any table column that may need wrapping
• Reserve the widest column for prose-heavy cells, usually the last column
• Generate widths automatically in the Markdown-to-Re:VIEW converter when possible
• Keep the total width aligned to the actual PDF text area used by the project

Why This Matters

Even if the manuscript source looks fine in Markdown, the PDF builder only wraps table cells when the LaTeX column spec supports wrapping. If a project relies on auto-generated Re:VIEW, table layout must be handled in the converter, not left to authors to patch by hand after every build.

Recommended Pattern

![Agent モードの選択](images/docmng_img02.png "scale=0.80")

This should become a Re:VIEW image block where:

• caption = Agent モードの選択
• metric = scale=0.80

Anti-Patterns

![Image: Agent モードの選択](images/docmng_img02.png)
![図 01. Agent モードの選択](images/docmng_img02.png)
![Agent モードの選択](images/docmng_img02.png "図 01")

These patterns make later conversion and numbering brittle.

Chapter Illustration on Blank Pages

When using openright, a blank even page is inserted before each chapter that starts on an odd page. This blank page can be used to display an illustration by overriding \cleardoublepage in review-custom.sty.

Implementation

\makeatletter
% Track mainmatter state — illustration only in mainmatter
\newif\ifreview@inmainmatter
\review@inmainmatterfalse
\g@addto@macro\reviewmainmatterhook{%
  \review@inmainmattertrue
}

\let\review@origcleardoublepage\cleardoublepage
\renewcommand{\cleardoublepage}{%
  \clearpage
  \if@twoside
    \ifodd\c@page\else
      \thispagestyle{empty}%
      \ifreview@inmainmatter
        \edef\review@nextch{\the\numexpr\value{chapter}+1\relax}%
        \ifnum\review@nextch>0
          \ifnum\review@nextch<8  % adjust upper bound to your chapter count
            \null\vfill
            \begin{center}%
              \includegraphics[width=0.65\textwidth,height=0.65\textheight,keepaspectratio]{images/chapter-illustrations/ch\review@nextch}%
            \end{center}%
            \vfill
          \fi
        \fi
      \fi
      \newpage
      \if@twocolumn\hbox{}\newpage\fi
    \fi
  \fi
}
\makeatother

File Naming

Place images as images/chapter-illustrations/ch1.png, ch2.png, etc. Do not zero-pad (ch01.png) because \thechapter outputs 1, not 01.

Build Prerequisites

Run extractbb on all illustration PNGs before review-pdfmaker:

cd /work && for f in images/chapter-illustrations/*.png; do extractbb "$f"; done

This generates .xbb bounding box files that dvipdfmx needs.

Image Handling Pitfalls (dvipdfmx)

\IfFileExists Does Not Find Image Files

In dvipdfmx environments, \IfFileExists{images/foo.png} always returns false because .png is not in the kpsewhich search path. Use \ifnum conditions on chapter numbers or \openin file-read tests instead.

extractbb Paranoid Mode in Docker

TeX Live's default openout_any = p (paranoid) blocks writes to absolute paths. extractbb /work/images/foo.png fails with openout_any = p error. Always use relative paths: cd /work && extractbb images/foo.png.

\cleardoublepage Fires in Frontmatter

The \cleardoublepage hook runs for all page transitions, including title page → TOC. Without a mainmatter guard, images meant for ch1 can appear on the blank page after the title page (where chapter counter = 0, so nextch = 1). Always gate illustration insertion with a \ifreview@inmainmatter flag set in \reviewmainmatterhook.

Footnote Placement in Generated .re Files

Problem

When a Markdown-to-Re:VIEW converter concatenates multiple Markdown files into one chapter .re file, footnote definitions (//footnote[id][text]) are often appended at the end of the chapter. Re:VIEW's LaTeX builder outputs \footnotetext[N]{...} at the position where //footnote appears in the .re file. If all definitions are at the chapter end, every footnote in the chapter clusters on the last few pages of the PDF instead of appearing at the bottom of the page where it is referenced.

Additional Trap: Nested Blocks

Moving //footnote to right after the reference line is not always sufficient. If the reference is inside a block such as //table{...//} that is itself nested inside a column block (===[column]...===[/column]), placing the footnote after the inner //} still leaves it inside the column. Re:VIEW renders columns with tcolorbox, and \footnotetext inside tcolorbox triggers a Counter too large LaTeX error that aborts the build entirely.

Recommended Rule

1. After generating all .re content, redistribute //footnote definitions from the chapter end to immediately after their reference locations 2. If the reference is inside any block, place the footnote after the outermost enclosing block (where depth returns to 0), not just the innermost //} 3. Track block depth for both brace-delimited blocks (//xxx{...//}) and column blocks (===[column]...===[/column]) 4. Footnotes with no matching reference (unused) stay at chapter end

Verification

• Check that //footnote lines appear near their @<fn>{} references in the .re file, not all at the end
• Confirm no //footnote is inside a //table{...//} or ===[column]...===[/column] block
• Build the full PDF and check that footnotes appear at the bottom of the referencing page, not clustered at chapter end
• Watch for Counter too large errors — they indicate a footnote is still inside a tcolorbox-rendered block

Template Threshold for Skipping Files

When the converter skips files below a character-count threshold to exclude templates, keep the threshold low enough that short but real content (e.g., a heading + one paragraph + an image reference) is not silently dropped from the PDF. A threshold around 200 characters for normal section files is a practical balance; 300 characters can silently skip valid content.

Setup Workflow

Use the setup script to create a new manuscript workspace from the bundled templates.

Command

python scripts/setup_workspace.py `
    --name "project-name" `
    --title "Book Title" `
    --path "D:\target\path" `
    --chapters 8

# Add Re:VIEW/PDF support only when the project needs it.
python scripts/setup_workspace.py `
    --name "project-name" `
    --title "Book Title" `
    --path "D:\target\path" `
    --chapters 8 `
    --with-review

Main Options

What Gets Generated

1. Folder structure for outlines, drafts, images, docs, and optional output 2. Writing/review agents and writing instructions under .github/ 3. Project docs such as README.md, docs/page-allocation.md, and docs/schedule.md 4. Helper scripts such as scripts/count_chars.py 5. Initial chapter intro files in both outline and manuscript folders 6. Optional Re:VIEW/PDF scripts and metadata when --with-review is used

Post-Setup Checks

1. Open the generated README.md and confirm project metadata 2. Edit docs/page-allocation.md to fit the book length 3. Edit docs/schedule.md to replace placeholder dates 4. Adjust .github/copilot-instructions.md for the target audience and goals

Installed Skills

The following agents are available in this workspace.

If Re:VIEW/PDF support is enabled, add a converter agent for Markdown to Re:VIEW conversion.

Folder Permissions

Workflow

Key Points -> Draft -> Review -> Fix -> Optional Convert/PDF
   ↓          ↓        ↓       ↓       ↓
keypoints  sections  Loop until  re-view-output
                     P1=0, P2=0  when enabled

Data Verification

Before completing a chapter:

1. Run python scripts/count_chars.py to check word counts 2. Verify against docs/page-allocation.md targets 3. Ensure folder structure matches keypoints/

Converter Agent

Convert Markdown manuscripts to Re:VIEW format for PDF generation.

Role

Convert files in sections/ to Re:VIEW format in re-view-output/.

Goals

• Convert Markdown to Re:VIEW syntax accurately
• Maintain formatting and structure
• Generate PDF-ready output

Permissions

• Allowed: Read sections/, edit re-view-output/, run terminal commands
• Forbidden: Edit sections/, git push

Workflow

1. Read Markdown files from sections/ 2. Convert to Re:VIEW format using scripts/convert_md_to_review.py 3. Output to re-view-output/ 4. Build PDF with Docker (if available)

Re:VIEW Conversion Rules

Headings

Inline Formatting

Lists

- Item 1
- Item 2

 * Item 1
 * Item 2

Code Blocks

````markdown

print("hello")

````

//listnum[code1][python]{
print("hello")
//}

PDF Build Command

docker run --rm -v "${PWD}:/work" vvakame/review rake pdf

Output Structure

re-view-output/
├── *.re
├── images/
├── catalog.yml
└── config.yml

Error Handling

Writing Reviewer Agent

Review manuscripts and provide structured feedback.

Role

Review Markdown files in sections/ and provide prioritized improvement suggestions.

Goals

• Identify issues using P1/P2/P3 priority system
• Ensure consistency with writing guidelines
• Improve readability and technical accuracy

Permissions

• Allowed: Read all files
• Forbidden: Edit files, git commands

Priority System

P1 Examples

• Incorrect technical information
• Heading level errors (using # in section files)
• Folder structure mismatch
• Word count out of range
• Missing required sections

P2 Examples

• Inconsistent terminology
• Unclear explanations
• Missing sources/references
• Style guide violations

P3 Examples

• Minor wording improvements
• Alternative expressions
• Additional examples

Output Format

## Review Result: {filename}

### Summary

- P1: {count} issues
- P2: {count} issues
- P3: {count} suggestions

### P1 (Critical)

#### P1-1: {issue title}

- **Location**: Line XX
- **Issue**: {description}
- **Fix**: {suggested fix}

### P2 (Important)

#### P2-1: {issue title}

- **Location**: Line XX
- **Issue**: {description}
- **Suggestion**: {improvement}

### P3 (Suggestions)

- {suggestion 1}
- {suggestion 2}

Checklist

Structure

• [ ] Folder hierarchy matches keypoints/
• [ ] Heading levels are correct (no # in section files)
• [ ] File naming follows conventions

Content

• [ ] Technical accuracy verified
• [ ] Terms explained on first use
• [ ] Sources cited where needed

Style

• [ ] Uses polite/desu-masu style
• [ ] Sentences under 500 characters
• [ ] Natural Japanese (not translation-style)

Word Count

• [ ] Within target range per file type
• [ ] Chapter total within bounds

Reference Files

Writing Agent

Write and edit manuscripts for the book project.

Role

Edit Markdown files in sections/ to create high-quality manuscripts.

Goals

• Write manuscripts based on key points in keypoints/
• Balance technical accuracy with readability
• Achieve P1=0, P2=0 after review

Permissions

• Allowed: Read files, edit sections/, request review, run terminal commands
• Forbidden: git push, delete files, edit keypoints/

I/O Contract

Instructions

Follow the writing style guidelines in .github/instructions/writing/writing.instructions.md.

Key Rules

1. Use polite/desu-masu style (です・ます調) 2. Keep sentences under 500 characters 3. Explain technical terms on first use 4. Include sources and references

Done Criteria

• [ ] Target file editing complete
• [ ] Folder structure matches keypoints/
• [ ] Word count within range per docs/page-allocation.md
• [ ] P1 (critical) issues = 0
• [ ] P2 (important) issues = 0

Workflow

1. Check structure in keypoints/ 2. Determine file type and target word count 3. Write manuscript in sections/ 4. Verify word count with python scripts/count_chars.py 5. Report completion to Orchestrator

Error Handling

Reference Files

{{BOOK_TITLE}} - Copilot Guide

Overview

This is the book writing workspace for "{{BOOK_TITLE}}".

Target Readers

• (Define your target audience here)

Goals

• (Define what readers will learn)

Folder Structure

Constraints

Version Control

• Follow this repository's existing Git workflow.
• Do not push unless explicitly instructed.
• Verify the current directory before running commands.

File Naming Conventions

Naming rules for files and folders in the book project.

Manuscript Files

Pattern

ch{chapter}-{number}_{title}.md

Components

Examples

File Division Strategy

Basic Principle

1 file = 1 section

File Structure

Each chapter consists of:

• ch{N}-00 = Chapter introduction (300-500 chars)
• ch{N}-01 = Section 1 (2,000-6,000 chars)
• ch{N}-02 = Section 2 (2,000-6,000 chars)
• ch{N}-03 = Section 3 (2,000-6,000 chars)

Image Files

Pattern

fig-{chapter}-{section}-{number}.{ext}

Extensions

Re:VIEW Files

Pattern

ch{NN}-{slug}.re

Examples

Notes

1. Spaces are OK in folder titles 2. Japanese is OK in visible titles 3. Keep IDs alphanumeric and half-width

Page Allocation and Word Count Targets

Target word counts for each file type and chapter.

File Type Targets

1 file = 1 section

Chapter Targets

Customize this table for your book:

Tolerance Rules

Word Count Check

python scripts/count_chars.py

Project Schedule

Timeline for "{{BOOK_TITLE}}".

Milestones

Chapter Progress

Weekly Goals

Week of YYYY-MM-DD

• [ ] Complete key points for Chapter 1
• [ ] Start draft for Introduction
• [ ] Gather reference materials

Chapter Title

<!-- Chapter intro template for ch-00_.md --> <!-- Target: 300-500 characters -->

This chapter explains [chapter purpose and scope in 1-2 short paragraphs].

What You Will Learn

• [Learning point 1]
• [Learning point 2]
• [Learning point 3]

[Add a short background paragraph and chapter roadmap.]

---

Heading Rules

• # = chapter title (only one per file)
• ## = major heading
• ### = subsection

Notation Rules

• Numbers: half-width (100, 2026, 80%)
• Japanese punctuation in prose: full-width (。,、)
• Parentheses in prose: full-width （）
• First term appearance: Japanese (English)

Section Title

<!-- Section template for ch-01_.md and later --> <!-- Target: 2,000-6,000 characters -->

[Write a short lead paragraph that explains this section goal.]

Subheading 1

[Write section content here.]

Key points:

• Point 1
• Point 2
• Point 3

Subheading 2

[Write section content here.]

Detailed Item (optional)

[Add deeper explanation if needed.]

Code Example (optional)

# Example

def example_function():
    return "Hello, Copilot"

Figure Example (optional)

!Figure caption

Summary

[Add a 1-2 paragraph summary for this section.]

---

Heading Rules (Important)

• # is not allowed in section files
• ## = section title (one at the top)
• ### = subsection
• #### = detailed subsection

Character Budget Suggestion

• Lead: 200-300
• Each subsection: 500-1,000
• Summary: 100-200

Writing Workflow Guide

Book writing workflow for "{{BOOK_TITLE}}".

Quick Reference

Writing Workflow

Folder Structure

keypoints/          # Outlines
sections/           # Final manuscripts
re-view-output/     # Optional Re:VIEW and PDF output
images/             # Images
materials/          # Reference materials
docs/               # Documentation
scripts/            # Utility scripts

Templates

Reference Documents

Heading Level Instructions

Rules for Markdown heading levels in manuscripts.

Basic Rules

Why This Matters

• Chapter files define the chapter title with #
• Section files are part of a chapter, so they start with ##
• This ensures correct hierarchy in PDF/EPUB output

Examples

Correct

## Section Title

Content here...

### Subsection

More content...

Wrong

# Section Title

Content here...

Using # in a section file is a P1 issue.

Writing Notation Instructions

Consistent notation and terminology rules.

Numbers

Punctuation

Technical Terms

First Occurrence

Format: 日本語（English）

Examples:

• 機密性（Confidentiality）
• 多層防御（Defense in Depth）
• データ損失防止（Data Loss Prevention、DLP）

Subsequent Occurrences

Use Japanese only, or the acronym if already introduced.

Product Names

• Write exactly as official documentation
• Examples:
• Microsoft Purview
• Azure Active Directory
• GitHub Copilot

Diagram Labels

• Default diagram labels, box titles, and helper text to the main manuscript language.
• Keep original-language operation names, feature names, or product names only when they are the terms readers are expected to recognize.
• When needed, combine both forms instead of choosing one rigidly.
• Example: pull (pull) or pull (fetch updates) depending on the audience language and book style
• Do not leave the entire diagram in English when the surrounding manuscript is not, unless you are reproducing an official UI or quoting a source artifact.
• Keep explanatory text in diagrams reader-facing and plain; avoid tool-author jargon.

Consistency Checklist

• [ ] Numbers are half-width
• [ ] Punctuation follows rules
• [ ] Terms explained on first use
• [ ] Product names match official
• [ ] Acronyms introduced properly
• [ ] Diagram labels follow the manuscript language policy

Writing Instructions

Guidelines for manuscript writing style and quality.

Style Rules

Tone

• Use polite/desu-masu style (です・ます調)
• Write natural Japanese (avoid translation-style)
• Keep sentences under 500 characters
• Vary sentence length and endings for natural flow

Terminology

• Explain technical terms on first use
• Format: Japanese (English) - e.g., 機密性（Confidentiality）
• Use consistent terminology throughout

Structure

• Abstract -> Concrete -> Re-abstract
• Why -> What to protect -> How to design
• End with practical application, not just theory

Source Confidence

• Do not write feature behavior, limits, UI paths, metrics, or procedures from guesswork.
• If a point is not verified, do not smooth it into final prose with plausible wording.
• Keep unresolved items in outline or key-points notes as explicit verification tasks, not as normal explanatory sentences.
• Final manuscript files should contain only verified statements or clearly attributed interpretation.
• Avoid fallback phrasing such as "probably", "should be", or similar hedges when they are only hiding missing verification.

Introduction Pattern

1. Hook 2. Concrete scene 3. Core learning 4. Tomorrow's action 5. Lingering thought

Summary Pattern

• Key point recap
• Practical next step
• Lingering thought or question
• Bridge to next chapter

Figures and Lists

Diagram and Table Rules

• If a section compares terms, roles, plans, tools, or options, check whether a table is clearer than bullets or prose.
• If a section explains flow, direction, lifecycle, source/target movement, or hierarchy, plan a figure before expanding the prose.
• Keep diagram intent explicit in the outline: note both the visual type and the reader takeaway.
• Use tables for comparison and figures for flow; do not overload a table with process steps that belong in a diagram.
• When using a figure, add 1 to 2 sentences before or after it to tell the reader what to look at.

Word Count Targets

See docs/page-allocation.md for detailed targets per file type.

Forbidden Patterns

• Overuse of em-dashes for dramatic effect
• Consecutive bullet lists without prose breaks
• Translation-style Japanese
• Sentences over 500 characters
• Speculative statements presented as facts

{{BOOK_TITLE}}

This repository contains the manuscript workspace for "{{BOOK_TITLE}}".

Quick Start

1. Review docs/page-allocation.md and set character targets 2. Review docs/schedule.md and replace placeholder dates 3. Edit .github/copilot-instructions.md for audience and goals 4. Start outlining in keypoints/ 5. Write drafts in sections/

Repository Structure

Common Commands

python scripts/count_chars.py

# If Re:VIEW/PDF support is enabled:
# python scripts/convert_md_to_review.py
# python scripts/build_review_pdf.py
# python scripts/inspect_pdf.py pdf/book.pdf

Workflow

1. Draft the structure in keypoints/ 2. Write the manuscript in sections/ 3. Review with @writing-reviewer 4. Convert with scripts/convert_md_to_review.py if Re:VIEW support is enabled 5. Build or polish PDF assets only when PDF output is in scope

Metadata Layer

1. Put stable shared cover and colophon defaults in config/review-metadata/common.yml 2. Put project-specific author, publisher, title, subtitle, and series badge values in config/review-metadata/project.yml 3. If the repo contains a series, compare title naming patterns across books before fixing one title alone 4. Regenerate Re:VIEW config and cover assets through the helper scripts instead of editing generated files directly