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
 hyphenation stinks
 unlucky number 13
 two spaces after a sentence
 multi-purpose block-quotes
 the play is the thing
 epigraphs and epitaphs
 lists in your book
 sometimes you want a numbered list...
 here's another example of a 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]

[1] this is the first footnote.

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

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

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]

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

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

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




 em-dashes


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

?????

the first - called an "en-dash" - is a narrow one.
you will see these in a fair number of the e-texts.
it's called an "en" dash because it was traditionally
defined as being exactly as wide as the letter "n".
(or, some say, as _wide_ as a letter "n" is _high,_
so you can take your pick between those choices.)

the second -- called an "em-dash" -- is wider, and
yes, it's called that because it's as wide as an "m",
or so the story goes, according to some people...

generally, try to use an em-dash, not an en-dash...
the en-dash looks too much like a hyphen, especially
when it is run into the words that are surrounding it.

now, the convention says that you should _not_ have
spaces on the sides of a dash. the convention is wrong.
it looks _much_ nicer if you put spaces around a dash.

perhaps even more importantly, the search capability
of many programs is thrown off if you don't use spaces.

so are the re-margination routines in many programs, so
-- to avoid these problems -- put spaces around dashes.

a problem arises, though, because there is no em-dash in
the lower-ascii codes. so you have to use a double-dash
-- like these here -- for an em-dash. ok, problem solved.
your system should be able to convert the double-dash
into a proper em-dash, if the user chooses that option.




 hyphenation stinks


hyphenation is another thing that messes up e-book
search capabilities. e-books don't need hyphenation.
so _turn_ _hyphenation_ _off_ when you make an e-book.




 unlucky number 13


there is no 13th floor in most buildings.




 two spaces after a sentence


back in the old typewriter days, students were
instructed to put two spaces after each sentence.

ever since wordprocessing, though, some people
have said two spaces are no longer required, that
it is an unnecessary leftover from earlier times.

those people were wrong. if you have one space
after a period, sentences run together too much.

but...

the thing is, it's actually a lot easier to edit
text if you only have one space after a period...
that way, you can do a search for two spaces,
and that search should come up _totally_ empty.

thus, to make life easier on the writers out there,
your software should create the smidgen of space
necessary to separate two sentences sufficiently.

so, if you're _making_ an e-book, use just one space.




 multi-purpose block-quotes


sometimes you want to quote a whole block of stuff
from someone. this is often called a "block-quote".
clever, the guy who came up with that name...

many of the project gutenberg e-texts contain
block-quotes of one various type or another.

here's an example of a block-quote, a letter.


 ~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

typically, block-quotes are indented
on both the left and right sides.

here's another block-quote, from a speech.

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

there are a number of different situations
throughout the e-texts that might call for
this type of indentation. for now, we will
just subsume them all under "block-quote";
perhaps later we will see fit to break out
a more finely-grained analysis, if we find
any special cases merit their own class.




 the play is the thing


there are plays in the library.
gotta be able to handle plays.

dale:~tab~ that's not what p.g. is all about.

bowerbird:~tab~ i think it's important to
give people a good e-book experience.

dale:~tab~ that's your opinion.

bowerbird:~tab~ yes it is.

steve:~tab~ (weakly) i can't...

dale:~tab~ no it isn't.

steve:~tab~ (weakly) get a...

bowerbird:~tab~ is too.

steve:~tab~ (weakly) word in edgewise...

dale:~tab~ is not.

lurkers:~tab~ will you two cut it out?

bowerbird:~tab~ is so.

dale:~tab~ is not...

fade to black.[3]

gotta be able to handle plays. dialog, instructions
to actors, stage directions, that kind of stuff...




 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.

so you wanna be able to handle that kind of thing.[4]




 lists in your book


i like lists. here's a list:

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

gotta be able to handle lists...




 sometimes you want a numbered list...


here's an example of a numbered list,
with the number specifically included.

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


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

still gotta be able to handle lists...




 here's another example of a list:


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


here's another example of a plus-sign list:

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


here's another example of a minus-sign list:

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

here's another example of an equals-sign list:

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




 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.




 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