beyond markdown

bowerbird Blocked Unblock Follow Following Oct 2, 2014

— part 5

shining a spotlight on sections and headers

this is part 5 of an ongoing series. you can find

a list of links at the bottom of the article which

will direct you to the other parts of the series…

***

ok, this piece got a lot longer than i intended,

so let me give you a “tl;dr” option on this one.

the topic is headers, .html tags “h1" through “h6".

markdown’s example of headers goes like so:

markdown header input:

http://zenmagiclove.com/simple/markdown-input-headers.png

i’ll ignore the other ways markdown can do headers,

underlying with equal-signs and dashes. too obtrusive.

markdown header input and output from the dingus:

http://zenmagiclove.com/simple/markdown-dingus-headers.png

***

pretty hard to beat that for input simplicity, right?

just start a line with some hashmarks. that’s easy.

and you get “headers”, big and bold, as expected.

and sure enough, put the same text in z.m.l. and

you will get back similar “headers”, big and bold.

markdown headers take 1 minute to learn because

they are 1 minute deep. and z.m.l. headers can be

1 minute deep, if you want. or they can go deeper.

so if you want the 1-minute version, there you go.

we’ll consider the two to be “the same”. for now.

so, if you’re too busy for the whole story, which is

quite a bit more complicated, and more interesting,

you can leave now. ok, so much for the tl;dr version.

***

ok, demo examples are often “unrealistic”, so

this wouldn’t necessarily be a criticism per se,

but surely we agree this one _is_ “unrealistic”;

you don’t often see a set of 3 headers in a row,

each one containing no content underneath it.

(some cheat-sheets actually list all _6_ levels!,

in a very compelling example of input/output

that you will never ever see in the real world.)

what you usually see is a header announcing a

section of some type, with its content below;

a header without any section below it is weird.

what i am driving at is this: if your idea of what

defines a “header” is “a line that’s big and bold”

— via having the requested markup of h1 to h6,

while having no regard for the section below —

then know that z.m.l. offers you the same thing.

and you can also stop reading shortly after this.

but if that’s really what your idea of a “header” is,

then maybe you should just stay with markdown.

because headers — or, more precisely, sections —

are one of the most important concepts in z.m.l.

zen markup language is not a mindless converter

changing shorthand to .html in a reductionist way.

it’s a document-processor that encapsulates a text

in a holistic sum-is-greater-than-the-parts manner.

so, my friends, if your idea of a “header” involves

something more “semantic” than “big bold line”,

more like labeling the meaning and/or the content

of a section in a document, then you might wanna

settle in and read this entire piece at your leisure.

***

which, aside, reminds me that i really appreciate

the great response you’ve shown for this series!

lots of you are viewing it, and even reading the

entire pieces, at least according to medium.com.

even “part 4" — which weighed in at 18 minutes!

and let’s face the facts, folks, you’re essentially

reading the _manual_ for zen markup language,

and we all know how rare it is to read a manual.

(most of all, we few who typically actually _do_!)

i know that i didn’t really expect you to read it.

first, it’s kind of boring, and second, i’m really

terrible at writing this type of stuff, so sorry.

explaining stuff brings out my over-explainer,

and he can bore anybody, most especially me.

i was just writing this up so i could point to it,

if people ever started asking me any questions.

the old “i’m-not-your-mama, r.t.f.m.” brush-off.

i didn’t expect people to show any real interest

until i gave you all a real z.m.l. authoring-tool,

so you could fiddle around with it and see that,

hey, it really is very simple, and it really works,

and it really could be something that replaces

inconsistent markdown with a reliable format,

and it really does give writers a real advantage,

and i’m gonna start using it and telling people.

really.

and i still expect that all of that _will_ happen,

when i give you the authoring-tools — soon! —

but i’m pleasantly surprised at the interest that

you have _already_ shown, so thank you kindly.

oh, and in case you’re wondering, most of the

tools that i offer will be absolutely free of cost.

those tools run the full range, web and native,

cross-platform, and ported to many languages.

(so coders, resist the urge, because you’ll just

be reinventing the wheel now, when later you

can help make the wheels work even better.)

i might have to charge a small amount to offer

stuff out of the apple stores, because you must

pay apple their fee to be “an official developer”,

but in general i pledge most of this will be free.

ok, now “part 5". i know you’re so excited! ;+)

***

the series is discussing “zen markup language”

— “z.m.l.” — which is a light-markup solution.

it is thus very similar to “markdown”. however,

z.m.l. was designed independently of markdown

(and i started it several years before markdown,

even before “textile”, markdown’s inspiration),

