PLang - Interactive markup language for narrative works

A formal language to plan and analyse prose, screenplays, games, etc.

---

This project aims to help:

• 🔗 maintaining logical consistence and keeping track of consequences
• 🧵 organising story threads
• 🔍 tracking introduction and usage of plot points
• 📖 cataloguing the content and monitoring its visibility

in narrative works, regardless of form or topic.

Usage

Requirements

• SQLite3 3.36.0 or higher

Building

Requirements

• A C++17-compatible toolchain (currently tested on GCC and Clang)
• xxd
• CMake 3.13 or higher
• SQLite3 3.36.0 or higher
• antlr4 (included as submodule)

Additionally required for building the command line:

• GNU Readline

Additionally required for testing:

• Catch2 (included as submodule)

Additionally required for building the documentation:

• Doxygen 1.9.1 or higher
• doxygen-awesome-css (included as submodule)

Targets

This repository provides the following build targets:

Target	Description
plang::libplang	Builds the core library
plang::plangcli	Builds the terminal application
plang__doc	Builds the documentation

Design

Syntax

The markup language is agnostic of natural languages. It does not contain keywords, only symbolic operators. While the herein included standard corpus is in English, it may be translated into a different language.

The statement syntax is derived from natural languages and follows a subject→verb→object order. (Additional word orders will be added in later versions.) Namespaces that catalogue the symbols in the corpus may be omitted as long as the statement remains unambiguous.

Take this natural sentence:

Andy eats salad.

Its shortest possible PLang equivalent would be:

[andy] eat: [salad];

Here,[andy] and [salad] are symbols. In PLang, a symbol is anything you can make a statement about. In the example, symbols serve as the subject and the object of what PLang calls a plot point, that is: any statement with at least a subject and a verb.

Its fully-qualified form looks like this:

.character[andy] .character.behaviour.action.eat
          ?what: .world.culture.artifact.food[salad];

The namespaces before the subject, verb and object sort them into the hierarchy of the corpus. These additional namespaces mark the symbols and points as being instances of a class:

• The subject "Andy" is a symbol of the class .character
• The verb "eat" makes the statement a point of the class .character.behaviour.action.eat
• The object "salad" is a symbol of the class .world.culture.artifact.food

These classes, beside many more, are defined in the corpus. The corpus refers to the entirety of information that a work holds. This repository includes such a template corpus to start from.

Explicit reasons and consequences may also be added inline:

.character[andy] .character.behaviour.action.eat
          ?what: .world.culture.artifact.food[salad]
  -< {.character[andy] .world.biology.fauna.sensation.internal.hunger}
  -> {.character[andy] ~.world.biology.fauna.sensation.internal.hunger}
;

meaning

Andy ate salad,
because he was hungry.
(And now he's sated.)

Because specifying these reasons and implications like so would be tedious, the template corpus already includes some obvious ones, so in this case, both causals would be implied.

Structure

This language differentiates between four contexts, each for a specific purpose.

• Plot: Defines the content of the work and its logical coherence
• Story: Orders the content chronologically
• Outline: Maps the story threads onto a presentative outline
• Text: Maps the outline onto the actual work and contextualizes stylistic devices

Files

The interpreter mainly works with two types of files:

• PLang Source File
  MIME type: application/x-plang
  File extension: .plang
  Derived from: plain/text
  
• PLang Database File
  MIME Type: application/x-plangdb
  File extension: .plangdb
  Derived from: application/vnd.sqlite3
  

Executables may also write:

• Log file:
  MIME type: application/x-log
  File extension: .log
  Derived from: plain/text
  

Referencing content in external file will be supported for the following types:

• PDF document
  MIME type: application/pdf
  File extension: .pdf
  Referencing: document sections, pages
• Webpage
  MIME type: text/html
  File extension: .htm, .html
  Referencing: document sections
• ePUB archive
  MIME type: application/epub+zip
  File extension: .epub
  Referencing: document sections
• LaTeX source
  MIME type: application/x-latex
  File extension: .tex
  Referencing: document sections, lines, columns
• Markdown source
  MIME type: text/markdown
  File extension: .md
  Referencing: document sections, lines, columns
• Plain text file
  MIME type: text/plain
  File extension: .txt
  Referencing to: lines, columns

License

The source code contained in this repository is published under the GNU Affero General Public License version 3,
unless specified otherwise in either the file or the containing directory.

See the LICENSE file for the full text.