z.m.l. overview


 an intro and a refresher


 by bowerbird intelligentleman


 you can "view source" for this document here:

 http://zenmagiclove.com/kicks-444514334.zml




 table of contents


 z.m.l. overview
 table of contents
 what is z.m.l.?
 a blank line is the z.m.l. separator
 sections in your z.m.l. file
 every gourd is composed of chunks
 every gourd must have a header
 italicizing and bolding
 plain ascii versus unicode
 centering a line
 putting a severe indent on a line
 tables in your e-texts
 pictures in your book
 footnotes and endnotes
 external links
 em-dashes
 two spaces after a sentence
 three ways to do blockquotes
 the play is the thing
 epigraphs and epitaphs
 lists in your book
 lists with a regular bullet
 lists with an unfilled bullet
 lists with a second-level list
 lists with a third-level list
 lists with a fourth-level list
 lists with a no-bullet-list
 lists that are numbered (ordered)
 a non-bulleted list as an ordered list
 lists that are custom-numbered
 the meta-data chapter
 the notes section
 meta-data for this book




 what is z.m.l.?


z.m.l. is short for "zen markup language",
a form of "light markup", which is a way
of formatting a document so that it can be
converted into something that "looks pretty"
and also functions correctly as an e-book.

authors use z.m.l. when they are writing,
and then convert the text into .html and
major e-book formats (.epub, .mobi, .pdf).

this document gives an overview to z.m.l.




 a blank line is the z.m.l. separator


use a blank line to separate paragraphs.

well, actually, you use blank lines to
separate _everything_ in a z.m.l. file.

every set of contiguous non-blank lines,
separated from its neighbors by one or
more blank lines, is termed a "chunk".

the "chunk" is the basic unit in z.m.l.,
an entity distinct from its neighbors
by virtue of its blank line separators.

most chunks in a z.m.l. file will be the
workhorse known as a plain old paragraph.




 sections in your z.m.l. file


the sections composing a z.m.l. file --
get separated by 4 or more blank lines.

in a novel, they're typically chapters.

but rather than call them "sections" or
"chapters" or some other common label
-- that will be inaccurate sometimes --
for clarity, z.m.l. terms them "gourds".




 every gourd is composed of chunks


each "gourd" in a z.m.l. file is made up
by "chunks", all separated by blank lines.




 every gourd must have a header


the first chunk in a gourd is its header.

a header already has at least 4 blank lines
above it -- because that is what defines
that section as a gourd -- plus the header
must have exactly 2 blank lines below it.

the header will be defined, in the .html,
as a header, and rendered (by default) as
bigger and bold and centered, exactly as
everyone will expect a header to look like.

in addition, the header will be linked to
the table of contents, where it is listed.

and its appearance in the table of contents
will be automatically linked to the gourd.
z.m.l. does all that for you automatically.




 italicizing and bolding


to do _italics,_ just surround a word with
the _underscore_ character.

to get *bold,* surround the word with
*asterisks.*




 plain ascii versus unicode


just type in your unicode characters.

as long as the font can show them,
everything should be handled fine.




 centering a line


 sometimes you want to center a line.

 to do that, start the line with a space.

 you can also center a series of
 lines, in exactly the same way,
 by starting each of the lines
 with a space in the first column.




 putting a severe indent on a line


         put 6 or more spaces
         at the start of a line
         (or a series of lines)
         if you want to provide
         a severe indent to them.


         if you vary the
            number of spaces
         you can vary the
            size of the indent.




 tables in your e-texts


for a table, start each line with " | ".


 |  table 1           column 1         column 2
 |  plain-text          yes              yes
 |  x.m.l.              no               yes
 |  html                yes              no
 |  .rtf                no               yes
 |  .pdf                no               no




 pictures in your book


to get a picture, enter its u.r.l.

 http://zenmagiclove.com/checking_watch.png




 footnotes and endnotes


for a footnote, put the referent in brackets.[1]

use any word you like for the referent.[anything]

in the text, the bracketed referent of a footnote
is not allowed to be at the beginning of a chunk.

in contrast, the footnote itself _must_ be at the
beginning of a chunk, meaning it has a blank line 
above it, with its left-bracket in the first column.