so z.m.l. avoids some of the flaws in markdown

— ergo the “beyond markdown” series title —

although you might find they are more similar

than dissimilar; but one of the features where

they diverge in important ways is _“headers”._

headers, of course, are extremely important,

as they cordon off _sections_ in the document,

such as the _chapters_ of a novel, for instance,

individual _pieces_ in an anthology, and so on.

and because z.m.l. goes the most simple route,

it considers the _header_ for any section to be

the first chunk which is found in that section.

or, to say it another way, the first chunk found

in a section is ruled to be that section’s header.

so how does z.m.l. decide it has “a new section”?

well, easy.

just like one blank line signals “a new chunk”,

whether that chunk is a “paragraph” or a “block”,

a set of 5 blank lines signals “a new section”…

just like one blank line

signals “a new chunk”,

a set of 5 blank lines

signals “a new section”

and, since i have just said that the first chunk

in a section is defined as that section’s header,

we come to the startling realization that there

is actually no need to even _mark_ that header,

because the 5-blank-line sequence already did!

but now i’m getting way ahead of myself…

so let’s reel it back in, to start at the beginning.

and when we talk about sections, and headers,

then we should begin with the table of contents.

***

bow down to the table of contents

z.m.l. has a focus on long-form documents, like books,

reports, journal articles, etc. — documents of substance.

these types of documents usually make a large webpage,

or even a whole set of united webpages across a website.

markdown, on the other hand, is often used on things

such as blog comments (or the blog article itself), and

particularly user-generated content, where that text is

a little part of a webpage, or a relatively small webpage.

indeed, markdown is usually converted as a “snippet”;

you _add_ the .html elements, .css, etc., if you need ‘em.

not so with zen markup language.

z.m.l. always gets converted as a full webpage, or even a

set of related webpages, and you are expected to _delete_

the stuff that you don’t need for your specific use-case.

the .css, for instance, is provided, although you can also

tell the converter that you want it to bring in your own.

either way, what you receive is something fully functional

and entirely stand-alone. it’s explicitly not just a snippet.

this difference in focus is a very important distinction,

like the difference between a blog comment and a book.

a concentration on long-form material means _sections_

are a crucial organizing principle of the z.m.l. framework.

in fact, it’s not unreasonable, as a general rule of thumb,

to think that you should stick with markdown if you are

using it to create relatively small pieces of content, like

one-at-a-time blog articles just a couple paragraphs long.

but if you are writing pieces that have multiple sections,

you’ll find that z.m.l. probably meets your needs better.

if your documents are long enough that they can benefit

by having a table of contents, you are writing long-form,

and you need a light-markup system geared to that goal.

and when you are offering a reader a document that big,

the skeleton organization of the document is something

that needs to be made clear to the reader, and the vehicle

which provides that vital clarity is your table of contents.

thus it is very important just from that single perspective.

let me stress that. you _want_ your readers to see and use

your table of contents, just as soon as they start reading,

because it helps them wrap their mind around the piece,

and frames their approach, especially if they’re reading it

in an electronic-form, on a screen, where it’s amorphous.

that reader-orientation to the article can be so important.

moreover, the table of contents helps you, as the writer.

it is the guide that organizes your thoughts, and ensures

that your piece embodies an “arc” that makes it cohere.

it’s the “outline” your teachers told you to start out with.

although, truth be told, a good one is always evolving, so

the important thing is to stay current with it as it does,

so you’re aware where the path is, and where it is going.

i apologize for this wee excursion in a writerly direction,

but it’s not off-topic, because it is this focus on _writing_

which serves as the very bedrock of the z.m.l. philosophy.

z.m.l. is not merely a format to make .html for webpages.

one big goal of z.m.l. is to help writers do better writing.

***

so, because of its importance, to both writer and readers,

the table of contents occupies a “place of honor” as the

second section of z.m.l. documents, so everybody knows

where it is, and everybody knows that everybody knows.

the first section, of course, is the cover/title section, but

it’s very good to know that you can count on the fact that

the table of contents is at the top too, just underneath it,

especially since many viewer-apps can jump to the top,

thereby making your table of contents quite convenient.

furthermore…

z.m.l. makes it very easy to maintain a table of contents.

because, if you think about it, you want your headers to

be in two places. one is obviously where they already are

— situated atop their respective sections, naturally —

but the second place would be in your table of contents.

so, during conversion of your z.m.l. text-file to output,

your text is scanned to ascertain its header-structure,

thereby automatically generating a table of contents.

if your table of contents section is the word “autotoc”

