markup.org

Goals/Motivations

Every markup language sucks

• HTML is unambiguous but painful to type
• Markdown syntax is bad (links are backwards)
• Others supported on github don’t suit our needs

In general markups have one or more of four problems:

• Missing features [1]
• Bad syntax [2]
• Bad implementations [3]
• Evil [4]

Markup	1	2	3	4
HTML		X	.
Markdown		x
OrgMode			x
LaTeX		X	.
BBCode		X	.
AsciiDoc	x	x
MediaWiki		x		X
Anything Else	X	x	?

(Note that “Bad syntax” is contextual when considering TeX)

Even if they didn’t suck

• Native SmileBASIC highlighting/support doesn’t exist
• Sanitizing properly is scary
• Don’t always work nicely (the best option is to call Emacs to render org… really?)

Goals / Features

• Actually works – no ambiguous cases, quotes breaking verbatim, broken features
• Domain-specific is okay! It’s better if no one else tries to use this (ew maintaining projects)
• Content generation [macros] – syntax lists from full notation, filesystem queries
• Nested tables
  • Possibly through an environment/scope syntax
• Citations (simple)
• Doesn’t convert char sequences like an idiot (smart quotes, emdash, bad ellipsis–all useless)
• Don’t be different just to be different
• Doesn’t eat line breaks
• Ignore line breaks after the start and end tags of block structures

Syntax

Headings

Must be at the start of a line

*** heading

Links

[[url][text]]

Escape sequence

\<symbol> inserts <symbol> directly without parsing

Basic Formatting

All of these are matched on word boundaries (maybe not literal word boundary though?) [A-Z_a-z0-9] shouldn’t match
SHOULD match against [,!?.:;(){}[] ]

Bold

*bold text*

Underline

_underline_

Inline code

grave marks

`code`

Strikethrough

no
tag?

Code

``` [language]
code block
```

Comments

Must be at the start of a line

# comment text

Options

#+OPTION value

Defining a macro

#+MACRO name value
#+MACRO #BEGIN_SRC ```

Environments

{ pushes current environment and begins a new environment (reset? or inherits?)
} pops environment

blah blah blah now to do something stupid:
{
#+MACRO a the fitnessgram pacer test is a multistage aerobic capacity test
hahaha
}
please don't hurt my text aaaa

Tables (revised)

(pipe has to be in first non-whitespace column… of environment?)

|=== start table |\s*| end row |\s*|===| end table | next cell |--- table has header

|========================|
| header |      header 2 |
|------------------------|
| row 1  |      aaaaa    |
| row 2  |      bbbbbbbb |
| vvvvv  
  ^^^^^  | multiline
           cell contents |
|========================|

|========================|
| header |      header 2 |
| row 1  |      aaaaa    |
| row 2  |      bbbbbbbb |
| vvvvv  
  ^^^^^  | multiline
           cell contents |
| |===||inner table||===|  |   wow    |
|========================|

output:

<table class="table-with-header">
<tr><td>header 1</td><td>header 2</td></tr>
<tr><td>row 1</td><td>aaaaa</td></tr>
<tr><td>row 2</td><td>bbbbbbbbM</td></tr>
<tr><td>vvvvv<br>^^^^^</td><td>multiline<br>cell contents</td></tr>
<tr>
<td><table><tr><td>inner table</td></tr></table></td>
<td>wow</td>
</tr>
</table>

header 1	header 2
row 1	aaaaa
row 2	bbbbbbbbM
vvvvv ^^^^^	multiline cell contents
inner table	wow