most of the time, you will want to put all of
the footnotes in a dedicated "endnote" gourd,
located at the back of the book after the text.

but you are allowed to put a footnote anywhere,
as long as it has that blank line above it.




 external links


to link to an external site, just type the u.r.l.

 http://www.google.com

z.m.l. wants the reader to know the destination
to which you are linking, so it uses the bare u.r.l.
it doesn't allow you to "hide" the u.r.l. behind
some non-informative text, in the usual web way.

however, you can put a link in a footnote.[google]

if you are used to markdown's link format,[ugly]
you'll find that z.m.l. can handle it just fine.

it can even handle two or more words[two-words].
just join the words with a dash[two-or-more-words].




 em-dashes


double-dash -- two typewriter dashes in a row --
is converted to an em-dash by the z.m.l. conversion.




 two spaces after a sentence


it's easier to edit your document if you don't use
two spaces after a sentence, because you can do
a search for two spaces and find any places where
you accidently have two spaces between words
where you didn't really intend to have them.




 three ways to do blockquotes


use " > " as the command to create a blockquote.

 > four score and seven years ago, our
 > forefathers set forth upon this continent
 > a new nation, conceived in liberty and
 > dedicated to the proposition that
 > all men[2] are created equal.

use " : " as another command for a blockquote;
the difference is that linebreaks are not honored.

 : four score and seven years ago, our
 : forefathers set forth upon this continent
 : a new nation, conceived in liberty and
 : dedicated to the proposition that
 : all men[3] are created equal.

and, of course, you can use the 6-or-more-spaces
indenting rule to format another type of blockquote:

            four score and seven years ago, our
            forefathers set forth upon this continent
            a new nation, conceived in liberty and
            dedicated to the proposition that
            all men[4] are created equal.

or you can do a similar thing with the ~tab~ character:

 ~tab~dear leslie,
 ~tab~
 ~tab~how are you? i am fine.
 ~tab~the weather is nice here.
 ~tab~but i wish it was half
 ~tab~as beautiful as you are.
 ~tab~
 ~tab~and i wish you were here.
 ~tab~
 ~tab~love,
 ~tab~bowerbird




 the play is the thing


if the first word in a line is followed by a colon,
which is in turn followed by a "~tab~", the word
will be rendered in bold.

hamlet:~tab~ to be or not to be, that is...

shakespeare:~tab~ bug off, you ham...




 epigraphs and epitaphs


 ~tab~~tab~~tab~ _there's_ _an_ _old_ _proverb_ ~tab~
 ~tab~~tab~~tab~ _that_ _says_ _just_ _about_ ~tab~
 ~tab~~tab~~tab~ _whatever_ _you_ _want_ _it_ _to..._ ~tab~
 ~tab~~tab~~tab~ _--_ _slashdot_ ~tab~

sometimes a chapter starts with a nice pithy quote,
which is usually _italicized,_ and often right-justified.

three tabs at the beginning of the line, and one at the end,
will give you this kind of right-justified format.[5]




 lists in your book


light-markup makes it easy to do lists.

and z.m.l. gives you lots of ways to make a list,
depending on what kind of bullet you want to have.




 lists with a regular bullet


the " * " command will give you the "regular" bullet.

 * one
 * two
 * three
 * four
 * five
 * six
 * seven
 * i forget what 8 was for.
 * number 9, number 9...




 lists with an unfilled bullet


the " o " command will give you the "regular" bullet.

 o mercury
 o venus
 o earth
 o mars
 o jupiter
 o saturn
 o uranus
 o neptune
 o pluto




 lists with a second-level list


the " + " command will give you the "regular" bullet,
in a list which is indented to the second level.

 + mercury
 + venus
 + earth
 + mars
 + jupiter
 + saturn
 + uranus
 + neptune
 + pluto




 lists with a third-level list


the " - " command will give you the "open" bullet,
in a list which is indented to the third level.

 - mercury
 - venus
 - earth
 - mars
 - jupiter
 - saturn
 - uranus
 - neptune
 - pluto




 lists with a fourth-level list


the " = " command will give you the "square" bullet,
in a list which is indented to the fourth level.

 = mercury
 = venus
 = earth
 = mars
 = jupiter
 = saturn
 = uranus
 = neptune
 = pluto




 lists with a no-bullet-list


