Terrace/docs/pages/about.tce

layout layout.njk
title About - Terrace - A simple structured data language
description
  A simple structured data syntax for configuration, content authoring, and DSLs.
  Terrace gets out of your way to let you just write

Section dark
  class flex flex-col md:flex-row gap-16

  Block
    class w-full lg:w-1/3
    TableOfContents

  Block
    class max-w-prose

    Heading 1 About Terrace

    Markdown
      Terrace is a tiny system for storing data in human-friendly text files.

      It allows you to mix all sorts of text and data formats together in an intuitive way without getting caught up in syntax pomp and ceremony.

    CodeBlock terrace
      title An Essay on Rockets
      date 2022-02-22
      by John Doe

      heading The ideal rocket equation

      equation LaTeX
        \Delta v=v_{\text{e}}\ln {\frac {m_{0}}{m_{f}}}=I_{\text{sp}}g_{0}\ln {\frac {m_{0}}{m_{f}}}

      markdown
        A fundamental equation in astrophysics, the *ideal rocket equation* describes the total potential velocity of an idealized vehicle propelled by expelling some of its own mass.

      ...

    Markdown
      class prose-invert
      You can use Terrace to write documents, web pages, configuration files, data storage, or whatever else you come up with!

      [This page](https://git.thederf.com/thederf/Terrace/src/branch/main/docs/src/about.tce) is written using Terrace!

Section light
  class flex flex-col md:flex-row gap-16

  Block
    class w-1/3

  Block
    class max-w-prose

    Heading 2 Background

    Markdown
      Terrace was originally envisioned out of frustration at the massive usability gulf for embedding custom blocks in simple, human-friendly markup formats such as [Markdown](), and capable but complex block-based systems such as [Project Gutenberg](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/writing-your-first-block-type/) and [Editor.js](https://editorjs.io/saving-data/).

    Heading 3 The Complexity Problem
      class mt-8 mb-4

    Markdown
      **A simple markdown document:**

    CodeBlock markdown
      # My Page Title

      Occaecat fugiat est ullamco aliqua ea dolor nostrud. Reprehenderit nisi minim sit commodo deserunt ullamco deserunt aute ex exercitation Lorem deserunt ad.

      1. Magna id sint consequat quis esse tempor.
      2. Veniam eu id esse occaecat eu.
      3. Minim commodo nostrud eiusmod excepteur ea sint in enim esse aliqua.

      [Put my-custom-component here somehow]

      Dolor adipisicing amet aliquip nulla occaecat Lorem excepteur veniam. Voluptate pariatur sint anim tempor aliquip in. Id nulla est irure officia occaecat enim.

    Markdown
      **That same document in a *simplified* Editor.js schema:**

    CodeBlock javascript
      class max-h-[500px] overflow-y-auto
      [
        {
          type: "header",
          data: {
            level: 1,
            text: "My Page Title"
          }
        },
        {
          type: "paragraph",
          data: {
            text: "Occaecat fugiat est ullamco aliqua ea dolor nostrud. Reprehenderit nisi minim sit commodo deserunt ullamco deserunt aute ex exercitation Lorem deserunt ad."
          }
        },
        {
          type: "list",
          data: {
            style: "ordered",
            items: [
              "Magna id sint consequat quis esse tempor.",
              "Veniam eu id esse occaecat eu.",
              "Minim commodo nostrud eiusmod excepteur ea sint in enim esse aliqua."
            ]
          }
        },
        {
          type: "my-custom-component",
          data: {
            option1: "value",
            option2: "value",
            text: "Text"
          }
        },
        {
          type: "paragraph",
          data: {
            text: "Dolor adipisicing amet aliquip nulla occaecat Lorem excepteur veniam. Voluptate pariatur sint anim tempor aliquip in. Id nulla est irure officia occaecat enim."
          }
        }
      ]

    Heading 3 MDX & MDC
      class mt-16 mb-4

    Markdown
      Other attempts, such as [MDX](https://mdxjs.com/) and [MDC](https://content.nuxtjs.org/guide/writing/mdc/) have been made to solve this problem, allowing you to incorporate complex content *inside* markup documents.

      However, they suffer from a number of problems:

      1. Tightly coupled to the JavaScript ecosystem
      2. Lock you out of other markup formats, such as [AsciiDoc](https://asciidoc.org/)
      3. Difficult to parse - Markdown was not intended as a general-purpose syntax
      4. Data can't be extracted from markup without rendering the entire document to HTML
      5. Ugly. Just look at this:

    CodeBlock markdown
      # My Page Title

      Occaecat fugiat est ullamco aliqua ea dolor nostrud. Reprehenderit nisi minim sit commodo deserunt ullamco deserunt aute ex exercitation Lorem deserunt ad.

      1. Magna id sint consequat quis esse tempor.
      2. Veniam eu id esse occaecat eu.
      3. Minim commodo nostrud eiusmod excepteur ea sint in enim esse aliqua.

      [MDX Example]
      <MyCustomComponent option1={{'value'}} option2={{'value'}}>
        Text
      </MyCustomComponent>

      [MDC Example]
      ::MyCustomComponent{option1="value", option2="value"}
        Text
      ::


      Dolor adipisicing amet aliquip nulla occaecat Lorem excepteur veniam. Voluptate pariatur sint anim tempor aliquip in. Id nulla est irure officia occaecat enim.

    Heading 3 Terrace Prototype
      class mt-16 mb-4

    Markdown
      I first attempted to solve this problem using an [S-Expression](https://en.wikipedia.org/wiki/S-expression)-based syntax for defining blocks.

    CodeBlock lisp
      (heading
        (level 1)
        My Page Title
      )

      (markdown
        Occaecat fugiat est ullamco aliqua ea dolor nostrud. Reprehenderit nisi minim sit commodo deserunt ullamco deserunt aute ex exercitation Lorem deserunt ad.

        1. Magna id sint consequat quis esse tempor.
        2. Veniam eu id esse occaecat eu.
        3. Minim commodo nostrud eiusmod excepteur ea sint in enim esse aliqua.
      )

      (my-custom-component
        (option1 value)
        (option2 value)
        Text
      )

      (markdown
        Dolor adipisicing amet aliquip nulla occaecat Lorem excepteur veniam. Voluptate pariatur sint anim tempor aliquip in. Id nulla est irure officia occaecat enim.
      )

    Markdown
      While quite flexible and clean-looking, problems became apparent with handling whitespace and escaping parenthesis in text.
      The parser quickly became much more extensive than initially envisioned.

      Nevertheless, it proved the concept that cleanly combining functional blocks and markup text was quite reasonable.

      Not long after, I stumbled upon [Tree Notation](https://treenotation.org) by [Brek Yunits](https://www.breckyunits.com/). Playing around with it, the potential of just *getting rid of the parenthesis* was quite apparent. Simpler syntax for humans to write, and far less work required for parsing & escaping since the only control characters are newlines and spaces:

    CodeBlock terrace
      heading My Page Title
        level 1

      markdown
        Occaecat fugiat est ullamco aliqua ea dolor nostrud. Reprehenderit nisi minim sit commodo deserunt ullamco deserunt aute ex exercitation Lorem deserunt ad.

        1. Magna id sint consequat quis esse tempor.
        2. Veniam eu id esse occaecat eu.
        3. Minim commodo nostrud eiusmod excepteur ea sint in enim esse aliqua.

      my-custom-block
        option1 value
        option2 value
        Text

      markdown
        Dolor adipisicing amet aliquip nulla occaecat Lorem excepteur veniam. Voluptate pariatur sint anim tempor aliquip in. Id nulla est irure officia occaecat enim.

    Markdown
      Ultimately though, using Tree Notation still proved too messy. After working with the grammar system and spreadsheet-style data model for a good while, my gut said all this use case needed was a simple line-based parser.

      I started Terrace to implement a similar syntax, but with the following goals:

      1. Make as few decisions as possible for the user
      2. Be as fast, tiny, and light on resources as possible

      Six or seven parser rewrites later, it finally works mostly how I envisioned it. :)

Section dark
  class flex flex-col md:flex-row gap-16

  Block
    class w-1/3

  Block
    class max-w-prose

    Heading 2 Development Goals

    Markdown
      class prose-invert
      Terrace development is guided by the following goals.

      - **Tiny, primitive core - no “framework”**
        - Use the most boring patterns possible for implementing the core library.
        - Avoid dependencies
        - Easily port Terrace in any language or environment
      - **Avoid dynamic allocation**
        - Since we can work directly off of string slices without the need for ASTs and escaping systems, might as well avoid dynamic allocations altogether!
      - **Minimize assumptions**
        - Let people use Terrace as a building block for all sorts of languages

      Make note of this before submitting change requests. If your changes don't fit these goals, they may be denied. In which case, you could try building a separate library on top of the Terrace cor.

    Footer