init

example.mharkup

@@ -0,0 +1,255 @@
+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
+` #\ 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)
+` 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: `*_+(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 @21st century
+i've solved many problems
+that noone's ever had.
+
+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: `\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)].