Appendix D

book.xml

Every book has a file called book.xml that describes it: its details, its parts, chapters and scenes in order, its front and back matter, the Stash, and the ways it’s built. This appendix describes every part of it.

You never need to open book.xml: the Title Page, the Manuscript sidebar, Statistics and Publishing change it for you. It’s an ordinary text file, though, so you can read it in any text editor, and change it by hand with the book closed (see How Septangular changes the file).

The shape of the file

book.xml is written in XML: each part of the book is an element, written between a start tag such as <title> and an end tag such as </title>, or as a single tag ending in /> when it holds nothing. Settings inside a start tag, such as status="draft", are attributes. Anything between <!-- and --> is a comment, which Septangular ignores. Names are case-sensitive: legalName, not legalname.

Inside <book>, these elements are usually in this order, though Septangular reads them in any order.

The <book> element itself must have version="1", and a new book’s also names the format, as in the example below. Every file named in book.xml is written relative to the book’s folder, with forward slashes: manuscript/the-crossing.md.

A complete example

A book with every part filled in. The comments explain each part; a book needs none of them.

<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="urn:septangular:project:1" version="1">

  <!-- The Title Page. Only the title and legal name are required. -->
  <metadata>
    <title>The Lighthouse Keeper</title>
    <shortTitle>LIGHTHOUSE</shortTitle>
    <genre>Literary Fiction</genre>
    <author>
      <legalName>Jane Q. Writer</legalName>
      <penName>J. Q. Writer</penName>
      <surname>Writer</surname>
      <address>
        <line>123 Harbour Road</line>
        <line>Port Ellis, ME 04000</line>
      </address>
      <email>jane@example.com</email>
      <phone>(555) 010-0199</phone>
    </author>
    <!-- For ebooks and print books. -->
    <language>en-GB</language>
    <isbn>978-1-23456-789-7</isbn>
    <publisher>Harbour Press</publisher>
    <description>A keeper, an island, a storm.</description>
    <cover>cover.jpg</cover>
  </metadata>

  <frontMatter>
    <copyright file="matter/copyright.md"/>
    <dedication file="matter/dedication.md"/>
  </frontMatter>

  <!-- 80,000 words by 1 March 2027. -->
  <manuscript target="80000" dailyTarget="500" due="2027-03-01">
    <part title="Part One: The Island">
      <chapter title="The Crossing" target="3000">
        <scene file="manuscript/the-crossing.md" status="revised"
               synopsis="Mara takes the boat out."/>
        <scene file="manuscript/02-the-keeper.md" status="draft"
               title="The keeper"/>
      </chapter>
    </part>
  </manuscript>

  <backMatter>
    <aboutTheAuthor file="matter/about-the-author.md"/>
    <alsoBy/>
  </backMatter>

  <stash>
    <scene file="manuscript/the-old-opening.md" status="draft"/>
  </stash>

  <configurations default="submission">
    <!-- Standard manuscript format: revised and final scenes. -->
    <configuration id="submission" description="Submission">
      <output format="pdf" file="build/lighthouse-submission.pdf"/>
      <output format="docx" file="build/lighthouse-submission.docx"/>
      <include minStatus="revised"/>
    </configuration>

    <!-- A reading copy: drafts too, on smaller pages. -->
    <configuration id="reading-copy" description="Reading copy">
      <output format="pdf" file="build/lighthouse-reading.pdf"/>
      <include minStatus="draft"/>
      <style>
        <font family="Libertinus Serif" size="11pt"/>
        <lineSpacing>1.3</lineSpacing>
        <paper>a5</paper>
        <margins>0.75in</margins>
        <titlePage>false</titlePage>
        <runningHeader>{title} · {page}</runningHeader>
        <chapterHeading>{number}. {title}</chapterHeading>
        <sceneBreak>* * *</sceneBreak>
      </style>
    </configuration>

    <!-- Septangular Publish: an ebook and a paperback. -->
    <configuration id="ebook" description="Ebook">
      <output format="epub" file="build/lighthouse.epub"
              theme="classic"/>
      <include matter="copyright dedication aboutTheAuthor"/>
      <edition name="Ebook" isbn="978-1-23456-790-3"/>
    </configuration>

    <configuration id="paperback" description="Paperback">
      <output format="print" file="build/lighthouse-paperback.pdf"
              trim="5.5x8.5" theme="classic" paper="cream"/>
      <include minStatus="final"/>
      <edition name="Paperback"/>
    </configuration>
  </configurations>
</book>

metadata: the book’s details

<metadata> holds what the Title Page shows. Each is an element holding text; leave out any that aren’t required, and the default is used.

author

manuscript: parts, chapters and scenes

<manuscript> holds the book in order: either <part> elements, each holding chapters, or <chapter> elements directly, never a mix of the two. A book needs at least one chapter, every part at least one chapter, and every chapter at least one scene.

Chapters are numbered straight through the book, across parts, in the order they appear. Titles are used exactly as typed, so type curly quotes in them if you want them.

stash

<stash> holds what’s been moved to the Stash: <part>, <chapter> and <scene> elements, in any order, written just as in <manuscript>. The Stash is never built, and its words don’t count toward the book.

