hello...  so you wanna make e-books, do you?  good for you.

many people say it's hard.  because it was hard.  in the past.
some writers beat their head against a wall for days, or weeks.
even web pioneers and standards geeks experienced difficulty,
occasionally actually resorting to outsourcing it to “a specialist”.
(i choose not to embarrass them now by linking to their posts.)

but no more.  as you'll see, it can be simple to make an e-book.
so simple you just click one button...  the “simple” button...

***

this is the introduction to one _online_ version of a tool that does
the work of converting a plain-text light-markup file into e-books.

the tool is generally called “jaguar”; this iteration is a python script,
an online version that's basically a demo for the offline applications,
which'll be cost-free, and cross-platform for the mac, pc, and linux.

as you can see, from the screenshot which i've pasted in right below,
jaguar's interface is simple.  you put your text in the field on the left,
then click the “simple” button, and boom! your e-books are created.

you don't have to learn .html, or fumble with angle-brackets, or any
of that crap. you just put in your text, and click the “simple” button...

the output file-formats of this web-app are .html, .mobi, and .epub.
(the web uses .html, the kindle takes .mobi, and ibooks uses .epub.)



***

no, we haven't transcended the “garbage-in-garbage-out” rule in
some magical way. the text which you put in cannot be “garbage.”

the text must be .zml — that's short for “zen markup language” —
which is a set of extremely simple formatting rules which even a
4th-grader can follow (e.g., put a blank line between paragraphs).

these rules reveal the “structure” of the text inside your book, and
“jaguar” converts that structured text into valid .html and e-books.

below, i point you to documentation of the 11 basic rules of z.m.l.;
learn 'em to prepare your own book-text when you wanna do that.

then when you use a “jaguar” tool, you'll get the results you expect.

but at first, if you'd prefer, just fiddle with the text that gets loaded
automatically, which is the _test-suite_ demonstrating various stuff.
since this text conforms to the “rules” of z.m.l., the output is correct.
so you can experiment, see how it works, and bend it until it breaks.

***

“jaguar” output takes many forms, but — for this purpose — is .html.
so, in the pane on the right, the created .html gets displayed — live!

this provides immediate feedback on if your .zml is entered correctly.
for instance, you'll want to make sure all of your headers look right...

if the output doesn't “look right” to you, it means your input is wrong;
therefore, you'll need to edit your input until you get the right output.

this constraint — that you can't modify the output per se, but rather
must edit your text until you get the proper “look” — is a vital one...
it means you can't “paint over” flawed input.  you must instead fix it,
so that eventually your text is correct.  embrace this constraint...

in addition to the _look_ of the output, you'll want to make sure that
it _behaves_ correctly.  for instance, items in your table of contents
automatically become _links_ to their appropriate chapters, so you'll
want to test some of them, to ensure they're working as they should.
(to assist you in this, any t.o.c. items which are gray are defective.)

to give you the idea about “the constraint,” it's possible for you to
make a line _look_ like a header, by making it bold and centered,
but that wouldn't make such a line _act_ like a header. in order to
make it _act_ like a header, your input text will need to be correct.
(so you know, a header is preceded by at least 4 blank lines; easy!)

again, fix your input until the output works correctly, so you'll know
your generated e-books will work right too, which is what you want.

if the displayed .html looks right, and seems to be working correctly,
then you can download the e-book file-formats, and check them out.
if you find anything that needs to be different, go back to your input,
and fix it there. fixing the output is tempting, but then you'll need to
repeat that process _every_single_time_ you regenerate your output.
that's the kind of busy-work that “jaguar” was built to save you from.

***

you can sign up right now and get your very own account, right here:

>   http://zenmagiclove.com/signup

you get your very own folder.  but it's open, so anyone can go there;
thus you must realize it is not private; now, if you don't tell anybody
the u.r.l., then it won't be that easy for someone to learn the location.
but still, do not put anything there you would not share with the world.
or to be most explicit, to keep your book a “secret,” do not put it here.
i won't steal it, and i don't think anyone else will, but still, keep it safe.

if you need some “practice” text, use a book from project gutenberg...

***

there's no commitment to an account, but if you just wanna “try it out”,
then you can play around in the “sandbox” accounts that i have set up.

but there are a couple things you should know about “the sandbox”...

first, the text is “live,” so any changes you make _will_indeed_“stick”._

and every time you click the “simple” button, e-books get regenerated,
with the files being saved right in the sandbox, writing over earlier files.

other people might be playing in their own corner of that “sandbox”,
but all of you will have the book text saved in the same subdirectory,
and all the e-book output files will be generated and saved there too.

