Appendix E

Troubleshooting

Problems you might meet, what Septangular says about them, and what to do. Most messages appear in the status bar at the bottom of the window, in red; if one is cut short, hover over it to read the whole of it.

Installing

Windows says “Windows protected your PC”

Windows says this about an installer it doesn’t yet know. Click More info, then Run anyway.

The AppImage won’t start on Linux

An AppImage needs FUSE: install your distribution’s libfuse2 package. Make sure the file is executable, too (chmod +x and its name). On Ubuntu 24.04, if it still won’t start, run it from a terminal with --no-sandbox after its name. Or install the .deb package instead.

Opening books

Septangular started at the welcome screen, not at my book

Septangular reopens the book that was open when you quit. On a Mac, it starts at the welcome screen if you closed the book’s window before quitting; on Windows and Linux, closing the window quits, and the book reopens. It also starts there if the book has been moved or renamed since. Choose Open Project… and choose the book’s book.xml.

The outline, timeline or style settings are empty, and the status bar shows a problem

The file behind them, outline.xml, timeline.xml or style.xml, has a mistake in it, perhaps from editing it by hand. The book opens anyway; hover over the problem in the status bar to see what’s wrong and where. Septangular leaves the file alone and never saves over it. Put it right in a text editor and it’s read again at your next save, or restore it from an earlier version (Chapter 8). If you make a change there, Septangular offers Start Afresh: the broken file is kept beside it, renamed (timeline-broken.xml, say), and a new one is started.

A book won’t open

Septangular shows why: on the welcome screen, or in the status bar if another book is open. The usual reasons:

• A mistake in book.xml, usually after it was edited by hand. The message says what’s wrong and often where, such as XML syntax error at 12:5 or <chapter title="The Crossing"> has no scenes. Appendix D lists the messages and what each means. Correct the file in a text editor and open the book again.
• A mistake in outline.xml, the Outline’s file: outline.xml is not well-formed, outline.xml should start with <outline>, or An <item> in outline.xml needs a title attribute. Correct it the same way.
• The wrong file chosen. Choose the book’s book.xml, or for a book in a series, the series’ series.xml. Cannot read project file means the file can’t be read at all.

A scene is in red and struck through

Septangular can’t find the scene’s file. The book still opens, the status bar counts a problem (hover over it to read Scene file not found: and the file’s name), and builds that include the scene stop with the same message. The scene can’t be opened until its file is back:

• If you moved or renamed the file in Finder, move it back, or give it back its name.
• If you deleted it in Finder, open the Trash, right-click the file and choose Put Back.
• Otherwise, go to Versions and select a version from before the file went. Its list of changes shows the file as Deleted since; click Restore beside it.

If you don’t want the scene, delete it from the book: right-click it, choose Delete, then save with ⌘S. A page of front or back matter whose file is missing shows the same way, and Remove from Book (Keeps Its File) on its right-click menu takes it out.

The status bar says there are problems

Hover over “1 problem” (or however many) to see them. Besides missing scene files, it reports two Story Bible entries sharing a name: “Will” names both Will Turner and Will Ashby; it will be linked to Will Turner. Give one of the entries a different name or other name; see Chapter 5.

A book in a series opened without its series

If the series bar is missing and the Story Bible is empty, Septangular didn’t find the book in its series. A book is in a series when the folder above it has a series.xml that lists the book’s folder by name. The book’s folder was probably renamed or moved out of the series’ folder. Close the book, put the folder back where it was, and open the book again. (If series.xml itself has a mistake, the book won’t open at all, and Septangular says what’s wrong: correct the file as Appendix D describes.)

Septangular won’t start a new book where I chose

Septangular makes each new book in a folder of its own. It says There’s already a book in “…”. Open it with File → Open Project… instead. if the folder holds a book, and The folder “…” already has files in it. Choose a new name for the book. if it holds anything else. Give the book a new name, or choose another place.

A book should never share its folder with other files: Versions keeps everything in the book’s folder in each version, so the history would fill with them. If you have a book.xml in a folder with other things, close the book, make a new folder, and move the book’s files into it: book.xml, manuscript, bible, notes and the others in Appendix C, including the hidden .septangular folder.

There’s a version I didn’t save, called “Changes made outside Septangular”

When a book opens, Septangular saves anything in its folder that changed while it was closed, such as a scene edited in another program or a file deleted in Finder, as a version of its own. Select it in Versions to see what changed, and restore anything you didn’t mean to change.

Starting from Word or Scrivener

The chapters aren’t where they should be

Before you click Make Book…, try each choice under Chapters start at, or for Scrivener, The Draft’s top-level folders are, and watch the list of chapters change. For a Word document:

• Word’s heading styles need each chapter’s title in a heading style, such as Heading 1. If they aren’t, apply the style to each chapter title in Word, save, and start again.
• Lines like “Chapter 12” need each chapter to start with a short line of its own, such as “Chapter 12”, “CHAPTER TWELVE”, “Prologue” or “XII”.
• Page breaks need a page break before each chapter.

If scenes run together, put a line holding just #, *** or ~ between them in the document, and start again.

If you’ve already made the book and it’s wrong, the document or project you started from is unchanged. Close the new book, move its folder to the Trash, and start again. Or put the book right in Septangular: Split Scene at Cursor, Combine with Next Scene and dragging in the sidebar (Chapter 3).

Septangular won’t read the file

Working with an editor

“… isn’t an editor’s copy from Septangular”

Review an Editor’s Changes… needs the very file you sent, opened and saved by your editor: it carries a hidden record of which scene is which. A new document, even one with the book pasted into it, doesn’t. Ask your editor to send back the file itself.

“Which copy is this?”

Some programs, when they save a Word document, drop the hidden record of what was sent, but keep the invisible marks at the start of each scene. Septangular then asks which of your “Sent to” snapshots the copy came from; choose it, and the review goes on as usual, comparing the copy with the book as it was then.

“… was sent from another copy of this book”

The copy was made from another copy of the book’s folder, one whose history this one doesn’t have, such as a copy on another computer, or a backup made without the hidden .septangular folder. Open the copy of the book you sent it from, and review it there.

Some of the editor’s changes aren’t listed

Changes to scenes you’ve since deleted, or moved to the Stash, aren’t shown: the review says which. Changes only to the typography, such as straight quotation marks made curly, aren’t counted as changes.

Saving

“You have unsaved changes.”

Septangular asks before closing the window, quitting, or opening or starting another book while there are changes you haven’t saved. Cancel takes you back, so you can save with ⌘S. Discard Changes goes on without them: every change since the last save, or auto-save, is lost.

“Couldn’t save:”

The save didn’t finish: no version was recorded, and the window still shows your changes as unsaved. The rest of the message says why. If it’s about the disk, make room or check that you can still write to the book’s folder, then save again. Until a save works, don’t close the window.

“book.xml has a problem, so the book is shown as it was”

The status bar reports this, as a problem, when book.xml was edited in another program while the book was open and now has a mistake in it. Your writing was saved, and recorded as a version, all the same. Until the file is put right, Septangular shows the book’s parts, chapters, scenes and settings as they were before the change, and changes to the book’s structure can’t be made. Hover over the problem to read what’s wrong, then correct book.xml in a text editor (Appendix D), or restore it from an earlier version (Chapter 8). The next save clears the problem.

A deleted scene is still in the Stash

Deleting takes two steps. Delete moves the scene into the Stash, struck through, and the status bar says “1 delete waits for Save (⌘S)”. Only saving with ⌘S finishes it; auto-save leaves it waiting. Until then, right-click it and choose Undelete to change your mind.

Changes I made in another program were lost

Septangular doesn’t watch the book’s folder while the book is open. If it had already opened a scene, and you then changed the scene elsewhere and changed it again in Septangular, its save wrote its own text over yours. Close the book before editing its files in another program; see Appendix C. If your changes were ever saved in a version, Edit → Find in History… ⌥⌘F can find them.

Getting things back

I deleted a scene

• Before saving: find it in the Stash, struck through, right-click it and choose Undelete.
• After saving: its file is in the Trash. Right-click it there and choose Put Back, which returns it to the book’s manuscript folder, then drag it from Finder onto the Manuscript sidebar, or use + → Add Existing Scene File…. You can also drag it straight out of the Trash onto the sidebar.
• If the Trash has been emptied: choose Edit → Find in History… ⌥⌘F. Under Files no longer in the project, find the scene and click Bring Back to the Stash. It comes back into the Stash, ready to drag into the book; save to keep it there.

I deleted a note or a Story Bible entry

Notes and entries go to the Trash as soon as you delete them, so Put Back in the Trash brings them back where they were. Or use Find in History…: under Files no longer in the project, click Bring Back. Septangular saves before deleting an entry, so its latest text is always in Versions. A note is in Versions only if it was there at a save before you deleted it.

In a series, every book shares the Story Bible, so an entry deleted in one book is gone from them all, and comes back to them all.

I cut a passage I want back

Edit → Find in History… ⌥⌘F searches every saved version. Type a few words you remember; each paragraph that ever held them is listed with the scene it was in and when it was cut. Copy copies it, ready to paste. See Chapter 8.

For something you’ve only just cut, ⌘Z is quicker: each scene keeps its own undo history until you close the book.

I restored a version, and want my work back

Before any restore, Septangular saves your work as a version, so a restore can always be undone, though not with ⌘Z. Go to Versions and tick Show every save. The newest version is the restore, “Restored …”; the one just below it is your work as it was before. Select it and choose Restore Everything to This Version, or restore just the files you need from its list of changes. See Chapter 8.