An item in the Stash may have pendingDelete="true": it has been deleted, and waits for your next save with ⌘S, which removes it and sends its scene files to the Trash. Auto-save leaves it waiting.

frontMatter and backMatter

<frontMatter> and <backMatter> list the pages before and after the story, in order. Each page is an element naming its kind. They appear in ebooks and print books only (see Chapter 9), and their files are written as Appendix B describes.

Any kind of page may go in either list.

configurations

<configurations> holds one <configuration> element for each way the book is built: at least one. Its default attribute names the configuration the preview and the Publishing page start with; without it, the first is the default.

A <configuration> has these attributes and elements, its elements usually in this order:

output

Each <output> builds one file. Only format and file are required; the rest belong to ebooks and print books, as the table says, and are refused on other formats.

• Building replaces the file, and makes its folder if need be. A print output also writes its cover template beside it, with -cover-template added to its name.
• Versions leaves the folder each output is written to out of the book’s history. Give outputs a folder of their own, such as build: never the manuscript folder, or your scenes would be left out of the history with it.
• Keep outputs inside the book’s folder, so Septangular can open them for you.

Trim sizes

Width by height, in inches: the sizes KDP Print and IngramSpark offer, and A5.

include

A chapter whose scenes are all left out by status is left out too, and the chapters are numbered without it. A configuration that leaves out every scene can’t be built (see Appendix E).

style

<style> sets how a manuscript looks. Each setting is optional, in any order, and anything left out follows standard manuscript format, the defaults below. In ebooks and print books, only the chapter heading settings apply; their themes decide the rest.

• A length is a number and a unit: pt, mm, cm, in, or em (times the type size): 12pt, 2.5cm, 1.5em.
• Empty means an element with nothing in it: <endMarker></endMarker> or <endMarker/>.
• Fonts: if a PDF manuscript’s font isn’t on your Mac, Septangular uses Times New Roman, then Liberation Serif, then Libertinus Serif, without a warning. A Word manuscript names the font, and Word chooses a substitute if the reader hasn’t got it.
• Paper: a PDF manuscript can use any paper size the Typst typesetting engine knows by name, but a Word manuscript only those in the table, so a configuration with a Word output should keep to them.
• Numbers in words go up to Nine Hundred Ninety-Nine, and Roman numerals to MMMCMXCIX; beyond them, the chapter’s number is written in figures.

edition

<edition> says which edition of the book a configuration makes. Each edition of a published book has an ISBN of its own.

How Septangular changes the file

Septangular writes book.xml only when you save, and changes no more of it than it must:

• Rearranging, adding, renaming and deleting parts, chapters and scenes, and changing statuses, synopses and targets, change only the lines involved. Your comments, indentation and the layout of attributes stay as you wrote them, and a one-line comment directly above a scene or chapter moves with it.
• The Title Page rewrites <metadata> as a whole, in the order above, leaving out what isn’t set. Front and back matter rewrite <frontMatter> or <backMatter>, and the configuration editor rewrites the one <configuration> it changed. A comment inside the element is lost then; a comment just above it stays. Deleting a configuration deletes a comment just above it too.

Edit the file by hand only while the book is closed. Septangular doesn’t watch the file while a book is open: it may write its own version over your changes the next time it saves a change to the book’s structure, and if your changes leave a mistake in the file, your writing is still saved, but the status bar reports the problem and the book is shown as it was, until the file is put right. When you next open the book, your changes are saved as a version, “Changes made outside Septangular”. Appendix C has more.

Messages about book.xml

If book.xml has a mistake, the book doesn’t open, and Septangular shows the message: on the welcome screen, or in the status bar if another book is open. Correct the file in a text editor, save it, and open the book again. The messages, with … standing for the part that varies, and the element they’re about:

A scene whose file is missing doesn’t stop the book opening; see Appendix E.

series.xml

A series’ folder holds a file called series.xml that names the series and lists its books, in order, by their folders inside the series’ folder (see Chapter 10). It may also hold the series’ box sets, a Septangular Publish feature.

<?xml version="1.0" encoding="UTF-8"?>
<series xmlns="urn:septangular:series:1" version="1"
        title="The Skerry Light Books">
  <book folder="the-lighthouse"/>
  <book folder="the-storm-season"/>
  <boxSets>
    <boxSet id="complete" title="Skerry Light: The Complete Series"
            books="all" isbn="978-1-23456-791-0" cover="cover.jpg">
      <output format="epub" file="build/skerry-light.epub"/>
      <output format="print" file="build/skerry-light.pdf" trim="6x9"/>
    </boxSet>
  </boxSets>
</series>

A <boxSet> holds one or more <output> elements, just as a configuration’s, and may hold a <style> for its chapter headings. Its cover and its outputs’ files are named relative to the series’ folder.

Septangular rewrites series.xml as a whole when you rename the series or add or reorder its books, keeping <boxSets> exactly as written. If series.xml has a mistake in it, its books won’t open: Septangular says “The series file beside this book (series.xml) has a problem” and what it is. Correct the file, and open the book again. The messages are much like book.xml’s: “series.xml is not well-formed”, “A <book> in series.xml needs a folder inside the series folder”, “Two box sets are called "…"”, and so on.