let's discuss, for a minute, how to prepare a .zml file...

for fun, we'll contrast it with how to code an .html file.

***

we'll start with something basic -- simple italics.

let's say that a word is _italicized_ in the p-book.

to do that markup in .zml, you surround the word
with _underscores._  you can type 'em in manually,
or you might have a tool that has a button that you
can click to have the tool insert them automatically.

in .html, you'd surround the word with italics tags,
so an [i]italicized[/i] word looks something like that.

(i changed the angle-brackets to straight-brackets,
so an .html viewer-tool will not be confused by it.)

again, you can type the brackets-plus-tag manually,
or you might have a tool to insert 'em automatically.
most .html authoring-tools have an [i] or [em] button.

so in this case, for italics, there's not much difference
between .zml and .html...  one uses underscores and
the other uses bracket-commands, but -- essentially --
there's no difference between them.  i might think that
underscores are easier to type, and easier on the eyes,
and thus less obstructive when it comes time to _edit_,
but it's hard to argue that there's much difference here.

and thus it is with a lot of the mark-up you might do...

in .zml, you indicate a blockquote with a leading " > ",
whereas in .html you use [blockquote]xyz[/blockquote].

and in .zml, you indicate a list item with a leading " * ".
while in .html it's more like this: [ul][li]abcdef[/li][ul].

again, i think the .zml looks a lot less obtrusive, and
that is indeed part of the big appeal of "zen" markup,
but if zen doesn't matter to you, there's no difference.

***

however, there _are_ some cases where it does make
a difference when you're tagging in .zml versus .html.

for instance, take the case of _headers_...

on the face, it might appear to be a similar situation.

in .zml, you indicate a header by 4 or more blank lines,
follow it with exactly 2 lines, and precede it with a space.

so, aside from the blank lines above and below it, which
"sets it off" such that the header will gain your attention,
a header has a pretty ordinary appearance in your text:

>
>
>
>
>    chapter 7 header
>
>

in .html, you tag a header thus:  [h2]chapter 7 header[/h2]

so if it was merely a matter of the tagging of the header,
this case is exactly like the previous:  not much difference.

but various other factors come into play involving headers.

first, the table-of-contents should _link_ to every header...

at a bare minimum, this means your header has to have
an "id" that is attached to it, to which the link is directed.

so in addition to the _header_ tag, you must make an "id",
with another bracket-command, which might look like this:
>   [div id="chapter_7_header"][/div]

so now the header, with its matching "id" spec, looks like:

>   [div id="chapter_7_header"][/div]
>   [h2]chapter 7 header[h2]

you could leave it just like that.  many people do, actually.

but .zml does more -- by default -- to aid in navigation.

every .zml header links _back_ to the table-of-contents,
so a person who is at any header can _jump_ to the t.o.c.

to do the same kind of back-link in .html, you'd do this:

>   [div id="chapter_7_header"][/div]
>   [a href="#table_of_contents"]
>   [h2]chapter 7 header[h2]
>   [/a]

that's a little more work, but very few .html tools do this,
so you'd have to do it manually.  but it's still manageable.

but there's more.  .zml also generates automatic links to
the _previous_ and _next_ chapters, so a person can easily
"skim" from one chapter to the next, which comes in handy.

in order to do this in .html, you'd have to do this:

>   [div id="chapter_7_header"][/div]
>   [a href="#chapter_6_header"]prev[/a]
>   [a href="#chapter_8_header"]next[/a]
>   [a href="#table_of_contents"]
>   [h2]chapter 7 header[h2]
>   [/a]

note that this raises the level of complexity quite a bit.
the "id" was based on the header itself, so that was easy
to generate, because the two are so close to each other.
so it would be rather easy to code a reg-ex for the task.

but when each header has to know the id of the header
which came before it, and the one which comes after it,
we have experienced an increase in the difficulty factor,
to the point where the reg-ex is gonna get pretty hairy.

you will also need some tagging in there to get the links
_positioned_ in the exact way that you'll want them, but
i won't bother to put in that clutter too right now, as...

...i wish to point out that, all of a sudden, our header
has gotten _buried_ inside a lot of .html-tag clutter...
which makes it difficult if you need to do more editing.
(a rule of thumb is you always need to do more editing.)

so again, let's take a look back at the .zml header...

>
>
>
>
>    chapter 7 header
>
>

very clean.  everything is automatic.  breath of fresh air.

***

we can go through the very same exercise for footnotes.

in the body of the text, where you have the footnote,[1]
you will need to do the .html coding to create that link.

[1] at the footnote itself, which might be in the "footnotes"
section, you'll need to form an "id" for the link to jump to.

and likewise, it's usually nice to have a _back-link_ too.
which means you need to have an "id" in the body-text,
and code the back-link in the footnotes section as well.

and, seriously, that's more than you wanna do by hand.

and thankfully, most of the time, you won't need to...

many .html tools make it relatively easy to make a link.
you just click where you want the link to be, and then
click again where you want that link to jump to.  easy...

at least, it's easy if you only have a few such links...

but if there's 580 footnotes, like a book i did a while back,
you _will_ want these steps to be performed automatically.

my .zml converter does that for you.

***

now, don't get me wrong.  there is absolutely _nothing_
in my converter-tool that some programmer could not
clone in an .html authoring-tool.  nothing at all.  zilch.

indeed, it wouldn't surprise me if it's already been done.
(well, actually, it would.  a little bit.  but i'd get over it.)

for instance, the text-to-html converter inside guiguts,
the d.p. postprocessing tool, does good on footnotes...

it'd even be possible to build an .html authoring-tool
which inserted all of this code automatically and _also_
removed it from the file when you wanted to do editing
-- so you wouldn't have all that crud distracting you --
only to re-insert it once again after you were finished...

it's even possible this tool could be offered at no cost...

it's even possible it could be an open-source creation...

you will let us know if you find such a tool, won't you?     :+)

***

z.m.l. input file:
>   http://zenmagiclove.com/test-suite-2012.txt

python script to create .html output:
>   http://zenmagiclove.com/cgi-bin/t2.py

-bowerbird