decisions.md

Blame: the commit that last changed each line · file · history

`a6d0aed2` 2026-10-24 Pavel Safronov	1	# Decisions
	2
	3	Each design or technical decision, why it was made, and when. Newest last.
	4
	5	## From the blog script (October 2026)
	6
	7	auto-print started as one script in the author's Dropbox-synced blog folder. These decisions were made there.
	8
	9	1. Read manuscripts as `gfm`. It matches how GitHub, GitLab and the VS Code preview show the files.
	10	A single line break is a soft break, so a manuscript with one sentence per line gives the same book as one with one line
	11	per paragraph. This was checked on three full books with pandoc 3.6.1: the epub, html and docx text was identical.
	12	2. Publish only one section of a manuscript (`## Writing` by default). Manuscripts keep notes, spelling lists and cut
	13	scenes next to the story, and these must never reach a reader.
	14	3. The source files are never changed. The build reads them and writes only to the output folder.
	15	4. Collections are an index file with links, not a list of files in the config. The index file is where the author
	16	already keeps the story order, so the order lives in one place. A link in an HTML comment is skipped, which is how a story
	17	that is not ready is kept out.
	18	5. A story's opening text moves below its title in a collection. Otherwise each story's content warning would land at the
	19	end of the previous story.
	20	6. Extra pages are sections of the source file, named in the config. The author did not want a separate file per page.
	21	Naming them in the config, instead of recognising fixed names, means a section is never published by accident.
	22	7. The shallowest heading wins when a name is used at several levels. A real case: an `## Info` section held
	23	`### Characters` notes with spoilers, next to a reader-facing `## Characters` page. Two headings with the same name at the
	24	same level stop the build, because there is no safe way to choose.
	25	8. The epub's flowing layout is built in the markdown, not with pandoc's `--shift-heading-level-by`. Extra pages need
	26	their own epub files (level 1 headings) while the story stays in one file. Doing the shift in the markdown, under a level 1
	27	heading with the book title, gave byte-identical epub files to pandoc's own shift for books without extra pages.
	28	9. Only pandoc's known epub roles are used. pandoc puts `dedication`, `copyright-page` and `preface` in the front matter
	29	and `appendix` in the back matter. An unknown role is treated as story text, so front pages default to `preface` and back
	30	pages to `appendix`.
	31	10. pandoc extensions `attributes`, `raw_attribute` and `fenced_divs` are on. The assembled markdown uses them to mark
	32	the extra pages, the page breaks and the dedication. They were turned on only after checking that none of the existing
	33	manuscripts contained `{` or a line starting with `:::`, and that the books came out identical.
	34	11. Page breaks are written per format: a raw Word page break in the docx, a `page-break` div in the html for the pdf,
	35	and nothing in the epub, where a new file is a new page.
	36
	37	## As a package (2026-10-24)
	38
	39	12. No runtime dependencies. Only Node's built-in modules. The external tools (pandoc, a browser, Kindle Previewer) are
	40	run as commands. Fewer dependencies means less upkeep.
	41	13. TypeScript that Node can run directly (`erasableSyntaxOnly`, `.ts` imports). The author's blog runs the source from a
	42	clone with `node src/cli.ts`, so there is no build step to forget. Installed packages live in `node_modules`, where Node
	43	does not run `.ts` files, so the published package runs `dist/`, compiled by `tsc` (`rewriteRelativeImportExtensions`).
	44	14. Every path in the config file is relative to the config file's folder. One rule for `source`, `cover` and `outDir`.
	45	15. `author` has no built-in default. The blog script defaulted to its own author, which would be wrong for anyone else.
	46	16. The docx dedication style comes from a reference doc (`assets/reference.docx`). A Word paragraph style is the only way
	47	pandoc can center a paragraph in a docx. The file is pandoc's default template plus one style, made by
	48	`scripts/make-reference-docx.sh`. For a book without a dedication, the only change in the docx is one unused style.
	49	17. Tests use Node's built-in test runner, again to avoid dependencies. The pandoc tests check pandoc's syntax tree of the
	50	assembled markdown, and skip themselves when pandoc is not installed.