a brief introduction to z.m.l.


 by bowerbird intelligentleman


 you can "view source" for this document here:
 http://zenmagiclove.com/hnews/hnews111111111.zml




 table of contents


 a brief introduction to z.m.l.
 table of contents
 preface to this brief introduction
 chapter 1 -- review paragraphs
 chapter 2 -- review sections
 chapter 3 -- text styling in your book
 chapter 4 -- poetry and other silly things
 chapter 5 -- images in your book
 chapter 6 -- linking in your book
 chapter 7 -- multi-purpose block-quotes
 chapter 8 -- footnotes and endnotes
 chapter 9 -- lists in your book
 chapter 10 -- epigraphs and epitaphs
 chapter 11 -- tables in your book
 chapter 12 -- the play is the thing
 chapter 13 -- unlucky number 13
 chapter 14 -- hyphens and dashes
 chapter 15 -- hyphenation stinks
 chapter 16 -- two spaces after a sentence
 chapter 17 -- preformatted text and code
 chapter 18 -- the notes section
 chapter 19 -- meta-data for this book




 preface to this brief introduction


this is the preface.




 chapter 1

 review paragraphs


separate paragraphs with a blank line.

don't indent paragraphs with spaces or tabs.

(indeed, don't use tabs anywhere.)




 chapter 2

 review sections


separate the sections -- such as chapters,
but also front-matter sections and so on --
with 4 blank lines above the section header
and 2 blank lines below the section header.

you can alternatively put hash-marks at the
beginning of a header preceded by a space
in the first column. an h2 header will have
two hash-marks, an h3 header three, etc.
you are only allowed to have one h1 header,
the title, and it is defined as the first chunk,
so you needn't use a 1-hash-mark indicator.

every section must have at least one header,
but it can also have two headers, if you like,
such as "chapter 1" and "in the beginning".
separate the two headers with 1 blank line.
and again, the header must be followed by
two blank lines, to separate it from the body.

the first section in the book is the cover/title.
the book's title comes first, the the subtitle(s),
then the author-name. after that, you should
include anything you consider of importance.

the second section is the table of contents.
this is required, so readers know where it is,
and know that it's in a very convenient place.
a table of contents will be auto-created and
injected as the second section of your book
if you do not already have a table of contents
as your second section. the table of contents
in an e-book should always have its items be
linked to the appropriate spots in the book, so
jaguar creates such links for you automatically.




 chapter 3

 text styling in your book


italicized words are indicated with underbars,
one at the beginning and another at the end.
the beginning one _must_ have white-space
to its left; likewise, the closing one _must_
have white-space to its right. in a phrase,
each word must have its own underscores.

this word will be in _italics._

this phrase _will_ _be_ _in_ _italics._

*bold* words are indicated with asterisks,
subject to the same rules on white-space.

this word will be in *bold.*

this phrase *will* *be* *bold.*




 chapter 4

 poetry and other silly things


use a space in the first column to get centered lines.

 t.v. will eat you
 (a haiku by bowerbird intelligentleman)

 t.v. will eat you
 out of a satellite dish
 with a tuning fork

use multiple spaces (5 or more, in a consistent number)
to get a chunk that is both left-justified and indented.

               a haiku for you
               (by bowerbird intelligentleman)

               haiku have three lines
               and seventeen syllables
               five, seven, and five

you can vary the spacing, as some poems like to do.

      six spaces at the start of this line
            12 spaces at the start of this line
      six spaces at the start of this line
            12 spaces at the start of this line
      six spaces at the start of this line
            12 spaces at the start of this line
      six spaces at the start of this line
            12 spaces at the start of this line

you can even get downright fweaky!

      six spaces at the start of this line
          ten spaces at the start of this line
              14 spaces at the start of this line
                  18 spaces at the start of this line
                      22 spaces at the start of this line
                  18 spaces at the start of this line
              14 spaces at the start of this line
          ten spaces at the start of this line
      six spaces at the start of this line

sometimes you want to set off an element
by giving it a different form of justification,
and jaguar makes it easy for you to do that.

 the input for the 2 chunks that follow has
 a space in the first column of all of the lines.

 you know about a space in the first column.

 a space in the first column will center a line,
 or -- applied to each line in a group of lines --
 will end up centering the entire block of lines.

  this chunk, and the next chunk as well, has
  two spaces at the beginning of each line.

  if you want to explicitly declare a block as
  left-justified, start it with _two_ _spaces..._
  this puts it at the left margin, with no indent.

   this chunk, and the next chunk as well, has
   three spaces at the beginning of each line.

   as reported above, a space in the first column
   will center a line. however, it is also the case
   that _three_ _spaces_ at the start of a line will
   cause that line to be centered.

    this chunk, and the next chunk as well, has
    four spaces at the beginning of each line.

    and, to fill out the left-center-right concept,
    4 spaces at the start of a line will cause it to
    be right-justified.

 so, to review, 1 space = centered
  2 spaces = left-justified
   3 spaces = centered
    4 spaces = right-justified

note also that you can use this convention inside
a paragraph, so if you want an interior line there
 such as this one, for instance
to be centered, just put it on its own line and
put a space in its first column to get that effect.
jaguar will precede it and follow this special line
with a hard-linebreak (or, in .html, the "br" tag),
so that is a way that you can _force_ _a_ _linebreak,_
and over-rule html's philosophical desire to wrap.

and, of course, the other types of justification
    like using 4 spaces for right-justification
will work as well. so if you want to center a line
   just precede it with 3 spaces at the start,
or, when you want a left-justified line to appear
in the middle of an otherwise fully-justified line,
 you will just put 2 spaces at its beginning,
and voila, that will give you the effect you want.
note that this is a good way to highlight a u.r.l.
 > http://gutenberg.org
that is located in the middle of a paragraph.




 chapter 5

 images in your book


to include an image in your book, just enter its u.r.l.

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

"what is the
use of a book,"
thought alice,
"without pictures
or conversation?"

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


you can put a caption on your image if you like,
above it, or below it, or even _one_ _of_ _each._


 here's a caption placed above a picture
 http://z-m-l.com/go/alice/checking_watch.png


 http://z-m-l.com/go/alice/checking_watch.png
 here's a caption placed below a picture


 and here's a caption placed above a picture...
 http://z-m-l.com/go/alice/checking_watch.png
 with another caption placed below the picture


and, using the methodology discussed above,
you can even insert a picture _inside_
https://dl.dropboxusercontent.com/u/26394889/hellobone.jpg
a paragraph, if you must, but you should
be aware that this will cause some funkiness
in some e-book viewer-apps, so you shouldn't
try to get too fancy. in general, it will be best
if you set off pictures, either above or below
the text that refers to them, for best results.


and, of course, the justification techniques that
we just discussed in chapter 4 can also be used
to set the "float" characteristic for your images.


to center an image, precede its u.r.l. with 1 space:

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


to "float" the image to the left, use 2 spaces:

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


to center an image, precede its u.r.l. with 3 spaces:

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


and to "float" it to the right, you'd use 4 spaces:

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


notice that when you use a single space, the image
will "expand" to fill the available width and/or height
of the screen which is currently being used to view it.
in most cases, that's exactly what your readers want,
so that is the recommended way of proceeding here.

on the other hand, using the 2/3/4 spaces method
means the image will get shown at its original size.

when you use the 2/3/4 spaces option for a picture,
text might -- or might not -- be "floated" around it,
but you shouldn't count on that, because it simply
won't be possible on some screens, and can cause
undesirable effects even on large-enough screens.




 chapter 6

 linking in your book


remember how, in chapter 2, we said
that the table of contents should be
hot-linked to the appropriate spots?
so jaguar creates them automatically.

similarly, there are often places in a book
that reference other chapters in the book.
in these cases, it's nice to have a hotlink
that transports the reader to the chapter
that is being referenced; it is convenient.

so jaguar automates those links for you,
too. just use the header (or subheader)
of the gourd, and jaguar will auto-link it.

for instance, the beginning of this chapter
has a reference to chapter 2. if a reader
clicked on those words -- "chapter 2" --
they will automatically go to chapter 2.
(and likewise with each of the references
to "chapter 2" here in this paragraph too.)

such internal links are one type needed,
but you also might want _external_ links,
ones that will jump out to some webpage.

to make an external link, just list the u.r.l.

 http://gutenberg.org

jaguar will create that link automatically.

a core element of the jaguar philosophy
is that a book's elements be transparent,
so there is no way to "hide" a link behind
some text. the u.r.l. must be fully exposed.

however, if the u.r.l. would be too bulky to
include there, you _can_ put it in a footnote.

i get 10 times more traffic from Google[g]
than from yahoo[y] and microsoft-bing[m] combined.

[g] http://google.com

[y] http://search.yahoo.com

[m] http://bing.com




 chapter 7

 multi-purpose block-quotes


you can get a blockquote like this.

 : 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[1] are created equal.

or like this:

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

you should note that the first method
(using the colon) rewraps the lines, and
the second (using the right-angle-bracket)
does not rewrap the lines. so use the one
which meets your needs better in each case.




 chapter 8

 footnotes and endnotes


your book can have footnotes.[3]

for a footnote, place the footnote-referent in
square brackets.[3a]

note that there must be _no_ white-space
to the left of the referent, but that there
_must_ be whitespace to the right of it.

this is just a dummy paragraph,
to get some separation between
the footnote referent up above
and the actual footnote below,
so you can see the jump when
you click between the two of them.

this is another dummy paragraph,
to get some separation between
the footnote referent up above
and the actual footnote below,
so you can see the jump when
you click between the two of them.

this is a third dummy paragraph,
to get some separation between
the footnote referent up above
and the actual footnote below,
so you can see the jump when
you click between the two of them.

and a fourth dummy paragraph,
to get some separation between
the footnote referent up above
and the actual footnote below,
so you can see the jump when
you click between the two of them.

here's dummy paragraph #5,
to get some separation between
the footnote referent up above
and the actual footnote below,
so you can see the jump when
you click between the two of them.

this is a sixth dummy paragraph,
to get some separation between
the footnote referent up above
and the actual footnote below,
so you can see the jump when
you click between the two of them.

and the seventh dummy paragraph,
to get some separation between
the footnote referent up above
and the actual footnote below,
so you can see the jump when
you click between the two of them.

here's dummy paragraph #8,
to get some separation between
the footnote referent up above
and the actual footnote below,
so you can see the jump when
you click between the two of them.

i hope 9 dummy paragraphs is enough
to get some separation between
the footnote referent up above
and the actual footnote below,
so you can see the jump when
you click between the two of them.[4]

[3] you can put the footnote right underneath
the paragraph which contains it, or at the end
of the chapter containing it, or in a section at
the end of the book with all the other footnotes.




 chapter 9

 lists in your book


you can use '' * '' at the beginning of a gourd
to make a list, an "unordered" list" that has
the usual circular bullet-point as its marker.

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

as you can see in this example, every item
must be prefaced with the same character
as the first one. and, in this example here,
the first item is _blank,_ which means that
this list will have some spacing at the top,
which serves to separate it from whatever
chunk appeared right before it. if you want
the list to snuggle with what came before,
you would eliminate that empty first item.

 ***

you can also use '' o '' for a list, a tag that
will use an _unfilled_ _bullet_ as its marker.

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

this list has an empty item at the end of it,
which means it will be separated from the
chunk that _follows_ it, i.e., this paragraph.

 ***

you can also use '' + '' for a list you want
to be indented one level, and which uses
a filled square marker as its bullet-point.

 + some
 + where
 + over
 + the
 + rainbow
 + blue
 + birds
 + fly.

 ***

and you can also use '' - '' to make a list,
one that gets indented _two_ levels and
uses the unfilled bullet as its marker.

 - mary's
 - violet
 - eyes
 - made
 - johnny
 - stay
 - up
 - nights.
 - period.

 ***

as you might imagine, you can combine
these indented lists for a multi-level list.

 * this is the first point at the first level
 + this item is at the second level
 + this item is also at the second level
 - now we've moved to the third level
 - one more at the third level
 * now we're back at the very first level
 * again, another point at the top level
 + here's an item at the second level
 + and another item at that level
 + and yet another item at that level
 - out to the third level.
 - and out to the third level again.

 ***

you can also use '' = '' to create a list;
a tag with an unfilled circle as its bullet.

 = the
 = equals
 = sign
 = uses
 = a
 = solid
 = square
 = as
 = its
 = bullet.

 ***

finally, you can use '' x '' to make a list.

 x the
 x letter
 x "x"
 x makes
 x an
 x "x"
 x with
 x no
 x bullet.

the '' x '' prefix has _no_ bullet at all.
as we will now see, that has benefits.

 ***

sometimes you want a numbered list...

here's an example of an unordered list
that masquerades as a numbered list,
with the number specifically included,
thanks to its use of the '' x '' tag.

 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,
but we mix things up a bit, to show
how to do non-sequential numbers.

 x 101. one
 x 202. two
 x 3. 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...

that example seems kind of silly, yes,
but there are many meaningful ones.

 x 9800bc -- north america gets inhabited
 x 1492 -- columbus "discovers" america
 x 1620 -- pilgrams land on plymouth rock
 x 1622 -- "indians" feed starving pilgrims
 x 1809 -- white men start "indian" genoicide
 x 1964 -- civil rights act passes congress

 ***

and finally, another numbered list, except
this time it's a plain html ordered list,
so the browser does the numbering.  for this,
the tag is a '' # '' hash (a.k.a., a number sign).

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




 chapter 10

 epigraphs and epitaphs


    _there's_ _an_ _old_ _proverb_
    _that_ _says_ _just_ _about_
    _whatever_ _you_ _want_ _it_ _to..._
    _--_ _slashdot_

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.[5]




 chapter 11

 tables in your book


you can have tables in your book, simple ones.
just use multiple-spaces to separate the cells.

 | table 1         column 1   column 2
 | plain-text    yes            yes
 | x.m.l.           no             yes
 | html             yes            no
 | .rtf              no                yes
 | .pdf          no            no

 ***

you can also use or-bars to separate the cells.

 | table 1 | column 1 | column 2
 | plain-text | yes | yes
 | x.m.l. | no | yes
 | html | yes | no
 | .rtf  | no | yes
 | .pdf  | no | no


 ***

you can even combine these two approaches,
but understand that or-bars take precedence.

 |      table 1        |        column 1  |      column 2
 |    plain-text    |        yes          |  maybe
 |    x.m.l. |                   no |                     yes
 |    html                     | yes |                     no
 |    .rtf  |                 no                  |   yes
 |    .pdf            |                no         |         no




 chapter 12

 the play is the thing


jaguar auto-bolds the first word of a paragraph
if it is followed with a colon. this is handy
when you are doing the dialog for a play.

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

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

dale: that's your opinion.

bowerbird: yes it is.

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

dale: no it isn't.

steve: (weakly) get a...

bowerbird: is too.

steve: (weakly) word in edgewise...

dale: is not.

lurkers: will you two cut it out?

bowerbird: is so.

dale: is not...

fade to black.[6]




 chapter 13

 unlucky number 13


there is no 13th floor in most buildings.




 chapter 14

 hyphens and dashes


use a double-dash -- like these here -- to get
an em-dash in your .html output. it's best to
put spaces around your double-dashes, or else
they can sometimes cause word-wrap problems...

don't use a single-dash - like this bad example -
where you want an em-dash, or it will look _bad._

even http://medium.com and http://kottke.org
make that mistake. it's rather embarrassing, eh?




 chapter 15

 hyphenation stinks


do not hyphenate your text. e-books don't need it.
and you never know exactly how the text will reflow.




 chapter 16

 two spaces after a sentence


many typesetters set a little bit of extra space
between sentences, so the separation is clear.
i support that, as i think it makes it look nicer.

now some people try to get this nicer look via
the old typewriter-trick of putting 2 spaces at
the end of a sentence. but that doesn't work
when the text is turned to .html. and further,
the extra spaces mess with our editing process,
where we often search the text for 2-spaces,
just to make sure we haven't inadvertently
introduced extra spaces in unwanted places.

so the best tactic to use these days is to put
only one space after a sentence, and _hope_
browsers will soon support better typography.




 chapter 17

 preformatted text and code


sometimes you might have a need to present
preformatted text, or computer-language code.

for these situations, you will use the ` backtick.

inside a paragraph, or some other element,
the `backtick` acts just like the italics `_`
and bold `*` markers. it will serve to have
the text that it surrounds displayed in the
`preformatted` .html tag -- which is `pre.`

however, the backtick can also be used as
a block tag, to signal that an entire chunk
should be shown using the html "code" tag.

while the '' ` '' can be used to start each line,
that would cause the code in the input file to
be "polluted" with these backticks, so it'll be
best to start the chunk with an empty tag:

 `
// the backtick code in the line above
// signifies this chunk is source-code,
// to be shown with .html's "code" tag,
// i.e., monospaced and preformatted.
 <script type="text/javascript">
    $(document).ready(function () {
       gdi=setInterval(function(){doit()},1000)
    })
 </script>
// this is known in light-markup circles as
// "a fenced block", since the backtick(s)
// up top sets a "fence" around the code.
// the code block is then usually followed
// by a closing "fence" of backtick(s), but
// in z.m.l., a blank line closes all elements,
// so we don't need a "closing" fence here.
// however, this does mean that the code
// cannot contain any blank lines inside it,
// so you must stay cognizant of that fact.
// comment out blank lines in your code.

be aware that you can also add a note to
the opening backtick tag that describes
what the code does, the language, etc.

 ` // javascript document.ready function
 <script type="text/javascript">
    $(document).ready(function () {
       gdi=setInterval(function(){doit()},1000)
    })
 </script>




 chapter 18

 the notes section


[1] in later years, it was made clear that
lincoln was referring to all "people", and
not just men, that women are equally equal.

[2] again, in later years, it was made clear
lincoln was referring to all "people", and
not just men, that women are equally equal.

[3a] 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.

[4] 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.

[5] this is another test footnote. but it will be short.

[6] you probably shouldn't mix footnotes and endnotes,
like i have done in this book, because that'll just make it
confusing for your readers. so choose one or the other.




 chapter 19

 meta-data for this book


here's the meta-data...

 o title = a brief introduction to z.m.l.
 o author = bowerbird intelligentleman
 o purpose = a brief introduction to z.m.l.
 o markup = zen markup language (.zml)
 o isbn = urn:isbn:0000000000000
 o publisher = jaguar(ps)
 o subject = a brief introduction to z.m.l.
 o rights = copyright 2013 -- all rights reserved