— just that simple string of letters, by itself on a line —

the auto-generated contents is spliced into the output.

so, with “autotoc” in your z.m.l. input file, this might be

an example of what would get spliced into your output:

further, if you make a change to the text of a header,

it is displayed immediately, in the on-the-fly preview.

so the table of contents stays in sync with the headers.

so, if we were to leave the “autotoc” line just as it was,

but edit the old-fashioned non-useful roman numbers

— the ones on those actual headers, in the text itself —

the auto-generated version will come to look like this:

(and yes, in z.m.l., we include the title — and even the

“table of contents” header — _in_ the table of contents,

even though some people might consider it redundant,

because we might want to copy this section out to the

digital equivalent of a “card catalog” for our cyberlibrary.

so we really need that listing to be full-and-complete.)

z.m.l. makes it very easy to

maintain a table of contents.

or, if you prefer it the other way around, you can put in

the table of contents that you want, and the converter

will compare the actual structure of your actual headers

against the structure you listed in the table of contents,

and alert you to any discrepancies between those two,

so that you can edit the errors, wherever they might be.

consider this as the kind of alert you might get:

http://zenmagiclove.com/simple/alice-toc-check-alert.png

or, for instance, say the auto-generated table of contents

looked like this graphic below. how do you analyze this?

http://zenmagiclove.com/simple/alice-autotoc-improper-levels.png

well, the auto-generator pays attention to the _levels_

of your headers, and indents them appropriately, so

— compared to the “h2" for all the other headers —

this indicates that chapter 5 is mislabeled as an “h3"

and chapter 9 has been mislabeled as an “h4" header,

so we’ll need to edit those two to be the correct level.

so you can either use the auto-generation approach

all of the time and assume your headers are correct.

or you can create your “ideal” table of contents and

then be alerted if the actual headers diverge from it.

or you can combine both those approaches, so start

with the auto-generation, and then — once you have

satisfied yourself that it is correct as you intended —

include a copy explicitly, so if you accidentally make

a change to your header-structure, you’ll be alerted.

or, if you intentionally change your header-structure,

you will be alerted so you edit your table of contents.

this auto-generation is one way z.m.l. helps you out,

when it comes to the matter of the table of contents.

but it doesn’t stop there.

the converter routine goes on to link every item in the

table of contents to its respective section in the output.

because today’s readers have a right to expect such links.

and you don’t need to do a single thing to get the links,

which is exactly what you should expect from the tool.

because the converter is fully capable of creating them.

finally, because these links are in every z.m.l. document,

readers will expect them, with no need for you to explain.

and yes, since you likely know how internal links work,

z.m.l. does indeed assign an .html “id” to every header.

and it’s not some randomly-assigned nonsense, either.

it’s an i.d. that directly parallels the header itself, so you

can confidently predict what it is by knowing the header,

without any need to go “view source” to learn what it is.

> Chapter 10 -- The Lobster Quadrille

> #chapter_10_—-_the_lobster_quadrille

...or this works too...

> #chapter_10

...or this works too...

> #the_lobster_quadrille

***

but wait. there’s more…

each header is also linked _back_ to the table of contents,

so your readers have awesome navigational functionality.

(which you can also use, while you are writing the piece,

since all of the links are fully functional in your preview;

good navigation is needed when you’re writing long-form.)

the table of contents, with great navigational functionality,

is a true asset to the power and simplicity of z.m.l. output.

and it’s largely automatic, because of the long-form focus.

now that we’ve grounded ourselves in the mechanisms of

the table of contents, we can discuss sections and headers.

***

headers and sections

and gourds, oh my!

in z.m.l., the “technical” term we use for a “section”

is “gourd”. thus, “chunks” accumulate into “gourds”,

just as paragraphs accumulate into chapters in a novel.

but no, i’m not going to use the “gourd” term here;

i just thought you should be told its “official” name,

so if/when we use it later, you’ll know what it means.

now, to repeat something we said earlier,

the first chunk in each section is its header.

the first chunk

in each section

is its header

the next chunk or two can be headers too,

or subheaders, which is a technicality, but

the first chunk is _always_ a header, by rule.

and, just so you know, the requirement that

a header must be _followed_ by 2 blank lines

is so z.m.l. knows where the header-chunk

and all its possible subheader-chunks end.

next of all, remember that the “h1" header

is reserved for the title of your document,

which must be the first “chunk” in your file,

so there is no need (or ability) to assign “h1".

so we are essentially talking about levels of

headers “h2" to “h6”, if you need that many.

