the 11 rules of z.m.l. zen markup language! by bowerbird intelligentleman z.m.l. is a "markup language" that has zero markup in it. it is zen. it allows you to use common plain-text conventions to make e-books that are _very_ _powerful_ when viewed with a z.m.l.-capable viewer and which _look_ _nice_ when displayed on-screen and/or when printed, all without spending lots of valuable time and energy doing "markup". table of contents the 11 rules of z.m.l. table of contents z.m.l. rule #1 -- headers and structure z.m.l. rule #2 -- styling the text z.m.l. rule #3 -- character-set and encodings z.m.l. rule #4 -- formatting blocks z.m.l. rule #5 -- multimedia and external files z.m.l. rule #6 -- footnotes and other links z.m.l. rule #7 -- lists z.m.l. rule #8 -- um... z.m.l. rule #9 -- reserved for future use z.m.l. rule #10 -- special publications z.m.l. rule #11 -- i can't think of any more notes z.m.l. rule #1 headers and structure 1a. paragraphs. paragraphs must be separated by 1 blank line. paragraphs should not be indented. (that's an option for the user.) 1b. transitions. use 2 blank lines between two paragraphs to indicate that a "transition" of some sort occurred between them. 1c. long transitions. for a _long_ transition, use 3 blank lines. 1d. sections. sections must be preceded by 4 or more blank lines and followed by 2 blank lines, with up to 3 lines composing the header. the _number_ of preceding blank lines indicates the section's priority; more blank lines indicate a higher priority, i.e., a more major section. if no header is present, the first line of a section is treated as such. z.m.l. rule #2 styling the text 2a. italics. use _surrounding_ _underlines_ to indicate italics. if you are only emphasizing _one_ word, they go before and after. if you're emphasizing _a_ _string_ _of_ _words,_ place the underbars before and after, and use one to _replace_ _each_ _space_ in the string. if you have linebreaks in your text, _the_ _surrounding_ _underbars_ _should_ _be_ _ended_ _at_ _each_ _linebreak_ _and_ _then_ _start_ _anew_ _again_ _at_ _the_ _beginning_ _of_ _the_ _next_ _line._ 2b. bold. use *surrounding* *asterisks* to indicate bold. you should note that headers should _not_ be indicated as bold. (it's up to the end-user to decide how the headers are displayed.) 2c. bold italics. use /surrounding/slashes/ for bold italics. 2d. other emphasis. you can specify other types of emphasis. ~any~ non-numeric from the top row of a qwerty-keyboard can be used to indicate such a different manner of emphasis; use it to ~surround~the~word~or~phrase~ in the usual way. you should inform the person reading your text at the outset what this special emphasis is intended to convey to them. (note: this next part is the one where the rule isn't concrete yet.) then, so the zml-viewer-program displays it as you would like, you should also put the display instructions with the character. for example, let's say that, for the tilda character used above, you wanted the zml-viewer-program to display it in green italics; the first or last tilda in your text should be around ~green~italics~. (a set of terms that the viewer-app recognizes will be formulated.) z.m.l. rule #3 character-set and encodings if your book requires non-ascii characters -- i.e., characters above the lower-127 -- use unicode. if your book works without it, as most english text does, don't think about it, just consider yourself _lucky_ and be _happy._ if your book is in english, and you are using some words that we've borrowed from other languages that have accents -- such as "cafe" or "vis a vis", and so on -- you can just leave the accents out, as we know what those words are and what they mean, even when they are displayed without their accents. use regular quotes, not the fancy high-bit curly-quotes. (if a user wants curly-quotes, there's an option for 'em.) use a double-dash (like this: "--") not the high-bit em-dash. (that's another option the end-user can choose if they want.) in general, use only low-bit characters, not high-bit ones. z.m.l. rule #4 formatting blocks after the empty calories of unicode, this rule is a _feast._ :+) so go right ahead and sink your teeth into this one, folks!... 4a. indents. z.m.l. makes it very easy to indent a line. to do so, just use leading spaces, as many as you want. 4b. centering. sometimes you want to center a line of text. or right-justify it. think of the line as existing in three pieces, each preceded, separated, and terminated with a ~tab~ character, that will be left-justified, centered, and right-justified. thus, ~tab~ left-justified ~tab~ centered ~tab~ right-justified ~tab~ you don't need all 3 elements if you don't want, obviously, so if you only wanted to center the line, you would do this: ~tab~~tab~ this is the text to be centered. ~tab~~tab~ to right-justify a set of lines, such as an epigram, you'd use: ~tab~~tab~~tab~ each of these two lines will be ~tab~ ~tab~~tab~~tab~ right-justified. ~tab~ 4c. tables. z.m.l. can also support simple one-level tables. you can prepare such tables in a monospaced font, making sure that every line in the table has the same number of characters. z.m.l. will recognize this, and present the table appropriately. or, if you prefer -- and this is recommended -- you can use tabs. using this method, just separate each column of the line with tabs; there's no requirement that lines have equal numbers of characters. the z.m.l. viewer will automatically format your table on-the-fly so that it fits the user's particular window-size at display-time. this tab method will usually create tables that are better-looking. 4d. leading white-space and the rewrapping of lines. the common element in this rule is that lines have leading whitespace, in the form of a space or a tab. because such lines are pre-formatted, they should not be rewrapped, even when the user has requested that, so this leading white-space exempts a line from being rewrapped. this means you can use leading white-space to accomplish the purpose of preventing line (or, more often, a set of lines) from being rewrapped. let's say you have an address block, and don't want it to be rewrapped. you would just use leading spaces (one will do) to signal that fact. michael hart founder and visionary, project gutenberg 10,000+ free e-books, available right now http://www.gutenberg.net hart@pglaf.org the presence of one-and-only-one space at the start of a line has a special meaning to the z.m.l. viewer-program, namely that -- although you do _not_ want this block to be rewrapped -- you _do_ want it to appear flush with the left margin, and _not_ indented one space, as one might reasonably assume. (yes, this means there's no way possible to indent a line one space; sorry about that, you'll just have to live with that limitation.) :+) 4e. leading white-space and its effect on pagination. when a number of consecutive lines have leading white-space, the z.m.l. viewer-program recognizes them as a unit, or block, and will make some small accommodations to keep the unit _as_ a block, and thus attempt to keep it together on one page. if it is too difficult to keep the entire unit on a single screen, the program will attempt to place the pagebreak appropriately, preferably on a blank line in the block. (this would, for instance, cause a poem to pagebreak between verses.) therefore, you can help the program by using blank lines generously in such a block. z.m.l. rule #5 multimedia and external files 5a. pictures. to have a picture displayed near a line of text, all you need to do is name the picture using a string of that text, with the spaces removed. the extension of the file doesn't count. whenever that line of text is displayed on a page, the viewer-app will display the picture (or a thumbnail of it) on the page as well. if the user clicks on the picture (or the thumbnail), a workspace will open up and the picture will be displayed in that workspace. allowing the user to deal with the picture in a number of ways (e.g., zoom it, rotate it, save it in another format, and so on...). 5b. movies. to show a quicktime movie near a line of text, just name the quicktime movie using the same convention as above. (it is anticipated that .swf files will also be supported rather soon, as well as any other file-format that can be played by quicktime.) 5c. sounds. to have a sound icon displayed near a line of text, which will -- when clicked -- play an associated sound-file, all you need to do is name the file using this same convention. 5d. other external files. to "activate" an external file whenever a line of your text is encountered, all you need to do is to name the external file using the convention detailed here. initially, the only such external files that'll be supported will be .text and .rtf files, which will be brought up in a scrolling-field, but requests for support for other types are happily entertained. z.m.l. rule #6 footnotes and other links 6a. footnotes. z.m.l. handles footnotes just fine. use brackets in the text to indicate a footnote. [1] there must be a space before the opening-bracket. the text of the note should be placed in a section at the end of the document, where it should begin at the start of a line, and contain the exact same string-in-brackets as the indicator in the text. the string itself does _not_ have to be a number; it can be anything you want. [x] for now, however, there cannot be a space inside of the footnote indicator. whenever a footnote indicator occurs on a page, the footnote is placed at the bottom of the page. if the entire footnote will not fit at the bottom, an icon is presented which -- when clicked -- opens up the "workspace" and presents the text of the entire footnote _there,_ along with the text of the other footnotes, in a scrolling-field that allows the user to view all of them together. when the user gets to the section that contains all the footnotes collected together -- which is therefore essentially an _end-note_ section -- the _reverse_ of the process is put into play, so a click on a note's text shows, in the workspace, a scrolling-field that displays the text in the body of the book where the footnote indicator is placed. 6b. external links. one of the exciting things that turned people on to the web was the ability to click on "links" to jump to another place entirely; this _was_ the experience of "surfing the web". so one of the things that readers now _expect_ from an e-book, even though "surfing" often isn't all that _congruent_ with the reading of a book, is this ability to hotlink to an internet web-page. so of course z.m.l. supports this type of linking, and does it with a method making it very simple: to link to a web-page, just put its u.r.l. in the text. for example, http://www.gutenberg.net would be an automatic link to the project gutenberg website. you can also put a full u.r.l. in a footnote, and the footnote indicator automatically becomes a link. 6c. "internal" links. the z.m.l. viewer creates a rich set of "internal" links in the book, automatically, which serve to help the reader _navigate_ the e-book. specifically, each _section_ _header_ is a link "target", such that any place in the text with the same text as a section header automatically _links_ to that header. so, for instance, if you have a "chapter 6" section -- i.e., a section with a first line of "chapter 6" -- any place where the phrase "chapter 6" appears _automatically_ becomes a _link_ to that section; if the user clicks it, they'll be taken to chapter 6. for a 2-part header -- where the parts are separated by a double-dash -- _either_ part becomes a hot-link. this can make a very nifty e-book, chock-full of links. sometimes it _can_ become overzealous, too, such as when you have a section that is labeled "introduction", in which case unrelated uses of the word "introduction" would become links, which is not what you really want (even if it doesn't _hurt_ anything, either, not really.) still, keep this in mind when you make your headers. with creativity, you can make it work like you want. (these hotlinks _are_ case-sensitive, which helps to minimize the occurrences of such "mistaken identity".) but used strategically, these automatic internal links can help you create a _tremendously_ powerful e-book. z.m.l. rule #7 lists z.m.l. can handle lists, and makes them simple for you too. sure, lists aren't that common in classic literature, but there are still a good number of them sprinkled in the e-texts. the two types of lists with which most people are familiar are (a) bullet lists and (b) numbered lists. unlike markup languages, z.m.l. won't number your lists for you automatically, you have to do it yourself. sorry about that. shouldn't be that much trouble. just make your lists in the typical manner, and the z.m.l.-viewer should recognize them just fine, and treat them appropriately. for example, it will recognize the list as a "block" and thus strive to avoid placing a pagebreak right in the middle of it. it also will retain the linebreaks of the list, and not rewrap it. this is the case even if the lines of the list do not contain leading whitespace, so there's no need for such whitespace. (i might change this down the line if it causes complications.) you can use any of the non-numeric characters on the top row of a qwerty-keyboard as your "bullet" character in a bullet list. the only thing you must do is leave a space after the character. the list items will then be indented from the bullet character, and any continuation-lines will also receive that indentation. in general, you should not place blank lines between the lines in a list, not unless there are just a few such lines, because that increases the chance the list will over-run the pagesize. and when there _is_ room on the page, the viewer-app will space out the lines of a list, in order to enhance readability, so there's no need for blank lines between items to do that. if you use a _numbered_ list, the z.m.l. viewer-program will also indent continuation-lines of items contained in the list; and if the numbering has _decimals,_ like a numbered outline -- in the style that is extremely common in tech manuals -- such as 1.1 and 1.11, they'll receive successive indentations, creating a very nice looking rendering, if i do say so myself. it should be noted that some of the things that you might not _think_ _of_ as _being_ lists are nonetheless _treated_ as such by the z.m.l.-viewer, such as a table of contents or illustrations. i guess i forgot to mention this back on rule #4, which discussed the other types of "units" or "blocks" -- such as block-quotes -- but these "units" are themselves placed into a menu of their own by the z.m.l.-viewer, so the user can easily jump right to them, just another way that the viewer-program helps the end-reader to "get a handle" on the _underlying_ _structure_ of the e-book and to navigate it easily. (footnotes _also_ go in that menu.) z.m.l. rule #8 um... um... i forget what 8 was for. z.m.l. rule #9 reserved for future use number nine, number nine: this rule intentionally left blank. z.m.l. rule #10 special publications (i should have thought to make the "lists" rule #10, in honor of david letterman and his "top 10 lists". and then i could have made this "specials" rule #7 instead, because 7 is a special number. oh well...) :+) 10a. plays. the lines of the characters in a play will be formatted distinctively _if_ the character's name (a) starts a paragraph and is followed by (b) a colon and then a tab, and then their dialog. there can be no spaces or tabs _in_ the character's name; you must replace them with underbars or some other filler. a character must have a (to-be-decided) minimal number of lines before they are given any distinctive treatment. the nature of the distinctive treatment is up to the reader. 10b. "narrator" indication. the lines of a "narrator" will be given distinctive treatment if formatted as described. a narrator's dialog is often not indicated with a name per se; to get this effect, just start such paragraphs with a colon. 10c. f.a.q., or question-and-answer sections. format a question-and-answer sequence in the same way as described for a play (i.e., as if the "question" lines were uttered by one character, and the "answer" lines by another) and they too will each be formatted distinctively. 10d. definition lists. for definition lists, treat the terms and their definitions as if they were two characters in a play, and format them in the manner described above. 10e. folder-exposition. you can create an e-book that automatically consists of all of the files in a folder, arranged alphabetically by name, with a one-line text-file that says "folder-exposition". note that such an e-book will be a dynamic entity on the end-user's machine, in that any files they add to the folder become part of the e-book. 10f. "tours". the zml-viewer keeps the "history" of the pages that you visit during your session in a listbox, which you can summon and use to return to any of the pages. you can also _save_ the list of pages in the history listbox as a plain-text file, and that file can subsequently be loaded into the zml-viewer again, to be followed in _that_ session. (as a plain-text file, this "tour" file can be edited easily, in case your traversal wasn't exactly as you wanted it; in general, you should only _delete_ lines from the file, though, since adding incorrect entries causes problems.) 10g. special sections particular to books. there are some types of sections that are common to books. if you use a header-line for a section from the list below, the zml-viewer will format that section "appropriately". (in some cases, this means centering the text horizontally, and positioning it in the upper-third of the page vertically.) ~tab~title (so special it doesn't even need any blank lines) ~tab~frontispiece ~tab~dedication ~tab~a note from the author ~tab~acknowledgement ~tab~acknowledgements ~tab~forward ~tab~foreword ~tab~prolog ~tab~prologue ~tab~preface ~tab~author's note ~tab~epilog ~tab~epilogue ~tab~appendix ~tab~appendices ~tab~notes ~tab~footnotes ~tab~endnotes ~tab~metadata the items in the following list can actually head an _otherwise-empty_ _section,_ which will be filled automatically by the zml-viewer. for instance, if you use "contents" as the header of an empty section, the zml-viewer creates a table of contents to put there. ~tab~table of contents ~tab~contents ~tab~table of figures ~tab~figures ~tab~table of illustrations ~tab~illustrations ~tab~table of links ~tab~links ~tab~references z.m.l. rule #11 i can't think of any more honestly, i can't think of more. do i really need 11? well, anyway, if you can think of any other feature that you might need in an e-book you want to create, do give me a hollar, would ya? as i have some extra room for a rule to handle it, you just might get lucky... notes [1] here is the text of the footnote labeled as "1". [x] here is the text of the footnote that is labeled as "anything you want".