— part 10
special sections in your document
***
this is part 10 in a series describing “z.m.l.” —
zen markup language — a light-markup format.
links to all of the parts are given at the bottom.
***
today we discuss special sections in your document.
as we said early on, z.m.l. considers the _sections_
of your document as a primary organizing principle.
for instance, your document might have footnotes,
in which case you’ll most likely want to collect the
footnotes in a section in the back of the document.
z.m.l. automatically creates internal links between
the referent in the body-text calling a footnote and
the matching referent in the footnotes themselves,
so a reader can quickly jump from one to the other,
so it’s ok the notes are separted in their own section.
i’ve discussed the rules for the footnotes themselves,
but i haven’t yet discussed the rules for the referents.
so let’s do that now, before we discuss other sections.
***
footnotes
let’s look at how we do footnotes in z.m.l.
because we need to be able to do footnotes.[1]
square-brackets are the key marker for footnotes;
these brackets are used to set off the “referent”.
the “referent” is the pointer serving to connect
the body-text location to its footnote at the end.
in the body, place brackets around the referent,
which must be placed at the end of a word.[2]
the referent must have whitespace to its right[3]
— that is, either an actual space or a linebreak —
and the referent must have no whitespace to its left.
the referent cannot have whitespace or punctuation.
you can use a number[4] as your footnote referent,
which is a very common practice in printed-books.
but you can also use letters[five] if you want to.
it can even be a mixture of letters and numbers.[six6]
remember, neither spaces nor punctuation is allowed.
the text above shows how you’d place 6 footnotes.
***
now, toward the end of your document, you’d have
a section where those footnotes would be collected.
input-wise, the footnotes themselves might look like:
[1] the footnotes are collected at the end.[2] this is the second footnote. you will notice
that when you click this link it takes you back
_not_ to the line that contains the referent, but
rather to the _beginning_ of the paragraph that
contains it, because that helps give you context.this paragraph is a continuation of the footnote
because of that, you’ll notice that it has retained
the indentation.this paragraph is another continuation.if you want to return to the margin, just place
_2_ blank lines above a paragraph, like this one.[3] this is the third footnote.[4] this is the fourth footnote.[five] this is the fifth. it shows an example
of a word being used as a footnote-referent.[six6] this is an example of a footnote-referent
that is a combination of letters and numbers.
http://zenmagiclove.com/simple/zml-input-endnotes.png
***
remember up above, when we were talking about the
referents in the body-text, how we said that they must
_not_ have any whitespace to their left, none at all?
well, as you will note, these footnotes themselves all
have referents that _do_ have whitespace to their left.
indeed, their referent is located at the start of a chunk!
this is how z.m.l. knows the difference between the
body-text pointer-referents and the actual footnotes.
and, of course, the referents themselves determine
how they go together — matching referents match up!
this means you can still use brackets in your document;
as long as the contents inside a pair of brackets doesn’t
match an existing footnote, z.m.l. treats the brackets as-is.
for the matching referents, though, mutual two-way links
are set up, so the reader can easily toggle between them.
that means that you can go to the footnotes section and
read through them and also jump to the points inside the
body-text where each footnote was called. it’s very handy.
***
there is one exception to this “matching rule”, however,
for what i call “super-footnotes”, where a footnote has
a specific referent that is not matched by one in the text.
in this case, z.m.l. takes the word making up the referent
and searches for it in the document; whenever it finds it,
it creates a link from that point in the text to the footnote.
so, for instance, if you were to have this as a super-footnote:
[apple] http://www.apple.comthen every time the word “apple” appeared in your text,
a link will be created to that footnote, which in this case,
since the substance of the footnote is a u.r.l., a secondary
link will be made so the reader could jump to apple.com.
notice that a backlink is not possible with a super-footnote,
because we don’t know which of several places to backlink.
(but the software’s “back” button can serve that purpose.)
one option, though, would be to link to the location of the
first super-footnote referent, presumably its introduction.
***
i will also consider a “local-footnote” functionality as well,
one that immediately follows a paragraph, acting just like a
“super-footnote”, but _only_ regarding that one paragraph.
in this case, the footnote will be hidden unless it is “called”.
as with many options, adoption of this “local-footnote” will
depend on whether the zen markup community approves it.
***
special sections in your document
here are some of the special sections you might have in
your document. you are invited to think about some of
the unique aspects of each of these sections which z.m.l.
might want to consider when processing or presenting it.
if you choose to start using z.m.l., and become a part of
the community around it, your thoughts will be solicited.
cover/title section
table of contents
abstract
list of illustrations
list of tables
list of figures
dedication
preface
forward
introduction
———
summary
conclusion
glossary
footnotes
index
references
colophon
about the author
about the editor
for more by this author
metadata
***
more on the colophon section
finally, there is one section, from above, that
we can tell you something about: the colophon.
in times past, the colophon was a quaint section
that typically gave details about the fonts used,
perhaps their history, or specifics in that book.
“the text in the body of this book was set
in 12-point bodoni with 15-point leading.”
now, the early-21st-century equivalent of that
will be considered the stylesheet, so if a u.r.l.
ending with .css is included in the colophon,
the document will default to that stylesheet.
so this, in the colophon:
http://zenmagiclove.com/simple/stylesheet99.csswill cause that stylesheet to be loaded and used.
that’s an easter-egg for techies who read patiently,
while all the time longing for some greater control.
and with that. we close up.
***
that’s all for today! and that’s all for the z.m.l. “manual”.
yay!, you’ve finished the classes and practically graduated!
the next part is the last part, the conclusion of this series
— “congratulations on your commencement”. next week!
p.s. one of your graduation prizes will be an authoring-tool,
so you can start experimenting with zen markup language…
***
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