so if you wanna download _your_ generated files, do it _immediately_
after you click “simple”, or else somebody else might overwrite yours.

here's the folder — open, for viewing — for the sandbox and its files:

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

when you click the “simple” button, your text gets saved in this file:

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

and an .epub file is regenerated, with your text, and saved here:

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

and a .mobi file is regenerated, with your text, and saved here:

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

you can also check the output from "kindlegen" to see if the .mobi had any errors:

>   http://zenmagiclove.com/zml/suite/kindlegen-output.txt

note the .epub file is stored _outside_ (above) the .epub directory,
while the .mobi file is actually located _inside_ the .mobi directory.

you might also want to examine the .html files the tool generates...
you can unzip the .epub, of course, to view the files that comprise it.
but you can also view these files right there in the .epub directory:

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

for the .mobi, all the files needed for kindlegen are in its directory.
there's a .txt version of the .opf file, for viewing inside the browser.

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

***

the last time i checked, the .epub file for the test-suite _validates,_
and the .mobi file is generated without any warnings or errors, but
it might not stay the case, on occasions, as i re-do parts of the tool.
but rest assured that any production versions will certainly validate.

***

however, it is entirely possible (and perhaps even _probable)_ that
when you enter your own text, the generated files will fail validation.

it might be because you made errors in the .zml for your input text,
or it might be because of some bug i have in the converter program.

or maybe someone “edited” (messed up) the demo text before you.

either way, let me know about the problem.  even if it's “your fault”,
because of an error in the .zml, i need to know what kind of mistakes
people tend to make...  so if you can't fix any .zml problems yourself,
don't hesitate to come to me with them.  at least not in the beginning.
at some time, i'll expect people to become self-reliant; but not at first.

(but if it's clear you just didn't do your .zml correctly, and didn't even
do the necessary work to learn it, i will kick it back to you very quickly.
the rules of z.m.l. are simple; i shouldn't need to be patient with you.)

***

new: i've decided to add a “restore” button, so when somebody does
screw up the text, you can always revert back to the original version.
i'll get to that very soon. (in-progress.)

***

so, how do you learn z.m.l.?  well, one way is to look at examples.
right here, with this online tool, you can review the input text itself,
on the left, and see how it got converted into the .html on the right.

the test-suite sandbox is very good, because it has all the z.m.l. features:
>   http://zenmagiclove.com/zml/suite/jaguar.py?book=prapr

but you can also look at some “regular” books...

here's a sandbox for “pride and prejudice”:
>   http://zenmagiclove.com/zml/prapr/jaguar.py?book=prapr

and here's a sandbox for “sherlock holmes”:
>   http://zenmagiclove.com/zml/taosh/jaguar.py?book=taosh

and here's one for “alice in wonderland”:
>   http://zenmagiclove.com/zml/alice/jaguar.py?book=alice

***

this is a “skeleton” file; copy its text as a “template”:
>   http://zenmagiclove.com/zml/skelt/jaguar.py?book=skelt

last but not least, here's a sandbox with the “rules” for .zml:
>   http://zenmagiclove.com/zml/rules/jaguar.py?book=rules

(i put it here at the bottom, just to see if you read all the way.)

that “rules” file is old, so there might be parts which are dated,
but i think for the most part that not much has been changed...
that being said, though, all these “rules” are subject to change.
i'm flexible while i see what kinds of functionality people need,
and what seems to be working well and what needs to be fixed.
i've worked on this for years, so i know that it's generally sound,
but until it gets a work-out from users, i'm flexible with details...

if you need any help, just holler...

my e-mail is “bowerbird@aol.com”.  yep, aol.  i'm old-school.
proud of it.  so if you think you can make fun of me for that...

-bowerbird

p.s.  and here's the payoff — the straight u.r.l. for the tool:
>   http://zenmagiclove.com/zml/suite/jaguar.py

p.p.s.  when you get your own subdirectory, the file-naming convention
will follow the same general pattern which has been described above.

thus, if your subdirectory were "zzzzz", here would be your u.r.l. names:

>   http://zenmagiclove.com/zml/zzzzz
>   http://zenmagiclove.com/zml/zzzzz/zzzzz.zml
>   http://zenmagiclove.com/zml/zzzzz/zzzzz.epub
>   http://zenmagiclove.com/zml/zzzzz/mobi/zzzzz.mobi
>   http://zenmagiclove.com/zml/zzzzz/kindlegen-output.txt
>   http://zenmagiclove.com/zml/zzzzz/epub
>   http://zenmagiclove.com/zml/zzzzz/mobi