Spec 001 T030: check-book

specs/001-pathway-pdfs/contracts/cli.md

@@ -99,10 +99,13 @@ the figures already drawn by `figures`.
     here can come after earlier parts or PDFs are printed; the step still ends with exit
     1 and no book written, the folder being moved into place only at the end.
 - **Exit 0:** the book is written, and `check-book` passed on it. The folder is written
-  beside its name and moved into place, so a failed run never leaves a partial book. A
-  run is whole: a failure in any PDF writes none, and the step is run again.
-- **Exit 1:** a fault from the preflight or FR-011. The report names each one by stable
-  identifier or file name, never a person.
+  beside its name, checked there (`check-book`'s checks, on the documents the preflight
+  built, the printer closed first), and moved into place only once they pass, so a failed
+  run never leaves a partial book or one that fails its check. A run is whole: a failure in
+  any PDF writes none, and the step is run again.
+- **Exit 1:** a fault from the preflight or FR-011, each printed as `check-book` prints it.
+  The report names each one by stable identifier or file name, never a person, and gives
+  each FR-011 check with its count of faults.
 - **Exit 2:** bad arguments; a `--report` that exists already (left untouched, and no
   report written), whose folder cannot be made, or that is inside `--out`; an `--out` that
   is not absent or empty, as for `figures` (an old book is never replaced in place), that
@@ -118,12 +121,16 @@ the figures already drawn by `figures`.
   128 and the signal's number. It exits rather than raising the signal again, as the
   exit handlers that end the browser and remove its folders run only on an exit. A
   signal while the browser is starting is acted on once it has started, and a second
-  signal then stops the run at once.
+  signal then stops the run at once. Once the book is checked and moved into place, a
+  signal stops nothing that is not done: the book is left in place, the report says it
+  was written (outcome `written`) and names the signal, and the exit is 0.
 - **A private temporary folder:** the run makes one in TMPDIR at its start and points
   everything it starts at it (the printer's pages, the browser launcher's folders and the
   browser itself, by TMPDIR), and removes it, whole, as the process exits, after the
