Skip to content

Latest commit

 

History

History
189 lines (141 loc) · 6.62 KB

README.md

File metadata and controls

189 lines (141 loc) · 6.62 KB
Raw

 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

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:

Additionally required for testing:

  • Catch2 (included as submodule)

Additionally required for building the documentation:

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.