monkeytale 0.3.3

An opinionated markup language for composing, documenting, and visualizing a novel outline.

MonkeyTale

"The book is a program." --- Pollen by Matthew Butterick

MonkeyTale is an OPML markdown language for documenting and composing a story world and its novels. It adds some syntax rules on top of Workflowy's OPML extract. From that it tries to crete the best machine-readable world and manuscript structures from which plugins can create output. These plugins can generate Word documents for editor submissions or scene flows, or whatever else someone comes up with. They can even change the structure.

Design Principles

• Derive as much as possible from the text itself before adding in syntax.
• Document what is written, let plugins report on the structure and content, and then gather the results.
• Set up and forget.

Interface Decisions

MonkeyTale syntax expects to live in Workflowy as the writing platform and OPML source. Theoretically, any OPML generating system could be used.

An OPML export will be given to the MonkeyTale parser by committing it to a git repo. The parser will then pass the generated structure and content on to each available plugin, to do whatever it does.

MonkeyTale will recognize the following structural block hierarchies:

• Manuscript, Part, Chapter, Subheading, Scene, Quote, and Verse
• Backstory, @Character, and #Setting

Each block is an outline item, where each higher level block contains one or more outline line items itself. Block nesting can skip levels, for example a Manuscript could consist of only a single Paragraph.

The character and setting are prefixed with @ and # respectively, two special markers in WorkFlowy making finding and filtering content much easier.

The nesting chains look something like this:

flowchart TB
    subgraph Narrative ["<b>Narrative</b>"]
        direction TB
        M[Manuscript] ==> MPT[Part] ==> C[Chapter] ==> MH[Subheading] ==> MSC[Scene] ==> MQ[Quote] & MV[Verse] ==> MPR([Paragraph])
        M -- series of --> M
    end

    subgraph StoryWorld ["<b>StoryWorld</b>"]
        direction TB
        B[Backstory] ==> SWPT[Part] ==> A[Actor] & ST[Setting] ==> SWH[Subheading] ==> SWSC[Scene] ==> SWQ[Quote] & SWV[Verse] ==> SWPR([Paragraph])
        A -- alias --> A
        ST -- contains --> ST
    end

Or, more accurate and convoluted, here is a diagram of which components may be nested.

flowchart TB
    subgraph Narrative ["<b>Narrative</b>"]
        M[Manuscript]
        C[Chapter]
    end

    subgraph StoryWorld ["<b>StoryWorld</b>"]
        B[Backstory]
        A[Actor]
        ST[Setting]
    end

    subgraph Sections ["<b>Sections</b>"]
        PT[Part]
    end
    
    subgraph Content ["<b>Content</b>"]
        direction TB
        H[Subheading]
        SC[Scene]
        Q[Quote]
        V[Verse]
        PR([Paragraph])
    end
    
    M ==> PT & C & Content
    M -- series --> M

    B ==> PT & A & ST & Content
    
    PT -. underneath\nManuscript .-> C
    PT -. underneath\nBackstory .-> A & ST
    PT ==> Content

    C ==> Content

    A ==> Content
    A -- alias --> A
    ST ==> Content
    ST -- contains--> ST

    H ==> SC & Q & V & PR
    SC ==> Q & V & PR
    Q & V ==> PR

Block Names

All non-paragraph blocks are identified by starting with their block type followed by a colon. Anything starting with the first non-whitespace character following the colon is deemed the name of the block. Any child bullets underneath will be considered the content of the block. And so, "Manuscript: Ye Olde Booke. " would be interpreted as a manuscript block with "Ye Olde Booke." as its name.

For header blocks, which includes quote and verse, the name is the header title. For the non-header block scene the name is considered to be an outline. A paragraph block has no block type or name. Its text is the paragraph content itself.

In Workflowy each outline item---bullet---can have its own note. The notes of blocks have a special meaning for MonkeyTale. It is in these notes that five additional pieces of information can be written:

1. Point-of-view character (PoV)
2. Setting
3. Time
4. Relationships with other blocks
5. Continuity notes

While each item is optional, there are some requirements as to their order.

The three anchoring items, PoV, setting and time, must reside on the first line, but within that line can be in any order. A line is defined as any text following a return/enter and ends in a return/enter.

Following the anchors are relationships. Each relationship occupies a whole line holds a description of the relationship and a WorkFlowy link to the related block. The order of these two has meaning. The relationship is meant to be read as an English sentence where the current block is assumed on the opposite side of the description than the link. For example these links below, where ... represents the imagined current block:

• [Linked block] foreshadows ...
  the direction is from link to current
• ... foreshadows [Linked block]
  the direction is from current to link

The first line that cannot be a relationship is that start of any continuity notes. This text continues until the end of the WorkFlowy note or until a line containing only "---" or "===" is encountered.

Text beyond the "---" is reserved for future use. Text beyond "===" is ignored by MonkeyTale.

To-Dos

Technology Decisions

MonkeyTale needs to work without any software installed on the user's system other than a browser, which is assumed to be already present.

• Workflowy as writing platform. Workflowy supports multi-platform, offline editing.
• Github as the store for exported OPML and the associated MonkeyTale plugin outputs. Github supports multi-platform offline storage to read or backup the MonkeyTale plugin output.
• Github Actions as execution platform, so nothing will have to be installed on the user's system other than Github Desktop. There is no offline alternative to refresh the MonkeyTale plugin output.
• Github Repo Templates as the quick start template.
• Python 3 as the programming language for MonkeyTale and any plugins that folks might want to build.

Development

I am building MonkeyTale to improve insight into my own writing and to learn more about software development.

MonkeyTale is developed in my spare time and uses Semantic Versioning and Semantic Release to track its, equally spare, progress.

As per Semantic Versioning: "Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable."

Check the change log for the latest updates.