z.m.l. overview


 an intro and a refresher


 by bowerbird intelligentleman


 you can "view source" for this document here:

 http://zenmagiclove.com/jagov.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
 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 meta-data chapter
 a demo for zen markup language
 the end of this test-suite
 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 (.pdf, .mobi, .epub).

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


here's how you do _italics._

here's how you do *bold.*




 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://z-m-l.com/go/alice/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 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).




 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.




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

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




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




 the " o " command for an unfilled bullet


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




 the " + " command for a second-level list


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




 the " - " command for a third-level list


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




 the " = " command for a fourth-level list


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




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


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


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

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




 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.




 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.




 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? :+)

 ~tab~~tab~http://gutenberg.org~tab~~tab~

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

the end.




 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 test footnote. but it will be short.

[anything] it can be anything.

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

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




 meta-data for this book


here's the meta-data...

 o title = a 2013 test-suite for project gutenberg
 o author = bowerbird intelligentleman
 o purpose = a test-suite
 o for = project gutenberg
 o markup = zen markup language (.zml)
 o isbn = urn:isbn:0000000000000
 o publisher = jaguar(ps)
 o subject = doing the test-suite thing
 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...

 .

 all of them in one paragraph: ??

 http://google.com

 http://zenmagiclove.com/test-suite-2013.zml

??

 http://zenmagiclove.com/zml/suite/suite.zml

 http://pgdp.net

 http://gutenberg.org

all of them in one paragraph:

http://google.com

and

http://zenmagiclove.com/test-suite-2013.zml

 ?? and

http://zenmagiclove.com/zml/suite/suite.zml

 and

http://pgdp.net

and

http://gutenberg.org.

 .

 http://google.com

 ??

 http://zenmagiclove.com/test-suite-2013.zml

 http://zenmagiclove.com/zml/suite/suite.zml

 http://pgdp.net

 http://gutenberg.org

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

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

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

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

 goodbye!

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

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

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

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

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

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

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

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

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

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

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

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