beyond markdown

— part 6

notes on a few types of “special” paragraphs

this series is discussing “zen markup language”
— z.m.l. — a light-markup akin to markdown,
but one that fully intends to sidestep some of
the problems that are starting to dog markdown,
like imprecisely-defined ambiguous corner-cases,
and an ever-increasing number of implementations
that offer inconsistencies across their conversions.

several major aspects of the z.m.l. documentation
have already been described, so we will now close
some of the gaps that we left earlier along the way.

for instance, we talked about “chunks” in “part 3".

a “chunk” is each set of contiguous non-blank lines
bordered by blank lines in your file, and chunks are
further broken down into “paragraphs” and “blocks”.

a chunk which you start with a space in column 1
is a “block”, meaning it requires special formatting.
these are elements like blockquotes, lists, and tables.

we discussed all the various “block” tags in “part 4".

a chunk which does not have a space in column 1
is a “paragraph”, meaning that it can be formatted
in a standard manner. in print-books, for instance,
a plain old paragraph is indented and full-justified,
and there is no extra space in-between paragraphs.

now, when we discussed “paragraphs”, we said that
— besides the familiar “plain old paragraphs” that
we all know and love — there are some “specialized”
types of “paragraph” chunks. so let’s detail them now.

***

one type of “paragraph” that sometimes get special
treatment is the first underneath a header in a book:
it will typically be left-justified rather than indented.

for example:

http://zenmagiclove.com/simple/zml-pfp-noindent-1.png

or this:

http://zenmagiclove.com/simple/zml-pfp-noindent-2.png

this is a print-oriented convention that we might not
wanna bring into the new electronic-document world
— i haven’t really made up my mind on that issue —
but for the time being we’ll consider these paragraphs
to be in a class by themselves. there isn’t anything you
have to do, because the converter-routine keeps track
of these paragraphs, but i wanted to tell you about ‘em
because they are being recognized as “a special case”.

***

next up is footnotes.

footnotes have two parts. the first part is the location
in the body of the text, which “calls up” the footnote.
in z.m.l., you “call” a footnote by creating a “referent”
in brackets. for instance, you call footnote 1 like this.[1]
this body-text part is _not_ what we’re discussing here.

the second part is the text that makes up the footnote
itself. and that’s the part that we’re talking about here.

in a printed-book, with pages, a footnote goes at the
“foot” of the page, but in today’s e-document world,
we often don’t have a “page” in the traditional sense,
so footnotes are generally collected toward the back,
in a section of their own. so let’s assume you do that.
(you can actually put a z.m.l. footnote anywhere, but
for the time being, say you put them all in one section.)

each footnote must start as a chunk, below a blank line.
and further, it must start with a left-bracket — “[“ —.
so the converter can recognize a footnote quite easily.

here’s a sample of the text-input for a footnote section.
as you see, we have 6 different footnotes in this section.

http://zenmagiclove.com/simple/zml-input-endnotes.png

footnotes are given an “outdent” rather than an indent,
so here’s the output for the sample footnotes above:

http://zenmagiclove.com/simple/zml-output-endnotes.png

links will be automatically generated from the referents
to the end-notes, and from the end-notes back to the body.

and there’s nothing special you have to worry about here.
just treat your footnote normally, and z.m.l. will handle it.

***

as you can see in the second footnote illustrated above,
a footnote can go on for more than one paragraph, and
the following paragraph doesn’t have to start with a “[“,
z.m.l. will treat this kind of “plain old paragraph” that’s
_after_ a footnote as a _continuation_ of that footnote.

and, as you can also see in the output graphic above,
a footnote-continuation is another type of paragraph
that gets special formatting. specifically, it continues
the indented left-margin that the footnote started,
which makes sense as it is the second (or subsequent)
paragraph of the footnote. and again, the converter can
figure this out by itself; you don’t have to do anything.

plus, as you can also see in the second footnote, there
might well be more than one footnote-continuations.

for a paragraph, right after a footnote or a continuation,
which is _not_ a continuation of that footnote, you must
indicate it with _two_ blank lines above it, not just one.
you can see this situation first in the input-text graphic,
and then, the effects of the 2 blank lines, in the output.

***

our next special paragraph is one you will often see in
a script of a play; it begins with the character’s name;
and the name is rendered in bold. another place where
you’ll see this is in the transcription of an _interview;_
the name of the interviewer and/or the interviewee is
rendered in bold. now, the common aspect of paragraphs
like these is that the bolded name is followed by a colon.
so that’s how the converter recognizes these paragraphs.
any paragraph that starts with a word which has a colon
at the end will have that word (and colon) shown in bold.

interview sample input:

http://zenmagiclove.com/simple/zml-input-interview.png

interview sample output, where the “q:” and “a:” are bold:

http://zenmagiclove.com/simple/zml-output-interview.png

***

finally, we have “numbered paragraphs”. these are paragraphs that
start in column 1 with a number which is followed by period-space.

these paragraphs are akin to a numbered-list (or, as .html calls it,
an ordered-list), but they are full-on paragraphs, ones you want to
have formatted like paragraphs, not formatted as an indented “list”.

for example:

http://zenmagiclove.com/simple/zml-numbered-paragraphs.png

***

those are the “special” types of paragraphs. other than knowing how
they are recognized, so you can “trigger” them whenever you want,
there’s no other action required to obtain the formatting you need.

***

that’s all for today!

***

here are the articles in this series:

beyond markdown — part 1 — it’s time for the next step https://medium.com/@bbirdiman/beyond-markdown-part-1-2300665659f7

beyond markdown — part 2 — z.m.l. was built to be easy to understand https://medium.com/@bbirdiman/beyond-markdown-part-2-b3527d2b9dcf

beyond markdown — part 3 — two types of chunks — paragraphs and blocks https://medium.com/@bbirdiman/beyond-markdown-part-3-eed9bebea0da

beyond markdown — part 4 — how to “tag” a block for formatting https://medium.com/@bbirdiman/beyond-markdown-part-4-9b4dc6841d7e

beyond markdown — part 5 — shining a spotlight on sections and headers
https://medium.com/@bbirdiman/beyond-markdown-part-5-4902097723b0

beyond markdown — part 6 — notes on a few types of “special” paragraphs
https://medium.com/@bbirdiman/beyond-markdown-part-6-8056eee5b783

beyond markdown — part 7 — text styling and typographic niceties
https://medium.com/@bbirdiman/beyond-markdown-part-7-3158e23f22bf

beyond markdown — part 8 — alignment, horizontal rules, and breaks
https://medium.com/@bbirdiman/beyond-markdown-part-8-1a082d7f1f6d

beyond markdown — part 9 — pulling outside resources into your document
https://medium.com/@bbirdiman/beyond-markdown-part-9-be74bbbed369

beyond markdown — part 10 — special sections in your document
https://medium.com/@bbirdiman/beyond-markdown-part-10-3ca0c08e5641

***

and, for reference, as an extra bonus:

markdown considered harmful — or perhaps a loved but irritating old uncle
https://medium.com/@bbirdiman/markdown-considered-harmful-495ccfe24a52