<-    -c-    ->    

chapter 2

chunks are stored in gourds

in a book, paragraphs join into "chapters".

and in a magazine, paragraphs compose "articles", which are grouped in "sections".

or -- depending on how you look at it -- "sections" will be combined into "articles".

both "chapters" and "articles" are examples of the types of "sections" we called the defining characteristic of long-form writing.

but "section" is an ambiguous term as well.

for instance, in a novel, it will be chapters, yes, but it'll also be the label for the index in the back, as well as the preface up front.

looking at some cookbook, it might refer to each recipe. alternatively, it can also mean the recipes collected in a "desserts section".

obviously, this could get to be confusing; thus we need an unambiguous word for it.

so we use the term "gourd" as our generic, broad equivalent for "chapter" or "section".

every separate section of a long-form text is called a "gourd". this includes things like the cover/title-page, the table of contents, the dedication, the footnotes, and all that.

so a novel might consist of many gourds, most (but not all) of which are chapters.

and each gourd is comprised of chunks, most (not all) of them being paragraphs.

so those are the two bits of jargon we use.

***

there are a couple things you have to know about gourds, and how you'll "mark" them.

the first thing to know about a gourd is it must have at least 5 blank lines above it.

this is how you tell z.m.l. that the chunks that follow are to be considered a gourd.

do not put 5 blank lines anywhere else, because z.m.l. will consider that to be a marker that you started a new gourd.

while there must be at least 5 blank lines, more than 5 is also fine, so please do not feel you must spend time counting lines. just repeatedly press "return" many times.

(i find, however, it is innocuous to count, out loud, and it's even strangely exciting, knowing you are starting a new chapter.)

***

the next thing you need to know is that the first chunk in a gourd is the header for that gourd; if you are writing a novel, a gourd's first chunk is the chapter title.

to repeat, the sequence of 5+ empty lines says "i'm starting a new section here", and the first non-empty line following it says, "i am the beginning of the header here."

a gourd can have a header with two parts: for instance, one part might be "chapter 1", while the second part is "in the beginning".

in such a case, you would put a blank line between the parts, since you want them to be recognized as independent chunks.

to indicate that the header is all finished -- and the body of the gourd will follow -- type in 2 blank lines below its last line.

***

the first gourd in the book is the cover/title. (in an e-book, the "cover" and "title page" are one and the same, unless you want to consider the icon of the file as its "cover".)

the book's title comes first, the initial chunk, followed immediately by subtitle(s), if any.

next comes the chunk naming the author. this chunk must begin with the word "by", the signal z.m.l. uses to discern the author.

after that, you'll include anything you consider to be of sufficient importance that it "belongs" on the cover/title; things like publication date, the web-page of the "view source" z.m.l. file, e-mail address for the author, and of course the u.r.l. for the image that's the book's cover.

the second gourd is the table of contents. this is required, so readers know where it is, and know that it's in a very convenient place, helping create a shared understanding of this.

a table of contents will be auto-created and injected as the second gourd of your book if you don't already have a table of contents as your second gourd. the table of contents in an e-book should always have every item linked to the relevant place in the book, so z.m.l. makes such links for you automatically.

***

the next gourds are "front-matter" you have, like a preface, introduction, prologue, etc.

though some front-matter pages, like the dedication, do not usually have a header in traditional printed-books, you will need to provide a header -- such as "dedication" -- so z.m.l.'s automatic links can be created.

also, it's important in an e-book, which has no "heft" to help inform a reader that they are at the "front" or "back" of the e-book, to provide some extra navigational hints to help the reader feel "oriented", and a header for each and every gourd serves that purpose.

***

and after the front-matter gourds, of course, you will begin on the regular chapter gourds. and after them, you'll have the "back-matter", things like the index, footnotes, references, colophon, note on other books by the author, "thanks for reading", and all of that claptrap.

***

i shouldn't need to tell you programmers, in a quick side-bar to this chapter, that you can divide a z.m.l. file into an array of its gourds by simply splitting on a set of 6 line-breaks, because you'll have already figured that out. but let me point out that you could also just use the array of chunks that you split earlier, because every sequence of 2 empty chunks represents the start of the next gourd. nifty! because, you see, z.m.l. has been specially designed, by a programmer, to be nice for programmers, in addition to regular people.