Markdown formal grammar template: rules and a derivation

A Markdown formal grammar template describes which strings belong to one small invented language. Its alphabet names the literal symbols. Its productions state how rule names expand, beginning with a designated start symbol. A sample derivation follows those written choices until only literal symbols remain.

Here the language consists of made-up shelf labels. Everything governing those labels appears in the example itself. These letters and digits carry no significance outside the fictional labels.

What the grammar file holds

The title gives the language a name, and a plain sentence says what it describes. Beneath that sentence, the alphabet fixes the available literal symbols. The start symbol identifies the rule name from which a whole string begins. Each named production then gives the replacements for one rule name, including its alternatives.

The derivation belongs beside those productions because it shows their effect on a particular string. It begins with the start symbol alone. Each following line expands one remaining rule name using an alternative stated above it. The last line contains the finished shelf label.

Keep this writing in an .md file; the explanation of .md files explains the extension. The grammar's subject stays the invented language and its strings.

The formal grammar template and shelf-label example

For this fictional setting, writer Jane Doe creates shelf labels within a project called Doe. She defines their language through the alphabet, start symbol and rules in the example. The sample derivation shows how those rules produce one label.

Only the title awaits its own wording. Beneath it, the filled parts give the language description, alphabet, start symbol, productions and derivation. For another toy language, replace those parts together, including the sample string.

# [invented language title]

Jane Doe's language describes invented shelf labels for the Doe project.

## Alphabet

The literal symbols are "q", "v", "2" and "7".

## Start symbol

<Label>

## Named productions

<Label> becomes <Stem> followed by <Digit>.
<Stem> becomes "q" or "v" followed by <Stem>.
<Digit> becomes "2" or "7".

## Sample derivation

<Label>
=> <Stem><Digit>
=> v<Stem><Digit>
=> vq<Digit>
=> vq7

The alphabet lists the available literal symbols, and the start symbol identifies where expansion begins. The productions define the choices at each step. A rule that refers back to itself allows repetition; its other choice ends that repetition.

The displayed derivation follows the stated rules through each expansion. It uses the self-referencing choice once, then ends the repetition and completes the label. Each step shows how a rule name gives way to its chosen replacement until only literal symbols remain.

The outer block is tagged text. Markdown code blocks describes how to enclose the example with fence punctuation. Inside it, the heading lines and grammar description remain the example's written text.

Keeping literal symbols and rule names visibly apart

Quote literal symbols in the productions and enclose rule names in angle brackets. Thus "q" supplies a character, while the name Stem still calls for expansion. The quotation characters and angle brackets aren't members of the example's alphabet. Neither are the arrows that separate the displayed derivation lines.

The derivation leaves literals unquoted so the growing string stays visible. Adjacent pieces touch without an added space: vq followed by the remaining Digit becomes vq7 when that alternative is chosen. Spaces used in the prose of a production separate words; they add no characters to a label. Keep this distinction beside the example when changing its alphabet or rule names.

Naming the grammar file

For Jane Doe's invented labels, doe-shelf-label-grammar.md joins the shelf-label subject to its grammar description. A different invented language deserves a name tied to its own strings. Markdown file naming discusses word separators and the file ending.

The title, language sentence and file name should describe the same set of strings. If the labels change to use different letters or a different ending, the alphabet, productions and sample derivation need to describe that same revised language.

Where Sashmark fits

Sashmark, in development, plans desktop reading alongside editing, with agent-written Markdown as its focus.