mharkup/example.mharkup

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 `/printable[print] it
` can easily (re)organize your document
` probably won't apply formatting on accident `/backtick[]

# 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
` `![#:] resource links
` `![#\] various extensions

### backticks /here

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]}
` include some `![code.f()]: `!{`![code.f()]}
` mark a non-word or name, like `@[mharkup]: ``@[mharkup]
` highlight a `_[special] element: `!{`_[special]}
` add emphasis to `+[something]: `!{`+[something]}
` highlight something `*[important]: `!{`*[important]}
` insert raw `{`text`}: `!<`{`text`}>: `2!{`<`{`text`}>}}: `2!<`2{`<`{`text`}>}}>>: ...
` link `/here[somewhere]: ``/here[somewhere]
` use an extension: ``\spec{...} or ``\spec<...>
` combine any of these: `*_+[whoa`~(h)]: ``*_+[whoa``~(h)]

##

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 @21st century `/ref[]
i've solved many problems
that noone's ever had.

in this case, the first line
of the section was `!{#@mark @21st century `/ref[]}.

### code blocks

#!python
def do_something_productive():
    pass

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

### resource links /ref

#:other_doc
A document you should read.

#https://example.com/hello
Something external.

The first lines of these sections were `!{#:other_doc} and `!{#https://example.com/hello}.
If the section starts with `!{#:}, the link is relative.

### 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: `\texm<a^2> or `2\texm{ \frac{1}{2} }}

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

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

# 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
<h7>this is a paragraph</h7>
<p>followed by a h7, the smallest heading</p>

[
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)].