Appendix C

The project folder

A book in Septangular is an ordinary folder of ordinary files. This appendix describes each of them, what’s safe to change or delete, and how to back the folder up and move it.

What’s in a book’s folder

A new book’s folder holds book.xml, a manuscript folder with an empty first scene, and empty bible and notes folders. The rest appear as you need them:

Keep each book in a folder of its own. Septangular won’t start a new book in a folder that already has files in it, and Versions keeps every file in the book’s folder in each version, so anything else left there would fill the history.

book.xml

book.xml is the one file a book must have; to open a book, you choose it. Septangular writes it whenever you save a change to the book’s structure, its Title Page, its targets or its build configurations, changing only the part of the file involved. It can be read and edited in any text editor, and Appendix D describes every part of it. Edit it by hand only while the book is closed (see Changing files outside Septangular).

Scenes

Each scene is a Markdown file, described in Appendix B. book.xml names each scene’s file, so a file’s place in the folder has nothing to do with its place in the book: moving a scene in the sidebar changes book.xml, not the file.

• A new scene’s file is named after the scene, in lower case with hyphens: a scene called “The Night Watch” is the-night-watch.md, in the same folder as the scenes near it (usually manuscript). If the name is taken, a number is added: the-night-watch-2.md. The file is made when you save.
• Renaming a scene changes its name in book.xml; its file keeps its name, so its history in Versions stays in one piece.
• A scene with no name of its own is named after its file, without any number at the front: 01-the-crossing.md shows as “The crossing”.
• A file added from elsewhere (with Add Existing Scene File…, or dragged in from Finder) is copied into manuscript when you save, under a free name made from its own; a file from the Trash is moved instead. Plain text and rich text files become .md files. A Markdown file already inside the book’s folder is used where it is.
• A deleted scene’s file goes to the Trash when you save with ⌘S, with its drafts.

Every scene must be inside the book’s folder: Septangular won’t open a file outside it.

Alternative drafts

A scene’s alternative drafts are kept in drafts, in a folder that mirrors the scene’s own path, each draft a Markdown file named as you named it:

drafts/manuscript/03-the-lamp-room/Darker ending.md

A draft is written to disk as soon as you start it, and saved in every version from then on. Since the folder follows the scene’s file, not its place in the book, a scene’s drafts stay with it however you rearrange the book. Drafts are never built or counted in the book’s words. A discarded draft goes to the Trash.

The Story Bible and Notes

• bible/ holds one Markdown file per entry, inside a folder per category: bible/characters/tobias-venn.md. An entry kept directly in bible is listed under “Other”. Appendix B describes an entry’s file, and Chapter 5 how files and folders are named.
• notes/ holds every note in one flat folder; folders inside it are ignored. A note’s kind comes from its file: .md, .markdown and .txt are text notes; a text note whose file starts with a url: line between two lines of --- is a link; .png, .jpg, .jpeg, .gif, .webp and .svg are pictures; .pdf a PDF; .docx and .doc Word documents. See Chapter 6.

Unlike changes to the book’s structure, adding, renaming, moving and deleting entries and notes happen on disk straight away. A deleted entry or note goes to the Trash. The next save records the change in Versions.

The Outline, front and back matter

• outline.xml holds the Outline: its items, their notes, the scenes each is linked to (by file), and the plotlines. Septangular writes the whole file each time you save a change to the Outline. If it has a mistake in it, the book won’t open until it’s put right (see Appendix E).
• matter/ holds the front and back matter pages you write, each a Markdown file named after its kind (matter/copyright.md, matter/about-the-author.md) or, for an other page, its title. Put an author photo in this folder too. A page’s file is made as soon as you add it; Remove from Book (Keeps Its File) leaves the file there.

The build folder

A new book’s configurations write into build, as each configuration names (Chapter 9). A print book’s cover template goes beside its interior. The Writing Record… is saved here too, unless you choose elsewhere.

