mharkup example

an example document which explains and documents the features of mharkup.

motivation

mharkup is a weird markup language to get around things that annoy me in most markdown flavors.

goals

as someone using mharkup, you

can read and write it in your text editor
can export and print[printable]

why does it need to be printable?

i don't expect to ever print out one of these documents, but i want them to be exportable to a static format, one where the user can read every piece of information in the document without having to interact with their device. this requirement just happens to line up with printability :)

it
can easily (re)organize your document
probably won't apply formatting on accident [backtick]

why is text formatting so inconvenient?

i really don't want to think about how many special characters i can't use while writing my plaintext documents. i know that writing `*(word) instead of **word** is inconvenient, but using *, _, and even \ without any escaping may (?) already be worth it.

Also, * and _ can't be nested, so if you took this **cool** section and copy-pasted it into an already bold section, you would get **this **cool** section** which is just... ew. Meanwhile `*(this `*(cool) section) works just fine and produces this cool section.

the format

documents

documents are split into sections. the first section is always the document's title. sections are separated by an empty line.

for example, here are the sections you just read:

mharkup

## documents

documents are split into sections.
the first section is always the document's title.
sections are separated by an empty line.

for example, here are the sections you just read:

#!mharkup
## documents
...

each mharkup file starts with a title, the first line of the file, which doesn't have any leading hashtags. a file should also have a small description of what it will contain, and the file's actual content should be in subdocuments. for example, here's how this file starts:

mharkup

mharkup example

an example document which
explains and documents the
features of mharkup.

# motivation
...

sections

in most cases, a section is just a few lines of text. you've probably already noticed that linebreaks are usually ignored or, more accurately, replaced with spaces.

sections beginning with a hashtag (#) are special. the first line specifies the type of section you want, and the other lines are the section's content. you've already seen this with #!mharkup in the first example.

the types of sections you can create like this are:

#@ quotes
#! code blocks
#\ various extensions

backtickshere

in a section, you can use the backtick (`) to apply text formatting, or you can start a section with a backtick followed by a space to create a list. here's a list of things the backtick can do:

create a list
represent itself `: ``
add a note: `-(note)
mark something that's ~~wrong~~: `~(wrong)
highlight a special element: `_(special)
add emphasis to something: `+(something)
highlight something important: `*(important)
insert raw `text`: `{`text`}: `<`{`text`}>: `2{`<`{`text`}>}}: ...
link
somewhere[here]
backticks

in a section, you can use the backtick (`) to apply text formatting, or you can start a section with a backtick followed by a space to create a list. here's a list of things the backtick can do:
create a list
represent itself `: ``
add a note: `-(note)
mark something that's ~~wrong~~: `~(wrong)
highlight a special element: `_(special)
add emphasis to something: `+(something)
highlight something important: `*(important)
insert raw `text`: `{`text`}: `<`{`text`}>: `2{`<`{`text`}>}}: ...
link somewhere[here]: `/here(somewhere)
use an extension: `\spec{...} or `\spec<...>
combine any of these: whoah: `*_+(whoah)
: `/here(somewhere)
use an extension: `\spec{...} or `\spec<...>
combine any of these: whoah: `*_+(whoah)

you can also insert a subdocument by inserting a new title section. for example, the backticks subdocument starts with the following section:

mharkup

### backticks /here

and these sections are back in the outer document, at depth 2 instead of 3, because of an empty title section:

mharkup

##

since sections are separated by an empty line, they don't usually contain empty lines themselves. however, they absolutely can, and for code blocks, you will definitely need it quite quickly.

in normal text, where newlines are usually removed, an empty line can be used to force a linebreak.

to add an empty line to a section, enclose it in at least one set of square brackets. for the following example, to be able to include the double brackets, the #!mharkup section is enclosed in 3 more sets of square brackets.

mharkup

[[
#@mark
and that's all,

i think...
]]

mark

and that's all, i think...

the following subdocuments just show how to use the different section types in more detail.

quotes

mark

i've solved many problems that noone's ever had.

21st century

in this case, the first line of the section was #@mark @21st century.

code

python

def do_something_productive():
    pass

in this case, the first line of the section was #!python.

extensions

mharkup

#\texm
\sum_{a=0}^{20} a^2

texm

\sum_{a = 0}^{20} a^{2}

mharkup

or inline: `\texm<a^2> `2\texm{ \frac{1}{2} }}

or inline:

a^{2}

\frac{1}{2}

mharkup

#\html
<marquee scrollamount="1">deprecated, but funny</marquee>

html

deprecated, but funny

reasoning

why is text formatting so inconvenient?backtick

i really don't want to think about how many special characters i can't use while writing my plaintext documents. i know that writing `*(word) instead of **word** is inconvenient, but using *, _, and even \ without any escaping may (?) already be worth it.

Also, * and _ can't be nested, so if you took this **cool** section and copy-pasted it into an already bold section, you would get **this **cool** section** which is just... ew. Meanwhile `*(this `*(cool) section) works just fine and produces this cool section.

why does it need to be printable?printable

i don't expect to ever print out one of these documents, but i want them to be exportable to a static format, one where the user can read every piece of information in the document without having to interact with their device. this requirement just happens to line up with printability :)

why don't the titles get smaller?titlesize

so that you can have as many layers of document as you want without asking yourself "is that just text in a <p> or is it a really small <h7> heading?", and so that you can move subdocuments between layers without having to think about it.

to illustrate this, see how <p> and <h7> look in your browser:

html

this is a paragraph

followed by a h7, the smallest heading

crazy, right? and i actually lied. the "paragraph" is a <h7> and the "h7" is a <p> element :) and here's 10 layers of documents in mharkup:

whoah, that's a lot

but it's still perfectly readable

why are there no nested lists?listnesting

the real answer is, implementing it was hard and it didn't feel natural with the rest of the syntax.

another answer is, if you have enough content to require nested lists, you should just use subdocuments.

this will also force you to have good titles for each element. it's sometimes unclear if you should use nested lists or headings in a markdown document, and my own .md notes are inconsistent in this way. and when i did use a nested list, some elements were like titles for the inner list, and others had their own content and then still contained another list. it's an inconsistent mess, so not having it in mharkup isn't too upsetting for me (yet..., i'm a big fan of lists in .md).