z.m.l. overview

an intro and a refresher

by bowerbird intelligentleman

you can "view source" for this document here:

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
the " * " command for a regular bullet
the " o " command for an unfilled bullet
the " + " command for a second-level list
the " - " command for a third-level list
the " = " command for a fourth-level list
the " x " command for a no-bullet-list
the " # " command for a no-bullet-list
the meta-data chapter
a demo for zen markup language
the end of this test-suite
the notes section
meta-data for this book

<- -c- ->

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 (.pdf, .mobi, .epub).

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

<- -c- ->

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.

<- -c- ->

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".

<- -c- ->

every gourd is composed of chunks

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

<- -c- ->

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.

<- -c- ->

italicizing and bolding

here's how you do italics.

here's how you do *bold.*

<- -c- ->

plain ascii versus unicode

just type in your unicode characters.

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

<- -c- ->

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.

<- -c- ->

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.

<- -c- ->

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

<- -c- ->

pictures in your book

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

http://z-m-l.com/go/alice/checking_watch.png

<- -c- ->

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 and its bracket in the very 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).

<- -c- ->

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.

<- -c- ->

em-dashes

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

<- -c- ->

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.

<- -c- ->

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 will be 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:

<- -c- ->

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...

<- -c- ->

epigraphs and epitaphs

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]

<- -c- ->

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.

<- -c- ->

the " * " command for 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...

<- -c- ->

the " o " command for an unfilled bullet

mercury
venus
earth
mars
jupiter
saturn
uranus
neptune
pluto

<- -c- ->

the " + " command for a second-level list

mercury
venus
earth
mars
jupiter
saturn
uranus
neptune
pluto

<- -c- ->

the " - " command for a third-level list

mercury
venus
earth
mars
jupiter
saturn
uranus
neptune
pluto

<- -c- ->

the " = " command for a fourth-level list

mercury
venus
earth
mars
jupiter
saturn
uranus
neptune
pluto

<- -c- ->

the " x " command for a no-bullet-list

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

here's another numbered list, again with the number specifically included, where we mix things up a bit...

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

<- -c- ->

the " # " command for a numbered list

here's another numbered list, except this time it's an "ordered list", which means the browser does the numbering...

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

<- -c- ->

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.

<- -c- ->

a demo for zen markup language

this test-suite document is a demonstration of z.m.l. -- "zen markup language" -- a system by which a set of simple formatting rules can take the place of complicated markup languages.

this document is "marked up" in z.m.l. and will spring to life when displayed by a z.m.l.-viewer.

furthermore, a z.m.l.-viewer can perform all of the tasks necessary to implement the features that this test-suite represents: the hot-linking, the styling, different layouts, tables, pictures, formatting for plays, the lists, the whole thing, without the difficulty of heavy markup languages.

<- -c- ->

the end of this test-suite

we hope you've enjoyed this test-suite document. if you have any questions, feel free to ask them.

this is a draft, so please suggest improvements. and if you want to make your own test-suite, do!

sadly, michael hart passed away in 2011, so he is no longer with us. he's up in heaven now, where there are no typos, and every book is available...

but after he attained his 10,000 e-texts goal, michael got a new goal -- a *million* e-texts!

maybe you can serve michael's memory, and say "thanks", by helping to reach his new goal? :+)

*have* *a* *nice* *day.*

the end.

<- -c- ->

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. ^^^

^^^ [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. ^^^

^^^ [anything] your footnotes don't need to be numbered. ^^^

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

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

<- -c- ->