I used a draft, or discarded one

Right after Use This Draft…, ⌘Z (Edit → Undo Use Draft) puts the scene’s text and the draft back as they were. Even later, nothing is lost: the scene’s earlier text is kept as a draft called “Before …”. A discarded draft goes to the Trash, and Versions keeps it once it has been saved.

Building

“Configuration "submission" includes no scenes”

A configuration builds only scenes of the statuses it includes. A new book’s Agent / publisher submission takes revised and final scenes, and a new scene is a draft, so at first it has nothing to build. Mark the scenes that are ready as revised (right-click them, Status), build the Reading copy (drafts included) instead, or change which scenes the configuration includes (Chapter 9).

Some scenes are missing from the built book

The build’s results say how many scenes were left out by status, as in “3 scenes left out by status”: their status is below what the configuration includes. A chapter whose scenes are all left out is left out too. Scenes in the Stash are never built.

A build stops with a message

The message shows in red under the Build button:

The build lists problems

A build can finish and still list problems under its results. They’re warnings: the book was built, but something in it may not be as you meant. The commonest:

• Heading "…" ignored: chapter titles come from book.xml, Lists are rendered as plain paragraphs, and other warnings about what a scene holds: Appendix B explains each. If a paragraph is missing from the book, look for a line of --- directly under it, with no blank line between: that makes the paragraph a heading, which is left out.
• Also By is left out or Next in the Series is left out: those pages list or show the series’ books, and this book isn’t in a series, or is its last book.
• … still links to example.com: put your own link there. The newsletter page still has its starting link.
• The cover is … pixels. Stores ask for a cover at least 1,400 pixels wide; 1600 × 2560 is usual.
• The book is … pages: a print book shorter or longer than KDP Print allows for its binding.
• A picture “prints only … inches wide”: use a larger picture for print.

The ebook or print book is only a sample

Ebooks and print books are part of Septangular Publish. Without a licence on this computer, they’re built as a sample of the first three chapters, with the front matter, a closing page saying it’s a sample, and no back matter. The build’s results say so: “(sample: the first 3 of 24 chapters)”.

To unlock the whole book, with a book open, choose Septangular → Septangular Publish…, paste your licence key, which starts SEPT-, and click Unlock. Then build again. If the key is refused, the message says why:

• That isn’t a Septangular licence key. Keys start with “SEPT-”. Copy the key from its start.
• The licence key is incomplete. Copy all of it, from “SEPT-” to the end. Part of the key is missing.
• The licence key doesn’t check out. Copy all of it exactly, from “SEPT-” to the end. The key has been changed or mistyped: copy and paste it rather than typing it.
• This licence key is for a different version of Septangular. Write to us (see below).

A licence is kept on the computer you enter it on. To move it to another Mac, choose Remove Licence from This Computer… on the first, then enter the key on the second.

The licence says it needs renewing

A licence includes a year of updates. It unlocks every version of Septangular released within that year, for good, but not versions released after it, which say Needs renewing for this version and build samples. Either renew it and enter the renewed key with Enter a Renewed Key…, or keep using a version released while your licence covered updates.

The book isn’t in the font I chose

The font must be installed on your Mac, and its name typed as the Mac knows it. If a PDF manuscript’s font isn’t found, Septangular uses Times New Roman instead, without a warning. A Word manuscript names the font, and Word substitutes another if it isn’t installed where the file is opened.

The window and the editor

The sidebar has disappeared

Choose View → Show Sidebar ⌃⌘S, or click the heptagon at the top of the section icons. If the section icons and status bar have gone too, you’re in focus mode: press Esc. To put the sidebar back to its usual width, double-click its right edge.

The text in the editor is too small or too large

Choose View → Editor Text Size, from 14 to 24 (17 is the default), and View → Editor Font for the typeface. They change only how the editor looks, never the finished book, and Septangular remembers them for every book.

If everything in the window is larger or smaller than it should be, it has been zoomed: View → Actual Size ⌘0 puts it back.

A command says to open a scene first

Formatting, splitting, combining, moving a scene and Scene History… act on the scene open in the editor. If none is open, the status bar says so, as in “Open a scene to format its text.” Click a scene in the Manuscript sidebar, then try again. While a scene shows one of its alternative drafts, split and combine wait until you switch back to Original above the editor.

Reporting a problem

If something isn’t working as this manual says, write to info@septangular.com. Please include:

• the version of Septangular you have, from Septangular → About Septangular (on Windows and Linux, Help → About Septangular);
• the version of macOS, from Apple menu → About This Mac, or of Windows or Linux;
• what you did, what you expected, and what happened instead;
• any message Septangular showed, word for word;
• whether it happens every time.

There’s no need to send your book. If a book won’t open, the message, and book.xml if you’re happy to share it, are usually enough.