the " x " command gives a list without bullets.

 x mercury
 x venus
 x earth
 x mars
 x jupiter
 x saturn
 x uranus
 x neptune
 x pluto




 lists that are numbered (ordered)


the " # " command creates an ordered list,
that is, one that is automatically numbered.

 # one
 # two
 # three
 # four
 # five
 # six
 # seven
 # i still forget what 8 was for.
 # number 9, number 9...




 a non-bulleted list as an ordered list


you can use the non-bulleted list to create a
"numbered list" where you control the numbers.

 x 1. one
 x 2. two
 x 3. three
 x 4. four
 x 5. five
 x 6. six
 x 7. seven
 x 8. i still forget what 8 was for.
 x 9. number 9, number 9...




 lists that are custom-numbered


this means you can create a list that has
custom numbers (e.g., non-consecutive).

 x 101. one
 x 202. two
 x 333. three
 x 4444. four
 x 55555. five
 x 6. six
 x 77. seven
 x 88. i still forget what 8 was for.
 x 9. number 9, number 9...




 the meta-data chapter


a lot of people think "meta-data"
is important. i think they're full
of poop, but why not make 'em happy?

so give them their own section --
call it the "meta-data section"
-- and then let them put whatever
makes 'em happy into that section.

you will find the meta-data section
toward the very end of this document,
where it belongs, after the "real" data.




 the notes section


[1] personally, i don't think we need to
make a distinction between footnotes
and endnotes any more, i believe that
all the types of notes should be stored
at the end of the file, like these notes,
but i think the person should be able to
_display_ them at the point of reference
in the actual body of the text. therefore,
they are actually a sort of hybrid between
footnotes _and_ endnotes, combining the
strengths and convenience of both types.

[anything] it can be anything.

[google] http://www.google.com

[ugly](http://daringfireball.com/markdown/basics)

[two-words] join the words with a dash.

[two-or-more-words] join 'em with a dash.

[2] in later years, it was made clear that
lincoln was referring to all "people", and
not just men, that women are equally equal.

[3] this is a test footnote. because of that,
it's going to go on and on and on.
this is a test footnote. because of that,
it's going to go on and on and on.
this is a test footnote. because of that,
it's going to go on and on and on.
this is a test footnote. because of that,
it's going to go on and on and on.
this is a test footnote. because of that,
it's going to go on and on and on.

look, it even has a second paragraph!
this is a test footnote. because of that,
it's going to go on and on and on.
this is a test footnote. because of that,
it's going to go on and on and on.
this is a test footnote. because of that,
it's going to go on and on and on.

oh no! a third paragraph. way too long!
this is a test footnote. because of that,
it's going to go on and on and on.
this is a test footnote. because of that,
it's going to go on and on and on.
this is a test footnote. because of that,
it's going to go on and on and on.
this is a test footnote. because of that,
it's going to go on and on and on.
this is a test footnote. because of that,
it's going to go on and on and on.

[4] this is another test footnote. but it will be short.

[5] this is another short test footnote.




 meta-data for this book


here's the meta-data...

 o title =  z.m.l. overview -- an intro and a refresher
 o author = bowerbird intelligentleman
 o purpose = a simple review of the z.m.l. basics
 o markup = zen markup language (.zml)
 o isbn = urn:isbn:0000000000000
 o publisher = jaguar(ps)
 o subject = z.m.l. introduction and refresher
 o rights = copyright 2013 -- all rights reserved

 http://gutenberg.org

 here's a test of some of the formatting commands.

 ~tab~left-justified~tab~~tab~~tab~

 ~tab~~tab~centered~tab~~tab~

 ~tab~~tab~~tab~right-justified~tab~

 ~tab~this just has one tab...

 http://google.com

 http://pgdp.net

 http://gutenberg.org

 http://zenmagiclove.com/checking_watch.png

 http://zenmagiclove.com/cat_fades.png

 http://zenmagiclove.com/alice_cramped.png

 http://zenmagiclove.com/alice_holding.png


 * 
 * one two buckle my shoe and my boots and my snowshoes and my snowboots and my wonderful wonderful wonderful wonderful snowmobil and snowfall and puddle and rainfall and rainforest

 * three

 * four

 * five

 * six

 * seven