Inside build, a hidden .septangular folder holds the working files of builds and the preview. You can delete the whole build folder at any time: the next build makes it again. The folders your configurations write to are left out of the book’s history, so keep builds in a folder of their own, not among the scenes.

The hidden .septangular folder

Every book’s folder has a hidden folder called .septangular. Finder doesn’t show it unless you press ⇧⌘. in a Finder window. It holds:

Snapshots, session marks and published editions are kept inside the history, not as separate files. A folder called snapshots at the top of the book’s folder is left alone, and left out of the history. See Chapter 8 for what else the history leaves out.

A series’ folder

A series is a folder holding its books, each in a folder of its own laid out as above, with what they share:

Each book’s own .septangular folder still holds its auto-save setting. A book added to the series from elsewhere keeps its earlier history there, while its versions from then on are the series’. A book is in a series when the folder above it has a series.xml that lists it. Chapter 10 has the rest.

What happens when a book opens

When you open a book, Septangular:

1. reads book.xml, and stops with a message if it has a mistake in it (Appendix D lists the messages);
2. reads outline.xml, if there is one, and stops if that has a mistake;
3. looks in the folder above for a series.xml that lists the book’s folder, and if it finds one, uses the series’ Story Bible and history;
4. opens the history, starting one if there’s none, and saves any changes made to the folder since the book was last open as a version of their own, “Changes made outside Septangular”;
5. reads the scenes, to count their words, and the Story Bible, notes and drafts.

A scene whose file it can’t find doesn’t stop the book opening: the scene shows in red, struck through, and the status bar counts it as a problem (see Appendix E).

To open a book, choose its book.xml with File → Open Project… ⌘O. For a book in a series you can choose the series’ series.xml instead, which opens the book you had open last (or the first).

Changing files outside Septangular

Every file in the folder is yours to open in any other program. The safe way to change them is with the book closed. When you open it again, Septangular reads everything afresh and saves your changes as a version, “Changes made outside Septangular”, so you can see exactly what changed in Versions.

Septangular doesn’t watch the folder while a book is open. If you change a file outside it while the book is open:

• A scene, entry or note that Septangular has already opened keeps the text it read. If you then change it in Septangular and save, its text replaces yours. One it hasn’t opened yet shows your changes when you open it.
• book.xml: your changes may be written over by Septangular’s own the next time it saves a change to the book’s structure. And if they leave a mistake in the file, saving still saves your writing and records a version, but the status bar reports the problem, and the book is shown as it was until you put the file right.

So close the book (⌘W) before editing its files elsewhere, and open it again afterwards.

Backing up and syncing

To back up a book, copy its whole folder: book, history and all. Copying the folder in Finder, or backing up with Time Machine, includes the hidden .septangular folder. Whatever you use, make sure it copies hidden folders too: without .septangular the book is safe, but its history isn’t. For a series, back up the series’ folder, which holds every book and the shared history.

A book can live in a folder that a sync service keeps in step between computers. Open it on one computer at a time, and let the sync finish before you open it on another, since Septangular writes to the folder, and its history, whenever it saves.

Moving or renaming a book’s folder

Everything in book.xml is named relative to the book’s folder, and the history is inside it, so a book can be moved or renamed as a whole. Close the book first, move or rename the folder in Finder, then open it with File → Open Project…. If it was the book open when you last quit, Septangular starts at the welcome screen instead, since the book isn’t where it was.

In a series, move or rename the series’ folder as a whole in the same way. Don’t rename a book’s folder inside a series by itself: series.xml lists each book by its folder’s name, so the book would open on its own, without the series’ Story Bible or history. If you must, close the book and change the folder’s name in series.xml to match.

Your own settings and profile

A few things belong to you rather than to a book, and are kept in Septangular’s folder in your Mac’s Library, at Library/Application Support/Septangular in your home folder. (In Finder, hold ⌥ and choose Go → Library to see it.)

None of these are part of any book or its history. To keep your profile, back this folder up too.