-  launcher has ended the browser; so a signal at any moment leaves nothing in TMPDIR. The
-  browser launcher's own signal handling is off, as in `serve`.
+  launcher has ended the browser; so SIGINT, SIGTERM or SIGHUP at any moment leaves nothing
+  in TMPDIR (SIGKILL, or the memory cap's kill, leaves it). One is live in a process at a
+  time, as TMPDIR is the process's: a second is refused. The browser launcher's own signal
+  handling is off, as in `serve`.
 
 ## `pdf-export preflight`
 
@@ -153,12 +160,15 @@ as in `--files` (`diagram/R-HSA-….json`), a figure's as in `--figures` (`R-HSA
 
 FR-011's check, alone. Also run by `book`.
 
-| Flag                   | Meaning                                                                                  |
-| ---------------------- | ---------------------------------------------------------------------------------------- |
-| `--graph`, `--species` | the graph the book was made from, for the list of top-level pathways and events expected |
-| `--files`              | the release's folder, for which events have a figure's source (FR-011)                   |
+| Flag                                 | Meaning                                                                                                                                      |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--graph`, `--database`, `--species` | as for `book`: the graph the book was made from, for the list of top-level pathways and events expected                                      |
+| `--files`                            | the release's folder: its EHLD summary, for the Figure rules, as `book` reads it, and which events have a figure's source (FR-011); required |
 
 - **Exit 0:** every check passed.
+- **Exit 2:** bad arguments (one folder, `--files`, and a graph are needed); a folder that is
+  not one; no EHLD summary in `--files`; the graph cannot be reached at the start; or any
+  other error (a PDF that cannot be read, a graph that fails mid-run), on stderr.
 - **Exit 1:** at least one fault, one line each:
   - `fault missing-pathway <stId>`: a top-level pathway with no PDF;
   - `fault extra-file "<file name>"`: a PDF in the folder that is no top-level pathway's;
@@ -168,8 +178,38 @@ FR-011's check, alone. Also run by `book`.
     `no-stable-id`, `missing-figure` and `broken-link`.
 
   A file is matched to its top-level pathway by name: the names expected are made from
-  the graph as `book` makes them. The PDFs are untagged, so sections are found by the
-  outline and the text at each entry's destination (research R8).
+  the graph as `book` makes them, and any other file or folder in the folder is an
+  `extra-file`. The PDFs are untagged, so they are read with pdf.js for their outline, links
+  and text (research R8), each event's printed texts after FR-017's substitutions:
+  - names are compared as read back: compatibility forms folded (NFKC), white space and the
+    characters never drawn (FR-017's controls and default-ignorables: a soft hyphen, a
+    joiner, a variation selector) left out;
+  - a **section** is found at its heading's link to the event's page on the website (the
+    first link there; a reaction's figure links there too, below it), where an outline or
+    contents entry with its name lands too; or else where such an entry lands whose section
+    gives the event's stable identifier first (two events of one name), or the first such
+    entry; or else at that link. It runs to the next section found;
+  - the **contents list's entries** are the links before the first section (where the first
+    outline entry with an event's name lands), each one annotation, its rectangle around
+    every line of an entry that wraps;
+  - `not-in-contents`: no contents entry lands on the section and reads its name;
+    `not-in-outline`: no outline entry, at any depth, does both; an event whose section is
+    not found at all is these two faults and `no-name`;
+  - `no-name`: the section's heading does not read its name. The heading is its leading
+    text set larger than its page's body text (the size most of the page's characters are
+    set at) by at least 15:14, the ratio of 11.25 pt to the body's 10.5 (the smallest
+    heading is 12 pt): measured against the page, not in points, so a page Chromium printed
+    scaled down (which the layout should never make, as nothing in it is wider than the text
+    column) still reads its names, its own scale not a fault; `no-stable-id`: its text
+    holds no `Stable identifier` followed by its stable identifier;
+  - `missing-figure`: a pathway's or reaction's section with a figure by the Figure rules,
+    whose source is in `--files` (its diagram's two files, its EHLD; a reaction's is the
+    graph), has no link to that figure's interactive form below its heading. The figure is
+    known by its link: a drawing lost with its link kept is not seen;
+  - `broken-link`: a link that lands on no page of its PDF, is still a placeholder or probe
+    address (T026), or whose address to an event's page cannot be decoded, named by the
+    section it is in, or by the PDF's pathway for one in its front parts, one line a
+    section.
 
 ## `pdf-export compare <reference> <new>`
 
@@ -201,4 +241,6 @@ The single-event service (contracts/service.md).
   SIGHUP once it serves closes it and exits 0; one before it serves, or another while it
   closes, exits at once with 128 and the signal's number. Like `book`, it makes a private
   temporary folder at its start for the printer and the browsers it starts, removed as
-  the process exits, so it leaves nothing in TMPDIR however it is stopped.
+  the process exits, so it leaves nothing in TMPDIR when it is stopped by SIGINT, SIGTERM
+  or SIGHUP. A process killed outright (SIGKILL, the memory cap's kill) or by a signal it
+  does not handle leaves the folder, as no exit handler runs.

specs/001-pathway-pdfs/data-model.md

@@ -176,6 +176,9 @@ cause (`unanswered`, `failed`, `refused`, `invalid` or `label`, contracts/figure
   time where they overlap (T029).
 - The join's settings: `--joins`, `--parallel` and whether object streams are on
   (research R4).
-- Each FR-011 check, and its result (none until `check-book`, T030).
+- Each FR-011 check (`check-book`, T030), with its count of faults, none a pass; none
+  when the run stopped before the check. Its faults are among the book's faults.
+- The signal that stopped the run, if one did; once the book is in place, the outcome is
+  still the book written.
 - The book's faults, each as `preflight` prints it, and the error that stopped it, if any.
 - No names (FR-013).

specs/001-pathway-pdfs/research.md

@@ -939,13 +939,24 @@ embedded.
 **Decision.**
 
 - **FR-011's check** (`check-book`) reads the book with pdfjs. The book is untagged
-  (R4), so it finds the sections by the outline pdf-export wrote and the text at each
-  outline entry's destination, not by a structure tree. It checks every top-level
+  (R4), so it finds each section, not by a structure tree, but at its heading's link to
+  the event's page on the website where an outline or contents entry with its name lands
+  too (or else where such an entry lands, T030, contracts/cli.md), and reads the text
+  there: its heading, the leading text set larger than its page's body text, and its
+  stable identifier. It checks every top-level
   pathway present, every event in the contents and the bookmarks, every section named
   and every section with its stable identifier (two faults), every figure present where
   its source exists, and every link landing on a page. Each fault is seen to fail once
   (SC-007). The release's files are checked before printing, by `book`'s preflight
   (contracts/cli.md).
+  - **Measured 4 Nov on a private copy of release 98's graph** (T030, from #160's review):
+    28 human events have a `<table>` in their summation, so a table wider than the text
+    column, which Chromium printed by scaling its whole part down below the theme's sizes,
+    would have reached the real book: the layout now never overflows (pages.css), and the
+    check reads headings against their page's body text. No human summation holds a
+    `<pre>` block, and no human event's name holds a soft hyphen, a zero-width or
+    variation-selector character or a control: the check's leaving those out of the names
+    it compares is defensive.
 - **SC-008's figure comparison** draws both by the same means, as SC-008 asks: the
   render service's SVG is printed alone by the same Chromium to a one-page PDF at the
   figure's size on the page, on a page with the same `@font-face` rules as the book's