(creating e-books the easy way)
by bowerbird intelligentleman
bowerbird@aol.com
copyright 2011 bowerbird
http://jaguarps.com
version 0.01 — june 1, 2011
[[creeb-halftitle.jpg]]
jaguar publication system
table of contents
warning! — trained professional at work here
chapter 1 — for whom is this e-book intended?
chapter 2 — all the various e-book file-formats
chapter 3 — this e-book is a sample document
chapter 4 — one master input, multiple outputs
chapter 5 — .mobi output, for amazon kindle
chapter 6 — .epub output, for ibooks and nook
chapter 7 — .html output, for web mounting
chapter 8 — .pdf output, for print-on-demand
chapter 9 — where you can download jaguar(ps)
chapter 10 — the tool you use to write your book
chapter 11 — the basic rules for writing your book
chapter 12 — graphic files add spice to your book
chapter 13 — numbering and naming chapters
chapter 14 — making your table of contents page
chapter 15 — various forms of styling you can use
chapter 16 — paragraphs vs. blocks of all types
chapter 17 — indicating blockquotes in your book
chapter 18 — using unordered and ordered lists
chapter 19 — hanging (outdented) paragraphs
chapter 20 — centering contiguous lines is easy
chapter 21 — poetry should be a thing of beauty
chapter 22 — the use of footnotes or endnotes
chapter 23 — tables are not possible at this time
chapter 24 — how about pull-quotes or sidebars?
chapter 25 — overview of the jaguar(ps) workflow
chapter 26 — a guide to those .opf and .ncx files
chapter 27 — put your copyright page at the end
chapter 28 — notes for jaguar publication system
chapter 29 — fix your ms-word .doc for jaguar(ps)
chapter 30 — jaguar publication system metadata
chapter 31 — you are finished with this manual
this book is written by a trained professional, who knows how to write a book in all-lowercase. but you should not attempt to do this yourself.
kids, don't try this at home.
you have been warned.
and yes, in case you are wondering, jaguar(ps) can handle uppercase letters just fine.
this e-book is intended for writers who want to create electronic-books, and who want that process to be easy. it's a manual for a software program — jaguar(ps), short for “jaguar publication system” — which facilitates e-book creation.
jaguar(ps) is a conversion program. you feed it a simply-formatted text-file, and it outputs various e-book formats for you.
i could tell you that the time for e-books is now. i could tell you that lots of authors are making money by self-publishing e-books for sale at amazon, and barnes and noble, and apple, and elsewhere. but if this book is really for you, you already know that.
moreover, you're ready to start, and you also want to speed up the process. good. then let's get to work.
it's best if you have an already-written book. you can handle the whole thing immediately, and that can work well, and be very rewarding.
equally good would be an in-progress book, one you're in the process of writing right now. after a day of good writing, you'll be able to make your book look nice and finished, and that's rewarding too.
and, if you don't have a book to practice with, why don't you just decide to write one? it's fun! it's just a practice book; you can throw it away if you decide you don't wanna keep it. but it'll help you learn.
or, if you're not in a writing mood, you can
always get the text of a public-domain book
from someplace online, and use it to practice.
project gutenberg has a boatload:
> http://gutenberg.org
different booksellers often use different e-book file-formats. and even the ones that use the same file-formats often end up implementing them in different ways. heck, even the same file-format from the same vendor can act quite differently in different versions of that vendor's hardware.
this is one of the reasons why e-book creation can be difficult.
so i developed a piece of software — jaguar(ps) — which makes it easy for authors like you.
you make one simple plain file, and jaguar(ps) then spits out the different e-book file-formats. so you just have to worry about writing the text. after that, jaguar(ps) does all the grunge work.
best of all, jaguar(ps) is absolutely free of cost. it's a gift, from me, to you, my fellow creators out in the world. so please use it wisely, friends.
i don't know about you, but i learn a lot faster if i can start with a working example in front of me. i can do modifications, see how they affect things, and yet always revert back to the working model if i've messed things up beyond recognition. this way works best for me, and makes me happy.
this e-book, the one you're reading right now, is such a “working example”. it will show you how to do a wide variety of things, in an actual sample document.
it's mostly meant to show you the formatting that you will be using, but it's still an evolving document, responding to the needs of the conversion routines while at the same time shaping those conversions.
the point is, this text might be in flux, as edits are made. the process of these changes might well provide us with useful experience in that regard.
you can download the latest version of this file here:
> http://jaguarps.com/tools
it'll likely be the version of the file with this name:
> http://jaguarps.com/tools/creeb.zml
i'll probably be keeping various “snapshot” versions of the file at that location, but the structure of the library should be clear from browsing the contents, at least if i've succeeded in doing my job correctly.
that means you'll be able to tell the newest version, as well as the edit-history as saved along the way.
there is an overriding philosophy that you should grasp deeply and intimately when using jaguar(ps). this is that you will create one “master file” which serves as an input file to jaguar(ps), which will — in turn — generate multiple output files.
your “master file” is the plain-text file which you start with, the one that contains the text of your book. it is this master file which you will edit when you want to fix typos, or create a new edition of your book.
after you've done any editing, you will regenerate the various multiple output files.
there is always a temptation, once you actually have the output files, to edit them directly, but this is a mistake, since you will need to make the changes to each of the multiple output files, and the original input file. (don't forget that!)
if you do the edits to your “master file” instead, then you always know which of your files is the updated one. it's important to remain disciplined in this particular regard, because it makes things much easier in the long run. so stay disciplined.
as for the output files that you'll be able to create, first out of the chute, we'll create a .pdf output file. then we will do .html output. based on that .html, we'll then create an .epub file. and based on that, we'll generate a .mobi file, for the amazon kindle.
so we'll now describe each of these output formats, but start with the last one first, just to be perverse.
almost all of the writers who are making money from sales of their e-books are making the bulk of that money from amazon so far.
so one very big priority will be the file-format that amazon requires, which is known as the “mobipocket” file-format, or “.mobi” for short.
now, you might already be aware that you can upload various document-formats to amazon, and amazon does the .mobi conversion for you.
the problem with that approach is that at times these conversions from amazon turn out shoddy, or not what you intended, or would like it to be.
but meanwhile, there it is, sitting online for sale; you might not want it out there on the market. if early buyers get a bad product, your reviews won't be good, and it can be hard to shake that.
so you'll want to create your .mobi file yourself, so you can preview it, to make sure that it's good, before you put it up for sale to the general public.
you might also know that the .mobi format is based on .html (which is the format used on the web).
the good news is that you don't have to learn .html. no, jaguar(ps) does all that grunt crap work for you. neither do you have to learn a bunch of kindle-specific stuff, because jaguar(ps) sidesteps that tar-pit for you, thanks to the jaguar(ps) information community, baby, sharing experience about what works and what doesn't. we keep you up-to-date. we keep ourselves up-to-date. we keep everyone up-to-date. and we keep up-to-date.
you just input your plain-text master, and jaguar(ps) will spit out a folder of files that'll create your .mobi file, using an app called “kindlegen”, which is available for free from the self-publishing section of the amazon site.
like i said, .mobi is a somewhat primitive format, and you might well be less than ecstatic with its formatting. not to worry, though, because .mobi has little time left. .mobi is already an outdated format, and the struggle of keeping up with the new demands coming from people who've recently jumped on the kindle bandwagon means amazon has no choice but to move on to something better. it might not happen this year, or next, but it will happen. what “better” means to amazon, however, might not be what “better” means for you and me, know what i mean? but at least we will have a format that works better.
in the meantime, jaguar(ps) will help you deal with .mobi.
the .epub format is another e-book file-format.
ok, this one was designed by the rich corporate publishing houses, who can afford to hire lots of tech-savvy employees to do their work for them, so they weren't too concerned with making things easy or cheap. indeed, they figured that they didn't need any competition from independent authors like you, so they enjoyed having a complex format, since it wastes your time and saps your motivation.
heck, they didn't even want e-books to succeed, so now they've been dragging their feet for years, trying to slow the erosion of their business model to keep opulent and lush lifestyles as long as they can.
but again, the good news is that jaguar(ps) will make it easy for you to output an .epub e-book, so the creative side out-wits the suits once again.
the suits did a good job in the 20th century, when the distribution of physical goods was a hard nut, and i'm willing to give credit where credit is due, so they might deserve their riches, but now it's time to give them their fancy gold watch and send them off on their luxury yachts to retire in the bahamas. we no longer need their greed. so it's got to go.
.epub isn't much better than .mobi. indeed, in many ways, it's actually worse. that's because amazon controls the .mobi format, so their viewer-programs render it rather consistently. on the other hand, there are several viewer-programs for the .epub format, and they all render the format differently, so it has become a real rat's nest. unfortunately, that's the way it is, so we have to deal with it now.
but don't let the experience get you down, because .epub ain't long for this world either. it's not just inferior, it's also splintered beyond all recognition. how can you call something “a standard” when it has umpteen different iterations, but none to spec? and being “the standard” is the absolute only thing that the .epub format has going for it, believe me.
the form of “markup” used on the web — .html, a.k.a., “hypertext transport markup language” — is the basis for the other formats here, so we will be creating .html on the way to making the other e-book formats. and once again, you don't have to worry about it, because jaguar(ps) does it for you.
all the other books out there, telling how you can create e-books easily, basically say that you need to know .html to make an e-book, so they tell you that .html is easy, and then they go on to teach you .html, when you didn't really want to learn .html, and you certainly don't want to have to apply it.
what you were looking for is something simple, which is what they promised you up-front, except then they failed to deliver.
this book is different. this book isn't gonna teach you .html. i assume you know some .html, and i'll discuss it when it's relevant, but you don't need to “learn” it, especially if you don't want to learn it, and i'm certainly not going to teach you any, so there.
now, like i said, .html is the “building block” for the other two formats we want — .mobi and .epub.
but of course, that's not the whole story.
one thing that's very important to keep in mind is that the .html format enables you to put your book up on the web, where it can be accessed freely by the public.
now, on the one hand, you might think that that would limit the number of people who would buy your book — i.e., actually pay cold hard cash for it. and that might be the case. but it also might not be. various authors have found that putting their books up for free has lead to increased sales. there are lots of reasons for this, and no, i won't bother to go into all of them at this time, because i'm not trying to persuade you about anything; truly, you can do whatever you want.
but if you do decide to put your book on the web, you will be able to do so, thanks to the output from jaguar(ps), and you'll be able to mount your book in a number of different ways.
for instance, you'll be able to mount your book in a page-by-page fashion that enables your readership to engage in a discussion about each specific page.
another thing readers might do is to report typos or other types of errors on that page, so you can fix 'em.
you'll also be able to mount your book section by section, if you prefer that. and put the whole book on one webpage.
however you do it, putting your book on the web will enable your fans — and the general public — to talk about your book, with each other, and with you as well.
in general, this type of interaction with your fans is something that will help create a bond between them and you, and that can end up being a very cool thing.
one other thing to consider is that, once your book is mounted on the web, it can be indexed by google, which will increase its ability to be found by people. it also establishes you as the originator of that text, so nefarious types can't plagiarize you quite so easily.
but whether you decide to mount your book or not, jaguar(ps) makes that option available to you.
love it or hate it, .pdf lives out there in the world, so jaguar(ps) can create a very nice .pdf.
you might be surprised how many people actually prefer .pdf as a format. but that's beside the real point here, which is that you can use your .pdf output for your print-on-demand purposes, meaning that you can satisfy your readers who want a physical book too.
with print-on-demand, your customers pay the cost of having the book printed, so you don't have any up-front expenses which put the burden on you to recover them. this is one of the beautiful things about our new world.
ok, you're ready for the jaguar(ps) program now.
you can download jaguar(ps) here:
> http://jaguarps.com/tools
this is the mac version:
> http://jaguarps.com/tools/jaguar.app.zip
this is the p.c. version:
> http://jaguarps.com/tools/jaguar.exe.zip
this is the linux version:
> http://jaguarps.com/tools/jaguar-linux.zip
the program comes zipped up in a folder, with a version of this manual in it, named “creeb.zml”, where “creeb” is short for “creating e-books”, and some other files as well.
these other files specifically include one called “creeb-spex.txt”, which is a file that contains the “specifications” which the program will use when it creates output e-books from the “creeb.zml” file.
there are also the graphics files used in this book.
creeb-halftitle.jpg
creeb-image.jpg
creeb-boygunbook.jpg
creeb-pull-quote.jpg
creeb-curls01.jpg
creeb-curls02.jpg
creeb-curls03.jpg
the first thing you should do is execute jaguar(ps).
just double-click it, and follow the prompts. it will ask you to verify things, but you can assume they are correct, and just continue to click as advised.
the program will tell you when it has finished.
***
keep this “jaguar” folder for future reference, but for your own book, you're going to want to create a copy of this folder. you might call your folder “dream-folder”. the program expects that you'll use a 5-letter name for your folders, so “dream” is a perfectly good name, but you can call it anything. for the purpose of explaining, though, i'll use “dream”.
inside your folder, you will rename the “creeb-spex.txt” file to “dream-spex.txt”. you'll need to edit it, to give it the proper metadata and parameters for your e-book. most of it should be self-evident. one gotcha, though, is to make sure you give the name of the font correctly. it'll probably be the name you see in the “font” menu on your word-processor. if you have problems with it, you can always rely on “verdana” and “georgia” as good.
you should then delete all of the other files that have names starting with “creeb”, to eliminate the clutter.
then copy in your book, naming the file “dream.zml”. remember that it must be a plain-text file, not some word-processing file. have your word-processor save out a plain-text (ascii) file. you'll also need to ensure that your file is formatted according to the “rules”, which will be explained in chapter 11.
you'll also need to move all your image-files into dream-folder. i suggest that you name all of them with a name starting with “dream-”, for the clarity, but that's not required.
then run jaguar(ps). if there is only one .zml file in the folder (which is how it should be), it will know that that's the file which it's supposed to work on. and if it's working on “dream.zml”, then it knows that it's supposed to look into “dream-spex.txt” for the specifications.
the program will prompt you to click the button that's located at the upper-right of its window. you will need to click this button to go through each step of the process, after reading whatever the program has presented to you in its text-field.
if you just leave your book-file in this folder as you work on it, you'll always be able to just run jaguar(ps) and generate the current version of your e-books with a few simple clicks of a button. it's free and easy.
at this point in time, jaguar(ps) is only a converter. you cannot actually use it to write your book.
you can use any text-editor or word-processor you like. the decision is up to you. you should use whatever makes you feel comfortable.
at any time you want to create some e-book versions, you'll just save out your book — as a plain-text file — so that it can be input to jaguar(ps).
whatever writing tools you use, though, you'll have to follow some simple rules, so that when you feed your text into jaguar(ps), the conversions are done correctly.
if your book is already written, you'll need to re-work it so that it follows the rules correctly. that's fairly simple.
i'll discuss the rules in forthcoming chapters; for now, i'll just note that if you are still in the process of writing your book, following these rules while you write mean that you'll be able to use jaguar(ps) to generate the e-book output at any time. this can be very valuable.
many authors report that it becomes easier for them to proofread and edit their books if they get away from their writing environment. so generating an e-book file and sideloading it to your kindle or your ipad (or even to your web-browser) at regular intervals might mean that you end up with a better book. some people like to use a .pdf to proof, because it “looks like a book”. so be it.
it's also good for your ego to see your in-process book in a “finished” format. it helps you envision your success. moving yourself to the end — slowly maybe, but steadily — is an important part of the recipe for attaining completion. it can be a long slog to write a book, and keeping yourself motivated is an important consideration during the haul.
if your book is already written (let me guess, ms-word?), there are some things that you can do which will facilitate its transition to jaguar(ps). that's discussed in chapter 29.
for now, though, let's cover the basic rules.
jaguar(ps) makes certain assumptions about how the text in your book will be formatted. for the most part, these rules were based on what people do “naturally” when they're writing a long document, or even an e-mail, so they should seem rather “intuitive” to you. and indeed, you might already be doing some of them, maybe even most of them. but even if you're not, it'll be easy to adjust.
***
scene-break
see that line of 3 asterisks right there? that's called a “scene-break”, and you'll often use them to signify that there is some break between the last paragraph and the next paragraph. some printed books just show it as a big white space between the paragraphs, but in an e-book, we need to be a little more clear for the reader, so we mark it with an actual separator.
***
centering a line
you center a line by putting a space in its first column. that's easy, isn't it! i'll discuss this in more detail later, but for the time being, you can just remember the simple version here.
oh, you might have noticed that the 3 asterisks which composed the scene-break up above were centered. that's because they were preceded by a space.
***
paragraphs
use a blank line between paragraphs. easy, eh?
the truth of the matter is that most fiction consists of lots of plain old paragraphs, with some chapter headings and maybe a few scene-breaks as the only interruption to the flow of those paragraphs.
other books can be more complicated in layout, sure, especially textbooks or manuals, but fiction is usually straightforward. so if you can handle paragraphs, things are gonna be pretty simple.
now, just because you use a blank line between your paragraphs in your text-file does not mean that that's how it will appear in your e-book output files.
when you run the conversion program, you will have the option of “indented paragraphs”, the kind you see in printed books, where the first line of the paragraphs gets indented, and there is no extra space between the paragraphs.
if you want, you can also have “block paragraphs”, where the first line is not indented, so paragraphs are indicated by a “blank line” between them. this is more common on the web. but i do not recommend it, because you want your e-book to “look like” printed-books, not like a website. so i strongly advise you to use indented paragraphs. but it's your e-book, so the final choice is yours.
you can even have the conversion program do a “hybrid” mode, where the paragraphs are indented, but there is also a space between paragraphs. some people consider this to be a nice compromise. others think it's the worst of both worlds. but again, the final product reflects on you, so it's your choice.
when you're writing your book, you can indent your paragraphs if you want. just make sure that when you prepare the text for jaguar(ps), there are no indents, and there is a blank line between the paragraphs. one way to accomplish this is to do a global change where you search for the indent and replace it with a blank line. this is discussed for ms-word in particular in chapter 29.
***
chapter headings
as we said above, most fiction is little more than a bunch of paragraphs interspersed with chapter headings. so now that we've covered paragraphs, let's discuss chapter headings.
jaguar(ps) needs to be able to determine your headings. so there's a way that you can mark them very easily.
you just insert a bunch of blank lines (at least 4) when you are about to start a new chapter. after those blank lines, type the chapter heading, then type exactly one blank line, then the chapter subheading, then exactly two blank lines.
so it might look like this:
last line of the old chapter
blank line #1
blank line #2
blank line #3
blank line #4
blank line #5
blank line #6
blank line #7
chapter heading
one blank line
chapter subheading
blank line #1 of 2
blank line #2 of 2
first line of the new chapter
***
if you only have a chapter heading (and no subheading), then type 4 (or more) blank lines before it, and exactly 2 blank lines after. that's how you indicate a new chapter.
that might look like this:
last line of the old chapter
blank line #1
blank line #2
blank line #3
blank line #4
chapter heading
blank line #1 of 2
blank line #2 of 2
first line of the new chapter
***
that's all you need to do to mark a heading!
when jaguar(ps) sees at least 4 blank lines, it knows that it's supposed to start a new chapter. so it will advance to a new page, because that's what most printed books do when they start a new page.
it also makes the chapter heading big, and bold, and centers it on the page, because that's the way a chapter heading is supposed to look. it also automatically sizes the headings, so they look appropriate on the page, not too big or too small.
jaguar(ps) also stores info about the chapter heading so it can compare it to the info found in the table of contents, and create links from the table of contents to each chapter. (it also creates a back-link from the chapter heading to the table of contents, because that can be useful to the reader.)
it does all of this linking automatically, thereby saving you lots of time and energy, so you can focus on the writing.
***
the cover/title-page section
the very first section in your book isn't a chapter at all — it's the “cover” and/or “title-page” (depending on how you choose to think about it). so the very first line of text in your file should be the title of the book, followed by 2 blank lines, then the subtitle (if you have one, and if you do, it too should be followed by 2 blank lines), and then your author by-line, by itself, on a line that starts with the word “by”.
you can have other stuff on the cover-page if you like. for instance, look at this book, and you'll see what i chose to put on the title-page. but everything you put on this title-page will be squeezed onto a single page, so don't try to put too much on there, or it will all be in small type.
***
the table of contents section
the second section in your book isn't a chapter either. it must be the table of contents, with “table of contents” as the heading. (some people say “table of contents” is redundant, but for reasons i'll discuss later, i prefer it.) i'll discuss the table of contents more fully in a later chapter. we put the table of contents up front because navigation makes it easier for readers.
***
other front-matter pages
you might also have some other “front-matter” pages, like a dedication page, a foreword, a preface, an introduction, or whatever. again, treat these as if they are “chapters” — with a heading preceded by 4 (or more) blank lines, and followed by exactly 2 blank lines. (most front-matter sections won't have a subheading.)
in most books, the dedication page has no heading, but you must include one, so jaguar(ps) doesn't get confused. it doesn't hurt to have it labeled explicitly, and we want to give jaguar(ps) a place to link to. so give every section its own heading.
***
italicized text
you can see that i've used some italics in my text here. in order to indicate italics to jaguar(ps), you must enclose the italicized word with underbars.
if you want to italicize an entire phrase, you must enclose the phrase with underbars and also use an underbar wherever there is a space between words in the phrase.
you can also surround each word with its own underbars, if that seems more intuitive to you.
the general rule is that you want the starting-underbar (which turns the italics on) to have whitespace to its left, and the ending-underbar (which turns them off) to have whitespace to its right. so you'll put these underbars outside of any bordering punctuation.
***
bold text
to have a word shown in bold, surround it with asterisks. to put an entire phrase in bold, surround it with asterisks, with an asterisk between each word.
it should be noted, however, that most books never use bold inside the text itself. so you should avoid using bold if at all possible. (and we don't even have a command for doing bold-italics, because those are truly unspeakable.)
it's unnecessary to make headings bold. jaguar(ps) knows that headings should be bold. adding asterisks will probably screw up the conversion, so don't do it.
***
that's enough for now
that's enough to get you started. it's amazing, but these rules alone will finish many books.
but if your book has features that are more complicated, don't fret. we'll discuss how to handle them as we go along.
images add spice to any book. they can be colorful.
and for some books, they add a lot of value as well, sometimes to the point that they are nearly required. for instance, a bicycle-repair book wouldn't be nearly as useful if it had no pictures or illustrations in it; indeed, it would be nearly useless.
one of the great things about e-books, compared to conventional ink-on-paper books, is that images are far more easy to incorporate. you don't need to do any color separations, or any of that other difficult garbage that used to be necessary with a print-book.
moreover, it's easy to incorporate images into your e-book. jaguar(ps) will handle all the difficult aspects for you automatically. just include the image-file in the folder where your text-file is located, and jaguar(ps) will find it and put it where you tell it to put it.
so think about images you can put in your book. it's best to use photos you have taken yourself, since there aren't any complicated rights questions involved. it also makes your book more personal, deepening the value of your connection to the work.
jaguar(ps) accepts the four basic image formats: .jpg, .png, .gif, and .tif.
let's say we have an image-file named “image.jpg”. to tell jaguar(ps) to place that file here in the book, right after this paragraph, we make a line like this:
[[creeb-image.jpg]]
this is the caption for image.jpg
so what you do is put a double-left-bracket to the left of the filename, and a double-right-bracket to the right of the filename, and jaguar(ps) will include it, and place your caption underneath the image. the caption, of course, is optional.
the kindle will automatically resize most images to the size of the display, to enhance their viewing.
if you don't want to have your image resized, you should make it smaller than 250px*300px.
if you want to size your image “correctly” so that it won't be resized, make it 520px*622px.
jaguar(ps) centers the image for you. perhaps in later versions of the program, we'll get more fancy, and offer different alignment options. but for now, you can have any alignment you like, as long as it's “centered”.
here's another image, called “boygunbook.jpg”.
[[creeb-boygunbook.jpg]]
the main rule is that each chapter in your book must have a unique name. that's because internal links and labels are duplicates of the chapter name, and they must be unique.
it's a good idea to number your chapters, and “name” them, meaning to give them a “chapter title” of some sort, to inform the reader what's going on in that chapter.
you'll see that a lot of fiction books don't have chapter titles, but rather rely on numbering alone. with e-books though, it's better to give your reader some “reference points” that help them know where they are as they navigate the book, and chapter titles are very good in that regard, serving as reminders about the story as the reader goes through the book, and most especially when they return after an absence.
numbers are also good as reference points. moreover, they will help you, as the author, when you are creating your book. if you only use titles, you (and your readers) can often get lost.
in this regard, it is useful to make an outline of your book. (or, if it feels more friendly to think of it that way, consider it to be “a table of contents”.)
if your book has sub-chapters, an outline will be a necessity. we'll discuss sub-chapters at a later time, as the program grows in complexity.
jaguar(ps) assumes that the table of contents page will be immediately after the cover/titlepage. jaguar(ps) will work incorrectly if the heading for this section isn't “table of contents”. (i don't know if that's really true, but it sounds scary, eh?)
jaguar(ps) automatically creates a table of contents that is based on the chapter headings that are actually in your book, as a check to make sure that the one you gave it was correct, so you can always replace your version with the one it creates.
if you use chapter numbers and titles too, as i recommend, they should be combined on one line, separated by an em-dash. this saves space and makes the “table of contents” manageable. again, for an example, see what i've done in this book.
one thing that jaguar(ps) does which might seem odd to you at first is that it lists the book's title in the “table of contents”, and even the table of contents itself in its table of contents. it's unusual, at least as far as p-books go, but it's a good idea for electronic-books, as then this table of contents serves as the base for building a “card-catalog” for an electronic-library.
one of the things that you should consider, when you create chapter titles, is to keep them all about the same number of characters, so the lines in the table of contents are fairly even. you should also avoid long titles, so they'll fit on a single line.
one other thing about the table of contents. if you add a string of 9 periods, preceded by a space, to the end of each item in the table of contents, jaguar(ps) will form a link to the chapters. not only that, but in the .pdf version, it adds the page-number, so your table of contents will resemble that of a printed-book. you can see that i've done this in this example.
as we discussed earlier, most books contain italics as their primary form of emphasis in the body text, and usually their only form of emphasis.
bold is generally reserved for headings.
you can get italics by using surrounding underbars.
you can get bold by using surrounding asterisks.
even though some e-readers support other forms of emphasis, like bold-italics, they are not generally necessary, so they are not supported at present by jaguar(ps).
this decision also applies to other forms of “styling” that are allowed in .html. for example, strikethrough is generally permitted, but you see very few print-books that have ever used strikethrough, so it's not supported.
another old .html trick is to use “big” or “small” tags, which made the text bigger or smaller, as you'd imagine. but since e-reader hardware allows a person to set the size of the text to their preference, there's no sense in making the text bigger or smaller against their wishes. they set their preference, and you should respect it. even if some things — let's say, for instance, footnotes — were generally expressed in smaller type in the past, it's not necessary to continue that practice. making type in a smaller size will only force the reader to make all of the type bigger to read the smaller type, and then the regular-sized type would be too big. so just don't do it.
jaguar(ps) doesn't support superscript and subscript either, at least not at the current time. but if there is some good argument for supporting it, let me know and i will consider it.
the final means of “styling” common to print-books is the use of a different font-face to convey the information.
where you find this employed, for the most part, is technical documentation, where a monospaced font is used to show you computer code. or sometimes it will show the text that you are supposed to type in to the computer. i'm guessing that most of the people who will use jaguar(ps) won't need this type of feature yet, so it's not being supported at the present time. but if you have a need for it, do please let me know, and we will find a way to incorporate it for you.
jaguar(ps) analyzes your text by splitting it into “chunks”; a chunk is each set of non-empty line(s) that is separated by blank lines.
in its first pass, the program places the chunks into two distinct types, known as “paragraphs” and “blocks.”
“paragraphs” are very obvious. they conform to the standard definition, so you already have a good understanding of them, and they're usually relatively easy for jaguar(ps) to recognize.
indeed, the rule jaguar(ps) uses is that any chunk that starts with a letter or a number in column 1 is a paragraph. so you too can easily recognize what jaguar(ps) will call “a paragraph”.
***
anything that isn't a “paragraph” is a “block”.
there are lots of different kinds of blocks, like:
unlike paragraphs, which are generally rewrapped to the margins of the current viewing environment, a block has linebreaks which are to be respected.
one thing in particular signifies a “block” to jaguar(ps), and that is that there is a space in the first column of each line of the chunk. once you understand this simple and basic rule, it's easy for you to signal jaguar(ps) that a chunk is a block — just make sure that the chunk starts with a space in column 1.
the next thing to remember is that you must inform jaguar(ps) about what kind of block it is. again, there are simple rules about how to signal each kind of block, but if you remember that that's the purpose of these rules, to signal which kind of block, it'll make it easy for you to remember the rules. you'll see this accented in the next chapter, on blockquotes.
now that we've discussed the basic elements of any book, we can start covering the ones which you might or might not have in your particular book. the first one is blockquotes.
a lot of books contain quoted material. blockquotes are traditionally indented a bit extra on the left and the right, to set them off.
to indicate a blockquote, preface lines with a space followed by a right-angle-bracket followed by another space, then each line:
fourscore and seven years ago,
our forefathers brought forth,
upon this continent, a new nation,
conceived in liberty, and dedicated
to the proposition that all men[1]
are created equal.
you might well recognize that these “>” greater-than signs are commonly used in e-mail programs, and on the internet too, to signal some bit of text that you've copied from somewhere else, which is exactly what a blockquote is. so jaguar(ps) recognizes that this is how blockquotes are commonly delineated, and that becomes the rule for how it recognizes blockquotes, making this a particularly easy rule for you to remember.
any pre-existing linebreaks in a blockquote are respected. so if you want to have the blockquote wrapped to the margins in the output, just put all of it on a single line which is prepended with the “ > ” indicator. since there are no linebreaks, the text inside the blockquote will be wrapped if/when it hits the margin.
does your book have lists in it? or bullet points?
***
unordered lists
maybe your book includes a list of the planets?
the first thing to remember about a list is that every item must start with a space in column 1, to indicate this chunk is a block, not a paragraph, and that the linebreaks after each line are significant.
as you can see here, to have a bulleted list created, you can use the letter “o” in the second column of each line, so it's preceded and followed by a space.
again, the “o” character kinda looks like the bullet which is commonly used in a bulleted list, so it is thus easy for you to remember that this is the rule for lists. but there will be other characters which might also be reminiscent of the bullets commonly used in lists, and thus help remind you of the command.
these characters can be used to create a bulleted list:
you must use the same prefix for every item in a list. (you can use different prefixes for different lists, if you like, but within each list, the prefix can't change.)
any of those characters will give you a list. this is how you get what .html calls an “unordered” list.
your list might actually have some kind of implicit ordering within it, such as the list of planets above, but as long as it's not a numbered list, .html still considers it to be an “unordered” list.
here is a list of the vowels:
***
ordered lists
you can also have an “ordered” list, which is clearly known more commonly as a numbered list of items.
to get a numbered list instead, just start the list-items with a space (of course, because this chunk is a block), then the number which you want the item to have, with that number followed by a period followed by a space.
1. you
2. can
3. use
4. ordinary
5. numbers.
you are not constrained to start at number 1. nor are you constrained to implement by 1, or even to go in order.
33. or you
42. can do
808. some stuff
123. that .html
9. will not
7. normally do.
you might know that an ordered list in some fairly recent versions of .html actually does have to start at number 1, and it is constrained to implement the list by 1. but you can ignore that, because jaguar(ps) doesn't use a plain .html “ordered list”, not unless you specifically request that type.
if you do want to have a regular .html “ordered” list, one which follows all of the .html parameters, just preface each item with a number sign — # — followed by a space:
you can also have “numbered paragraphs”, which is something of a hybrid between a form of numbered list and a special type of paragraph. these are discussed in the next chapter.
1. sometimes you might want to number your paragraphs.
2. or maybe not.
3. in these cases, the numbering is usually important in some way, shape, or form, so you'll want to accent the numbers, and the best way to do that is to “outdent” them — which means you're gonna “indent” them with a negative number. you can do that by making the first line of the paragraph flush with the left margin, and then indenting the rest of the paragraph. i'm going to add this sentence as filler to this paragraph in order to illustrate what it looks like when a fairly long paragraph is set in from the left margin. as you can see, the fact that the number “sticks out” from the paragraph makes it prominent. if you were doing something like a timeline, for instance, then you might use the year as the outdented number.
4. here's a nonsense paragraph, just to illustrate the point again. yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada yada yadayada yada yadayadayada yada yadayadayadayada.
just put a space in column 1 to center a line.
this line will be centered
put a space in column 1 of each line in a chunk consisting of several contiguous non-empty lines if you want all of those lines centered.
this line will be centered
and so will this line
here the third line is centered
and so is the fourth
and here is the bottom line
poetry
can present
a challenge
in e-books
because of
the inconsistency
in the left margin.
in jaguar(ps)
just use spaces
to indent each line
as much
as it
should be.
the other challenge
that poetry gives us
is when lines wrap
because they are
too long for the
current view-port.
that's a very difficult
subject that we will
have to address when
we have more time.
your book might contain footnotes or endnotes. in an e-book, where the concept of “pages” often has little meaning, where footnotes cannot find a toe-hold, most people have come to agree that endnotes should be used.[3]
to indicate a footnote in your text, just put the footnote number in square-brackets.[4]
as you can tell, the footnotes need to be numbered, and enclosed in square brackets. the other rule, a 2-parter, is that the footnote reference — the one in the body of the text — is required to have no whitespace to its left, and is required to have whitespace (either a space or a line-break) to its right.
that is, it must be [1] attached to the word on its left, and [2] separated from the word to its right. notice that the bracketed numbers in this paragraph don't meet condition [1]. so jaguar(ps) isn't confused that they are footnote references.
the footnotes themselves are collected in a section at the end of the book. for the footnotes themselves, the rule is reversed: the bracketed footnote number itself must be at the start of the paragraph, and it must be followed by a space. you can see how i've done it in this example document.
this is how jaguar(ps) tells the difference between the footnote references and the footnotes themselves. (of course, the numbers inside the brackets must match for the reference and its corresponding note.)
jaguar(ps) looks for labels like these, and then matches the label in the body of the book with the other matching label in the “notes” section at the end of the book, and links them together, automatically, so you don't have to worry about doing that grunge work.
you can have 100 footnotes. or 200! just number 'em right, and jaguar(ps) will take care of creating all those links. aren't computers wonderful and nifty?
tables are not yet possible with jaguar(ps). if you have a need for tables, let me know. if you have an immediate need, turn the table into an image, and put it in the book that way.
just so you know, even when jaguar(ps) does support tables, it will only be fairly simple ones. some people are reading these e-books on their phones, for crying out loud, so their screens are very small, and there just isn't a lot of room for a big fancy table. so learn how to split up your big tables into smaller meaningful tables that can be comprehensible on small screens.
how about pull-quotes or sidebars? i dunno. how about them? if you need them, tell me.
likewise, for immediate needs, use an image.
[[creeb-pull-quote.jpg]]
ok, we're wrapping things up now. here's what's gonna happen. you put your text into jaguar(ps), and then you specify some basic information about the book, such as the title and the author and all that. next you will specify your preferences, in terms of fonts, margins, and all that.
then, when you're done with all that, you'll click a button, and then “boom!”, a number of files are created for you.
one of the files will be the .pdf file, which is a standalone.
another will be the .html file containing the entire book, which is also a “standalone”, when viewed in a browser.
you will also get an .epub folder, which contains all of the files which you need to create an .epub file. all you need to do at this point is to zip up the file. but the technocrats who invented the .epub format didn't want anything to be easy, so they specified that an .epub file has to be zipped a certain way, or it won't be “valid”. fortunately, there is a little utility online that does this specific type of zipping. you just drag the folder of files onto this app, and it zips it. then you'll have your .epub. however, you must also then check the file to make sure that it is “valid”. (some online e-bookstores require that an .epub be “valid” in order for them to accept it from you.) again, luckily, there's an app to check this for you. just drop your .epub on this app, and it will tell you if the file is “valid”, or if there are problems. here's where you need to fall to your knees and thank me, because i dealt with countless numbers of “invalid” files along the way to figuring how to make jaguar(ps) create “valid” files for you. i beat my head against the darn wall, so you wouldn't have to. and if jaguar(ps) doesn't create a “valid” file for you — assuming that you fed it correct text — i will do the grunt work of figuring out how to make it right. you're welcome. ;+)
you also get another folder, a “kindle” folder, which will contain all the files that are needed to create a .mobi file. this is a little more sketchy, however, because you have to use a program called “kindlegen”, available from amazon. kindlegen is a “command-line” program, which means that it can be a pain, especially for mac folks who rarely do that. you need to download kindlegen, and uncompress it, and puzzle through amazon's instructions on how to operate it. it's not difficult, once you know how to do it, but getting to that point can be a small pain. what you will eventually do is to point kindlegen at the file with the “.opf” extension. (don't point it at the .html file, or you won't get the nice cover image and the various table-of-contents pages that serve as the hallmarks of a well-prepared .mobi e-book.)
there is another option, though, to make your .mobi file. you can download a copy of amazon's “kindle previewer”. (you'll find it in the same place as the kindlegen program.) run the “previewer”, and then drag-and-drop your .epub file onto it. the previewer will convert it into a .mobi file. if it works for you, you don't have to mess with kindlegen.
two files that are required by .epub, and all-but-required for .mobi as well, are the .opf and .ncx files.
these files are a great example of the needless difficulties imposed on us by the obsessive-compulsive nitpickers on the committees who invent these obtuse e-book file-formats.
they want to make things difficult for self-publishers!
even though these files are required, there is precious little clear-speaking explanation of them available online. so you can thank goodness that you probably won't need to ever dig into them, or understand them, or edit them.
but in the event you do, later versions of this document will explain the cursory knowledge that i've managed to obtain about them. so check back then.
on the back of the title-page in most print-books, you'll find the copyright page. it's full of legalese, and it's very boring, so it doesn't really belong in the front of an electronic-book. it's legal to put all that crap at the end of a book, so if you must include it, put it at the end. you'll also wanna read the chapter where i discuss the “metadata” section of the e-book.
[1] so even the great emancipator was still a product of the sexism of his time. we presume he'd now happily agree all women are created equally equal, thank you very much.
[2] some disagreement still persists on the status of pluto as a planet. whatever. we need a period for our sentence, or mary's violet eyes and johnny get in a lotta trouble, know what i mean? so pluto is a planet in my book, end of story.
[3] in fairness, the take-home message is not universal, but it is widespread.
[4] as usual, these rules are derived from common conventions elsewhere. for instance, this square-bracket convention for notes is used by wikipedia, as well as lots of other systems.
here are some quick instructions on how to fix your ms-word .doc for jaguar(ps). (ok, really, they're long, and kind of boring, but that's what you get for using ms-word.)
you're gonna use the “search” facility inside ms-word to locate stuff in your text that you will probably need to change. to aid the effort, it's best that you turn on “invisibles” (i.e., the linebreaks and spaces). also, before you begin, make sure that you have a couple copies of your ms-word document, so if things go badly, you can always revert. do the work on a copy.
first of all, if you didn't put a blank line between your paragraphs, you should change each linebreak to a double-linebreak. you can do this by changing “^p” to “^p^p”. the bad news is that, if you have any “blocks” — like lists, or address-blocks, or poetry — this find-and-replace will fracture them badly. you'll have to look through your entire book to find out if this happened anywhere, and then repair the damage, by selectively changing those double-linebreaks back to a single linebreak. while you're doing this, make sure that each line of your block has a space at the beginning. (if you prefer, you can put those blank lines in before you do the global change, because then it will be easy to locate the fractures, because they will be two linebreaks followed by a space. either way, it's a manual process.)
next, you probably made your headings bold, so search for any bold text. on your headings, make sure that they have at least 4 blank lines before them, and 2 blank lines following them. if you have a chapter heading and a subheading, there should be one blank line between them. (it won't work to use a colon to separate them.) you can also search for a manual page-break — “^m” — if you used them on a new chapter. step through the book to make sure you got all of the headers.
after writing up the final step in the process, in the next paragraph, i realized it was too tortured, so you can just skip over it. i will find a way to simplify it, perhaps even automate it for you, so read it now only if you need the entertainment.
the other thing you're gonna have to change is the “styling” — i.e., the italics and bold. again, this is relatively easy using find-and-replace, but ms-word can get kind of funky, so i wouldn't do this find-and-replace blindly. look at each instance to be changed, and approve each one individually. first, to make things easier to see, change all of your italicized text so that it's red (or some other bright color you can easily see). to do this, search for a wild-run of italics, and change the color to red. (to search for a wild-run of italics, just leave the “find” box empty, and then from the “special” drop-down menu, choose the “font” selector, and pick “italics” in the dialog.) in the “replace” box, do the same thing and pick “red” as the text-color. you can do this change globally, without any need to look at each one. now, after you've turned the italics red, you can then do another search for each wild-run of italics, and precede it with a space followed by a unique character, both of which should be declared to be “regular” or “plain”, and black in color, rather than red and/or italic. then do another search for each wild-run of italics, and follow it with a (different) unique character followed by a space, where again both of them are declared to be “regular” or “plain”, as well as black in color, rather than red and/or italic. then, change the first (preceding) unique character followed by a space into the unique character without a space. then change the unique character into an underbar. then change any instance of the (following) unique character which is preceded by a space into the character all by itself. (that is, delete the space.) this ensures that the closing character is nestled right up against the word which it follows, which is exactly what we want. so at this time, you can change the closing unique character into an underbar. finally, globally change every italics space into an underbar.
ok, that explanation was really complicated, or at least it seemed that way. even though what we wanted to accomplish wasn't really all that difficult. so i will improve those instructions, and maybe even write up a little program to do it automatically. but right now, i've gotta get this software out.
***
whew! that was quite a process, wasn't it? the good news is that if you follow the rules from now on, you can still continue to use ms-word if you want to. you simply save out a plain-text file to submit to jaguar(ps) whenever you want to create some e-books.
anyway, here are some “makeover” pictures to reward you for plowing through all of that boring old text.
here's the “before” shot:
[[creeb-curls01.jpg]]
and here are the two “after” shots:
[[creeb-curls02.jpg]]
those curls are nice, aren't they? and she's pretty!
[[creeb-curls03.jpg]]
this is the metadata section for “jaguar publication system”.
this data is saved in an external file called “creeb-spex.txt”, which is what jaguar(ps) will use as the “specification file” for the text contained in the document named “creeb.zml”.
but i have also included it here, in the book itself, because the “metadata” should travel with the book itself, inside it, and not be separated from it.
indeed, future versions of jaguar(ps) will first look inside the book itself for this metadata information. only if it cannot be found there will jaguar(ps) look for an external “spex” file.
***
file-prefix: creeb
title: jaguar publication system
sub-title: creating e-books easily
author-first: bowerbird
author-middle:
author-last: intelligentleman
publisher: bowerbird productions
rights: copyright 2011 bowerbird — all rights reserved
language: en-us
publish-date: 2011-06-01
subject: jaguar conversion manual (first draft)
description: this is a manual for the jaguar conversion app
isbn: 0000000000000
uuid: 0000000000000000000000000000000000000000
kindle-text-font: georgia
epub-text-font: georgia
pdf-page-width: 5.5
pdf-page-height: 8.5
pdf-margins: 54
pdf-text-font: bookman old style
pdf-text-size: 10
pdf-text-leading: 11.99
ok, congratulations, you made it to the end of this book!
but this is just the start of a longer process. if you use this program, and become a self-publisher, i encourage you to become a member of the “jaguar” community. i'll be responsive to input from the users of this program, who i will expect to do exploration and experimentation with the different output formats, to find the best way of creating e-books. we will all benefit by helping each other.