Compiling a Long Document

A thesis, a report, a paper, a book: too big for one page, and written in pieces. In MojoPad those pieces are ordinary pages in a folder — and File ▸ Compile… turns the folder into the finished thing, in the order the pages sit in your sidebar.

Three people who need this

• The academic with a paper due. Abstract, Introduction, a Method folder holding Participants and Measures, Results, Discussion. Each is its own page, written on its own day. Compile hands you the manuscript, with the headings already in the right order and at the right level.
• The consultant writing a report. Sections drafted out of order, some borrowed from the last report, one still a stub. Compile whenever you want to see the whole thing, send the PDF to a colleague, and go back to editing pieces.
• Anyone with a long argument. Writing in pieces keeps each piece short enough to finish. The document only has to exist at the end.

How it works — the one rule

How deep a page sits decides its heading level. A page at the top of the folder becomes a top-level heading; a page inside a sub-folder becomes a heading one level down; the sub-folder itself becomes the heading above them. The page's own headings slide down to sit underneath its title, so nothing ends up outranking the section it belongs to.

It's the same rule a storyboard uses when it becomes a paper — structure in, document out.

Doing it

1. Put the pieces in a folder. One folder per paper. Drag the pages into the order you want to read them; nest a sub-folder wherever a section has parts.
2. File ▸ Compile… and pick that folder. (Sub-folders are listed too, so you can compile a single chapter.)
3. Choose how it should read. Names become headings gives each page and folder its own heading — turn it off if your pages already carry their own titles. Start with a title page puts the folder's name and today's date on a page of their own. Each part on a new page keeps top-level sections from running together on paper. Keep MojoPad's automatic links is off, and the next paragraph explains why you probably want it left that way.
4. Choose what you get. Make a page writes the whole thing into a new page in this wiki — the one to use while you're still working, because you can then polish it, and everything in MojoPad works on it. Or write a file straight out: PDF, Word, Markdown, plain text.

Your folder is never touched. Compile as often as you like — each run makes a fresh page or a fresh file, so there's no state to keep track of and nothing to undo.

The second time, and the twentieth

A paper gets compiled far more than once: after every session, and three times in the hour before you send it. So the first run asks its questions and every run after that asks nothing.

File ▸ Compile Again (⌥⌘B) rewrites the same file, from the same folder, with the same options — no folder to pick, no panel, no save sheet. The status line tells you it went. It is the one to learn, because it is the one you will use twenty times.

It will not guess. If the folder has been deleted, or the file has been moved or renamed or sent somewhere, MojoPad says so and opens the full Compile instead of quietly writing a new file where you no longer expect one.

And the first run asks a smaller question than it used to: the folder holding the page you are on is listed first, along with the folders above it, so after an hour of writing inside a paper the paper is already at the top of the list rather than somewhere in it.

Links between your own sections keep working in the finished file. Where one section links to another that is also in the compile, the link survives as a live jump — in the PDF and in the Word file both, so a reader can follow your cross-references without leaving the page they are on. A link to a page you did not compile becomes ordinary text instead of a dead link, since the page it wanted is not in the file.

The two kinds of link, and why only one belongs in a paper

Inside your wiki, MojoPad links for you: every phrase that happens to match a page name lights up, whether you meant it to or not. That is exactly right while you are reading and thinking — it is how you find the note you forgot you had.

It is exactly wrong in a manuscript. If you have a page called Attention, then every one of the ninety times the word appears in your paper becomes a live link — in your running prose, in your block quotations, and in your reference list, where an author's surname matching a page name turns a citation into a hyperlink. Nobody wants to submit that.

So Compile leaves them out. The links you made yourself are untouched — a cross-reference you built between two of your own sections still works, which is the whole point of the previous paragraph. It is only the automatic ones that are dropped, and Keep MojoPad's automatic links puts them back if you are compiling something that is going to be read as a wiki rather than as a paper.

Paper size, margins, line spacing, type size and page numbers come from Settings ▸ Files & Backups ▸ Paper. A journal asking for A4, one-inch margins, 12 point and double spacing is four choices there, made once.

If your journal prints at a size that isn't on the list, it is still there. Besides US Letter and A4 there is B5 and A5, and Custom… takes the trim straight from the guidelines — in millimetres or inches, whichever they quoted it in. Choosing Custom starts from the size you were already on, so you only change what actually differs.

When the margins are not the same all round — a wider inside edge for binding, a deeper foot for a running head — set Margins to A side each and give the four their own numbers. It starts from the margin you already had, so nothing moves until you move it.

The notes block

Compile already does the hard part with footnotes: every section's notes are gathered into one list at the end and renumbered straight through, so a paper written in twelve pieces does not arrive with twelve lists all starting at 1. A note whose reference you deleted is kept rather than dropped, at the end of the list, where you will see it.

What it could not do was make that list look the way a journal asked. Three controls appear in the Compile panel when the folder actually has notes in it:

• Notes are numbered — 1, 1), [1] or (1), applied to the reference in the text and to the note itself, together. The bracketed and parenthesised styles also sit on the line rather than raised above it, which is how a journal that asks for them expects to see them.
• Under the heading — type Endnotes, Notes, References, whatever yours calls it, and it goes above the block as a heading of its own. Leave it blank and you get the plain rule the notes have always had.
• Notes start on a new page — otherwise they begin immediately after your last line, halfway down a sheet.

These shape the PDF and the Word file — the two things you send somebody. Compiling to a page in your wiki, or to Markdown, leaves the notes exactly as they are, because those are documents you carry on working in and a numbering style baked into one is a thing you would have to undo by hand later.

One more difference in those two: the little ↩ that takes you back from a note to its place in the text is a convenience for reading on a screen, and it is left out of the PDF and the Word file. It was appearing in submitted manuscripts.

Planning a section before you write it

Open the Draft pane (the palette panel, beside Info and Context) on any page and you get the three things a long-form writer keeps beside the text rather than in it:

• What this section is about. A line or two — the promise the section makes. Write it when the section is still an intention and nothing else exists yet; it shows wherever the page is listed, so the shape of the paper is readable long before the paper is. It is never part of the writing and never exported.
• A word target. Type the number you're aiming at and the pane shows how far along you are, with a bar that turns green when you get there. Compile adds them up: open it on a folder and it tells you the whole paper's words against what its sections were aiming at.
• Notes to yourself. Check that figure. Ask Sara whether the 2019 numbers are final. This paragraph is borrowed from the grant application. They sit beside the page, they turn up in search when you go looking, and they are never exported and never printed — so the thing you'd otherwise scribble in the margin and have to remember to delete can simply stay.

What comes along, and what doesn't

• Everything a page holds comes: pictures, tables, quotes, equations, diagrams, footnotes, and pages you've embedded with ![[Page name]].
• Pages you've marked Skip on export stay out, which is how you keep a scratch page or a private note inside the folder without it turning up in the manuscript.
• Encrypted pages stay out too — a locked page is locked.

Working this way

Keep a Research sub-folder in the same paper folder and mark those pages Skip on export: your sources live beside the writing, in the same place, and never leak into the output. Open one beside your draft with ◫ Split while you write — and if you'd rather listen than read, the speaker reads whichever pane you're pointing at.