(quite often, you only need one level, “h2".)

so this means that headers in your document

will need to be identified, for z.m.l. to handle.

more precisely, _sections_ in your document

will need to be identified, for z.m.l. to handle.

the rule for sections in z.m.l. is clear and simple:

every z.m.l. section must be preceded by

at least 5 blank lines (or more), and

its header-chunk(s) must be followed by

exactly 2 blank lines.

——————————————————————-

every z.m.l. section

must be preceded by

at least 5 blank lines (or more),

and its header-chunk(s)

must be followed by

exactly 2 blank lines.

——————————————————————

this arrangement of blank lines tells z.m.l.

exactly where the sections break, as well as

where each header begins and where it ends.

so any time there is a 5-blank-line sequence,

the chunk that follows it becomes the header

for that new section. so, if you don’t want to,

there’s not even any need to label the header!

just put a space in column 1, to identify that

chunk as a “block”, and then type the header.

(to be honest, you don’t even need the space.)

got that? there’s no need to mark the header!

this is a good example of where the “zen” in

“zen markup language” comes in the picture!

if you wonder, this 5-blank-line rule is based

on the one used for project gutenberg e-texts.

the project gutenberg corpus was the model for

the plain-text conventions i wanted to emulate.

http://www.gutenberg.org/wiki/Gutenberg:Volunteers%27_FAQ#V.111._How_should_I_handle_chapter_and_section_headings.3F

project gutenberg requires 4 blank lines, but for

a programming reason, i’ve changed that to _5_.

(hey, since you’re here reading a fucking manual,

you probably _wonder_ about what the reason is,

so i’ll tell you. to split a z.m.l. text into “chunks”,

we just split it by “



” — a pair of linebreaks —

which is how a blank line in a file expresses itself.

so when we require 5 blank lines before a section,

that translates to 6 successive linebreaks, meaning

2 successive empty chunks indicate a new section,

and we don’t have to do another split for sections.)

***

you can witness this in the project gutenberg e-text

for “alice’s adventures in wonderland”, which was

what i used above for the sample table of contents.

> http://www.gutenberg.org/files/11/11.txt

…or…

> http://www.gutenberg.org/cache/epub/11/pg11.txt

as you scroll through the e-text, you’ll notice that

the chapter-headers stand out nicely, due to that

relatively large amount of whitespace above them.

and there’s another appealing thing about this rule,

for me anyway, because i admire print-book design.

see this?

> http://zenmagiclove.com/simple/alice-header-midpage.jpg

> https://archive.org/stream/alicesadventures00carr3#page/30/mode/2up

that’s an image of a real hard-copy page from “alice”.

notice how the header is offset from the top the page?

that, of course, is something very common in books.

for me, the 5-blank-lines-above rule reconstrues this,

conjures in my mind a picture of this kind of design.

***

so, did you look at that project gutenberg “alice” file?

if so, did you notice the headers did _not_ have the

required 2-blank-lines below each chapter-header?

except chapter 12? unfortunately, project gutenberg

has always done a lousy job of “enforcing” its rules,

fearful that doing so would chase off its volunteers,

so its e-texts are rife with inconsistency issues. sad.

***

ok, so we know now that, in terms of marking the

existence of a new section, 5 blank lines will do it.

and that, given that, we don’t even need to mark

the header for it, since it’s always the first chunk.

and as long as we’re happy having all our headers

at the same level, then we can be “officially done”.

but we often do want a document-structure that

includes headers with a variety of different levels.

so how do we set the levels of these various headers?

***

setting the header levels

if your document has headers of different levels,

you’ll indicate the level of a specific header using

either of 2 different methods, the choice is yours.

set header level — method 1 —

setting the level via blank lines

you must have at least 5 blank lines preceding

each header, but that will only give that header

the “basic” level in that particular document.

for instance, if all the headers have 5 blank lines,

they will all be assigned the “h2" .html header.

however, if you vary the number of blank lines,

the assigned levels of the headers will vary too.

so let’s say you want “h2" and “h3" .html headers;

you could put 5 blank lines before the “h3" headers,

and (let’s say) 6 blank lines before the “h2" headers.

more blank lines indicate a higher-priority header;

you can remember this using the “offset” graphic,

because more blank lines will create a bigger gap.

so whichever headers have the most blank lines,

those are the ones that will get the “h2" markup.

the ones with the next most get “h3", and so on.

so let’s say you want to use all 6 levels of headers.

you might use 6 blank lines before the h6 headers,

8 before the h5 headers, 10 before the h4 headers,

12 before h3 headers, and 14 before h2 headers.

(read that last paragraph in the opposite order

if doing so will help you understand it better.)

i can hear your skepticism about this arrangement,

probably because i’ve heard it so often in the past,

something about not wanting to count blank lines.

i can tell you that, once you get used to this method,

it works very well, and you will come to embrace it.

all of the volunteers at project gutenberg learned it,

and i’ve used it too, quite nicely, for many years now.

“counting lines” isn’t all that hard to do. in fact, i find

that it is rather fulfilling to do it, knowing i’m starting

a new section, which means my writing is proceeding.

and remember, if you get the number of lines wrong,

the auto-generated table of contents will look weird.

here, let me show you that graphic again:

see? it’s very obvious what needs fixing there.

alas, i can still hear your skepticism.

you probably still don’t believe me.

so i’ll give you a second method that’s more explicit.

but you have to promise me you’ll actually _try_ to

use the blank-lines method, because it really works,

and if you just try it out, you’ll see that it’s very nice.

but ok, here’s that other method, which will look

familiar to you, because it’s the old hashmark one.

***

set header level — method 2 —

setting level via explicit hashmarks

you can set the level via the “hashmark” method instead.

each header still needs to be preceded by 5 blank lines,

and followed by 2 blank lines. but the header’s _level_

is indicated explicitly with the familiar “ ## ” markup.

specifically, an h2 header is marked with “ ## ” at its start.

an h3 header is marked with “ ### ”, h4 with “ #### ”, etc.

notice the “ ## ” marks must have a space in column 1, and

there must be at least one space before the header begins.

(and, once again, perhaps you can actually skip the spaces,

but i might “fix” that in future versions of the converter.)

to repeat: note that the “ ## ” marks are _not_ locating the

start of the section — the 5-blank-line sequence does that —

but rather merely the _level_ of the header. be clear on that.

you can put in all the “ ## ” marks you want, but that won’t

signal the beginning of a new section to the z.m.l. converter.

if your “header” is not preceded by the set of 5-blank-lines,

yes, it’ll get an .html “hx” tag, and be displayed big and bold,

but it _won’t_ be considered to be a section-header, meaning

it will not go in the auto-generated table of contents, nor will

it be assigned an .html “id” automatically, nor get any links.

but if you _do_ precede your hashmark-header properly, with

a set of 5-blank-lines, it’ll be considered a full-fledged header,

with its level explicitly set by the number of hashmarks it has,

and _not_ by the number of blank lines which it has above it.

***

and with that, we have finally finished up with headers. yay!

thank you for being patient with the awful length of this thing.

like i said, once my over-explainer comes out, even i get bored. ;+)

