<-    -c-    ->    

chapter 1

the "chunk" is the basic unit

"zen markup language" -- z.m.l. for short -- is a system of "light-markup". as such, it is a means by which the "structural elements" of a long-form document can be indicated, so that each element is treated "correctly", whatever that means in various situations.

many structural elements of long-form texts are well-known to people, and certainly the most familiar one is the humble "paragraph", a group of sentences related to each other, gathered together in support of their topic.

a second common element is the "header", such as a chapter-title, big and bold and centered, and often starting on a new page.

indeed, there are many books which consist of little more than headers and paragraphs, once you pass a smattering of front-matter.

in order for a system to know how to treat a header or a paragraph "correctly", it must first know what that specific element is, so we need to a way to inform the system "this is a header" and "this is a paragraph".

z.m.l. -- zen markup language -- analyzes a text-file to prepare it for published output by first splitting it into its "sections", which would be chapters, for instance, in a novel.

then each section is split into "paragraphs", to use this term that we're all familiar with.

but there are several different kinds of basic underlying structural elements that can be grouped under a "paragraphs" label, as we'll see, so z.m.l. calls them "chunks", to have an unambiguous descriptive term for the basic building-block of long-form.

"chunk" is thus the word we use generically, to refer to every single element in our text.

"chunk" is one of the few cases of jargon that we will use, but we'll use it a lot, so you will need to feel comfortable with it.

the thing you must know about chunks is that a "chunk" is defined as any non-blank line(s) with a blank line above and below.

every word in your book is in a chunk, separated from its neighboring chunks by a blank line, and all chunks are numbered, from the first one in the file -- the title -- to the last, holding the last word in the file.

each header is a chunk, and each paragraph, and every type of element in the entire book.

we use a blank line to separate the chunks.

ergo, use a blank line between paragraphs.

while you're writing, put a blank line above each paragraph, and a blank line below it. (yes, the blank line "below" one paragraph doubles as the blank line "above" the next.)

that might be something you already do, putting a blank-line between paragraphs, but if not, a global find-and-replace to turn one return into two will do the trick.

also, if you're helping, or considering it, do not indent the first line of paragraphs with spaces. and especially not with tabs. (it is probably best not to use tabs at all.)

a first-line indent option is something that gets handled by the system automatically, not something to fret about when writing.

***

there are "special" types of paragraphs, which we will need to differentiate later, and other elements besides paragraphs, which we'll discuss then too, but for now, remember that "chunk" is our basic unit.

it's easy to understand, easy to recognize.

(it's also extremely easy to write code for. as a quick side-bar for any programmers, you will separate a z.m.l. file into chunks by simply splitting the text on blank lines; that is, you split on a pair of line-breaks. now we return to regular-person readers.)