i promise the remaining parts of this series will be much shorter.

and even better news is that there aren’t too many of them left!

so if you’ve come this far, make sure and stay for the whole ride.

because even before the series ends, authoring-tools will emerge.

and that’s when the _real_ fun will begin!

***

here are the articles in this series:

beyond markdown — part 1 — it’s time for the next step https://medium.com/@bbirdiman/beyond-markdown-part-1-2300665659f7

beyond markdown — part 2 — z.m.l. was built to be easy to understand https://medium.com/@bbirdiman/beyond-markdown-part-2-b3527d2b9dcf

beyond markdown — part 3 — two types of chunks — paragraphs and blocks https://medium.com/@bbirdiman/beyond-markdown-part-3-eed9bebea0da

beyond markdown — part 4 — how to “tag” a block for formatting https://medium.com/@bbirdiman/beyond-markdown-part-4-9b4dc6841d7e

beyond markdown — part 5 — shining a spotlight on sections and headers

https://medium.com/@bbirdiman/beyond-markdown-part-5-4902097723b0

beyond markdown — part 6 — notes on a few types of “special” paragraphs

https://medium.com/@bbirdiman/beyond-markdown-part-6-8056eee5b783

beyond markdown — part 7 — text styling and typographic niceties

https://medium.com/@bbirdiman/beyond-markdown-part-7-3158e23f22bf

beyond markdown — part 8 — alignment, horizontal rules, and breaks

https://medium.com/@bbirdiman/beyond-markdown-part-8-1a082d7f1f6d

beyond markdown — part 9 — pulling outside resources into your document

https://medium.com/@bbirdiman/beyond-markdown-part-9-be74bbbed369

beyond markdown — part 10 — special sections in your document

https://medium.com/@bbirdiman/beyond-markdown-part-10-3ca0c08e5641

***

and, for reference, as an extra bonus:

markdown considered harmful — or perhaps a loved but irritating old uncle

https://medium.com/@bbirdiman/markdown-considered-harmful-495ccfe24a52