— part 4

how to “tag” a block for formatting

for links to the 3 prior articles in this series,

see the list given at the bottom of this article.

z.m.l. — a.k.a., zen markup language — is a

light-markup format you might enjoy using,

especially if you have markdown pain-points.

in the previous segments, we explained how

z.m.l. is built to be easy to understand, and

how each element in a z.m.l. text is called a

“chunk” and must be bordered by blank lines.

we also noted that every chunk can be either

a “paragraph” or a “block”, and you know by

the first column in the first line of the chunk.

if it is a space, the chunk is a “block”, which

means it requires some “special formatting”.

if the first character is not a space, the chunk

is a “paragraph”, and gets normal formatting.

now we will go on to the next point, which is

how you tell z.m.l. _what_kind_ of block it is.

for instance, say you need to make a table;

there is a “tag” you must apply to tell z.m.l.

that you want it to create your table for you.

***

the first 3 characters are the “tag”

the first character is enough to tell if a chunk

is a block, but you need the first 3 characters

to say what _kind_ of block that it is, and thus

what kind of special formatting it will receive.

these 3 characters are called the block “tag”.

the first and third characters are usually a space,

so we’ll typically label the tag by using the second,

dispensing with mention of the surrounding spaces.

***

tables

for instance, the tag for a _table_ is the “|”,

the vertical-line that’s often called an “or-bar”

(as it is used as the symbol for “or” in logic).

so, if you want to make a table, you would

start the chunk with [space] [|] [space] —

a space, then an or-bar, then another space.

| this is a “table” with one column

it would look like this in the input:

http://zenmagiclove.com/simple/zml-input-table1.png

and it would look like this in the output:

http://zenmagiclove.com/simple/zml-output-table1.png

***

or, if we want something that’s more like

a real honest-to-goodness table, try this:

| this lone line looks like a table header

| row value | col 1 head | col 2 head | monday | 11am | 9pm | tuesday | 9am | 9pm | wednesday | 9am | 9pm | thursday | 9am | 11pm | friday | 11am | 6pm

in the input, that table will look like this:

http://zenmagiclove.com/simple/zml-input-table2.png

note that you can also “line it up” if you like:

http://zenmagiclove.com/simple/zml-input-table2b.png

either way, lined up or not, in the output, that table will look like this:

http://zenmagiclove.com/simple/zml-output-table2.png

***

let’s see those block tags!

now that we know how to do a table, we have

a way to present the entire set of block tags…

here’s a z.m.l. table, showing those block tags:

| tag character | html | comments | > | blockquote | wrap lines | : | blockquote | no wrap lines | * | unordered list | disc bullet | o | unordered list | circle bullet | = | unordered list | square bullet | + | unordered list | 2-level indent | — | unordered list | 3-level indent | x | unordered list | no bullet | # | numbered ordered list | standard html | ~ | code-block | comment 1 | ` | code-block | comment 1 | “|”| table | solid borders | ^ | table | no borders | ! | poetry | varying indents | ; | definition | must be accompanied | . | filler line | (period by itself)

if we were to line that up in our input file, it might look like this:

http://zenmagiclove.com/simple/zml-input-table5.png

and then that input would look like this, in the output:

http://zenmagiclove.com/simple/zml-output-table5.png

remember that the full format of the block-tag is: [space][tag][space] at the start of the chunk. don’t forget the spaces!

***

ok, now let’s step through and demonstrate each of those block tags.

we have the following:

blockquotes

unordered lists

ordered lists

code-blocks

tables

poetry

definition-blocks

filler-line

***

blockquotes

there are 2 forms of blockquote markup, one of which

rewraps the lines to the current viewport width, while

the other one retains the linebreaks from the input.

i know that “>” will be the tag for one of the forms,

but i’m not really sure which one it will be, nor have i

decided on the tag for the second, but let’s say “:”.

> for now, anyway, the “>” tag does the rewrapping,

> so even though this chunk has linebreaks in it,

> the output will eliminate them to do rewrapping.

the input will look like this:

http://zenmagiclove.com/simple/zml-input-blockquote1.png

and the output might look like this:

http://zenmagiclove.com/simple/zml-output-blockquote1.png

***

> notice that if you are using the “rewrap” form,

you have to put the “>” tag on the first line, yes,

but it’s unnecessary to put the tag on every line,

since those tags are gonna be removed anyway.

note that this chunk starts with [space][>][space],

so z.m.l. recognizes this block as a block-quote.

in other words, it’s only necessary to put the tag

on the first line of the blockquote, not all of them.

but, of course, you can put the “>” on every line,

if that makes the blockquote more clear for you.

so this input:

http://zenmagiclove.com/simple/zml-input-blockquote2.png

might create this output:

http://zenmagiclove.com/simple/zml-output-blockquote2.png

***

: now, when you use the colon tag for a blockquote,

the linebreaks will be retained. so again, therefore,

there’s no need to put the colon tag on every line.

so this input:

is equivalent to this input:

and both will create this output:

***

unordered lists

we discussed lists in part 3, but to refresh your memory,

you can use the different forms of the unordered-list tag

to get different bullets for the list-items. you can also use

“+” and “-” tags to get second-level and third-level indents.

so you could enter this:

* unordered list, disc bullet o unordered list, circle bullet x unordered list, no bullet = unordered list, square bullet + unordered list, 2-level indent - unordered list, 3-level indent

that input would look like this:

and it would give this output:

***

ordered lists

the tag for a numbered list is “#”.

so assume we have this chunk:

# one # two two # three three three # four four four four # five five five five five

our input file would look like this:

and it would produce this output:

later you will learn that the hashmark can also

be used as an option to mark headers in your file,

and you’ll learn how z.m.l. differentiates the two.

but the secret is that you never use a “ # ” header;

the top chunk in your file is always considered as

the title, and thus gets the sole .html tag of “h1".

all of the other .html headers — h2 through h6 —

are assigned with tags “ ## ” through “ ###### ”.

it is also the case that headers must be preceded

by at least 5 blank lines, so that’s yet another sign,

to stop confusion. but we’ll discuss headers later.

***

code-blocks

one of the blocks that you can tag is computer code.

when you tag a block as “code”, it is not processed

as z..m.l. text. for instance, underbars are underbars,

not shortcuts for italics. and asterisks are asterisks.

quotemarks are untouched, not converted to curly.

even a u.r.l. is left as text; it’s not converted to a link.

(though it probably wouldn’t hurt anything, i guess.)

you can use either a backtick or a tilde to tag a chunk

as code. at present, these 2 forms are highly similar.

in the future, we could produce some differentiation

between these 2 tags, but that decision will be made

down the line, with the help of the z.m.l. community,

according to the specific needs which are manifested.

for the moment, though, one of them is marked with

the .html “pre”, and the other with the .html “code”.

(and, to be honest, i’m not sure which is which, since

i suspect i’ve previously done both of ‘em both ways;

and i don’t know if this difference has ramifications.)

also notice that you can mark each line of the block

with the tag, or just mark the first line of the block,

as was the case we discussed with “blockquote” tags.

furthermore, the first line, which contains the tag,

can be otherwise empty. or, to facilitate colorizing

of the code, it can contain the name of the language.

` this entire paragraph (1) ` will be treated as code.

` this entire paragraph (2)

will be treated as code.

your input file might look like this:

http://zenmagiclove.com/simple/zml-input-code1.png

and the output might look like this:

http://zenmagiclove.com/simple/zml-output-code1.png

***

(thanks to alan hogan, who noticed

i’d made mistakes in these code images

and alerted me so i could correct them!)

***

or take these chunks:

`

this entire paragraph (3)

will be treated as code.

` // javascript

//this entire paragraph (4)

//will be treated as code.

your input could look like this:

http://zenmagiclove.com/simple/zml-input-code3.png

and your output might look like this:

http://zenmagiclove.com/simple/zml-output-code3.png

***

or consider this text:

~

this entire chunk (5)

will be treated

as code.

~ this entire chunk (6) will

be treated as code.

~ this entire chunk (7) will ~ be treated as code.

the input might look like this:

http://zenmagiclove.com/simple/zml-input-code5.png

and the output might look like this:

http://zenmagiclove.com/simple/zml-output-code5.png

***

a blank line terminates the chunk,

so if your code contains blank lines,

turn them into empty comment-lines.

consider this, which is one chunk:

` // javascript

var s = “this entire paragraph (8)”

var t = “will be treated as code.”

//

var u = “see what i did there?”

//

var v = “i retained the unity of (9)”

var w = “the chunk by turning”

var x = “the blank lines into”

var y = “non-blank lines —”

var z = “i.e., empty comments.”

the input might look like this:

http://zenmagiclove.com/simple/zml-input-code8.png

the output would look like this:

http://zenmagiclove.com/simple/zml-output-code8.png

***

finally, you could have input that looked like this:

~ // javascript

— — — — var s = “it’s fine to indent your code (9)”

——— — — — ——- var t = “even to vary your indent”

var u = “indents don’t even have to make sense”

http://zenmagiclove.com/simple/zml-input-code9.png

the output would look like this:

http://zenmagiclove.com/simple/zml-output-code9.png

***

tables

you’ve already seen tables in action,

so i will just note here that there are

2 forms of the table block tag as well;

the “|” draws borders around cells,

and the other one — “^” — does not.

^ this is a borderless “table” with one column, one row

it would look like this in the input:

http://zenmagiclove.com/simple/zml-input-table-none-1.png

and it would look like this in the output:

http://zenmagiclove.com/simple/zml-output-table-none-1.png

***

for a real honest-to-goodness table, try this:

^ this lone line looks like a table header

^ row value ^ col 1 head ^ col 2 head ^ monday ^ 11am ^ 9pm ^ tuesday ^ 9am ^ 9pm ^ wednesday ^ 9am ^ 9pm ^ thursday ^ 9am ^ 11pm ^ friday ^ 11am ^ 6pm

the input might look like this:

http://zenmagiclove.com/simple/zml-input-table-none-2.png

and the output might look like this:

http://zenmagiclove.com/simple/zml-output-table-none-2.png

you can also do something like this:

^ left side ^ center ^ right side

so your input would look like this:

http://zenmagiclove.com/simple/zml-input-table-none-3.png

and your output would look like this:

http://zenmagiclove.com/simple/zml-output-table-none-3.png

because sometimes you want the ability to quickly and easily

format something that looks like that, without fuss or muss.

***

as long as you stay _simple_ with tables,

you can even go relatively _big_ with them.

here’s how you might enter a long table:

| major league baseball final standings 2014

| _national_league_

| _n.l._west_ | w | l | pct | gb | home | away | l10 | strk

| dodgers | 94 | 68 | .580 | — | 45–36 | 49–32 | 8–2 | w5

| giants | 88 | 74 | .543 | 6.0 | 45–36 | 43–38 | 4–6 | w2

| padres | 77 | 85 | .475 | 17.0 | 48–33 | 29–52 | 6–4 | l2

| rockies | 66 | 96 | .407 | 28.0 | 45–36 | 21–60 | 5–5 | l4

| d-backs | 64 | 98 | .395 | 30.0 | 33–48 | 31–50 | 2–8 | l1

| = | = | = | = | = | = | = | = | =

| _n.l._central_ | w | l | pct | gb | home | away | l10 | strk

| cardinals | 90 | 72 | .556 | — | 51–30 | 39–42 | 6–4 | w1

| pirates | 88 | 74 | .543 | 2.0 | 51–30 | 37–44 | 6–4 | l2

| brewers | 82 | 80 | .506 | 8.0 | 42–39 | 40–41 | 3–7 | l1

| reds | 76 | 86 | .469 | 14.0 | 44–37 | 32–49 | 5–5 | w2

| cubs | 73 | 89 | .451 | 17.0 | 41–40 | 32–49 | 5–5 | w1

| = | = | = | = | = | = | = | = | =

| _n.l._east_ | w | l | pct | gb | home | away | l10 | strk

| nationals | 96 | 66 | .593 | — | 51–30 | 45–36 | 8–2 | w2

| mets | 79 | 83 | .488 | 17.0 | 40–41 | 39–42 | 6–4 | w2

| braves | 79 | 83 | .488 | 17.0 | 42–39 | 37–44 | 3–7 | w2

| marlins | 77 | 85 | .475 | 19.0 | 42–39 | 35–46 | 3–7 | l2

| phillies | 73 | 89 | .451 | 23.0 | 37–44 | 36–45 | 3–7 | l2

| = | = | = | = | = | = | = | = | =

your input for the national league will look like this:

http://zenmagiclove.com/simple/zml-input-table3.png

***

and then, for the american league…

| _american_league_

| _a.l._west_ | w | l | pct | gb | home | away | l10 | strk

| angels | 98 | 64 | .605 | — | 52–29 | 46–35 | 3–7 | l3

| athletics | 88 | 74 | .543 | 10.0 | 48–33 | 40–41 | 5–5 | w1

| mariners | 87 | 75 | .537 | 11.0 | 41–40 | 46–35 | 5–5 | w4

| astros | 70 | 92 | .432 | 28.0 | 38–43 | 32–49 | 3–7 | l2

| rangers | 67 | 95 | .414 | 31.0 | 33–48 | 34–47 | 7–3 | l1

| = | = | = | = | = | = | = | = | =

| _a.l._central_ | w | l | pct | gb | home | away | l10 | strk

| tigers | 90 | 72 | .556 | — | 45–36 | 45–36 | 6–4 | w1

| royals | 89 | 73 | .549 | 1.0 | 42–39 | 47–34 | 6–4 | w1

| indians | 85 | 77 | .525 | 5.0 | 48–33 | 37–44 | 6–4 | w1

| white sox | 73 | 89 | .451 | 17.0 | 40–41 | 33–48 | 4–6 | l1

| twins | 70 | 92 | .432 | 20.0 | 35–46 | 35–46 | 5–5 | l1

| = | = | = | = | = | = | = | = | =

| _a.l._east_ | w | l | pct | gb | home | away | l10 | strk

| orioles | 96 | 66 | .593 | — | 50–31 | 46–35 | 4–6 | w1

| yankees | 84 | 78 | .519 | 12.0 | 43–38 | 41–40 | 6–4 | w1

| blue jays | 83 | 79 | .512 | 13.0 | 46–35 | 37–44 | 6–4 | l1

| rays | 77 | 85 | .475 | 19.0 | 36–45 | 41–40 | 3–7 | l1

| red sox | 71 | 91 | .438 | 25.0 | 34–47 | 37–44 | 5–5 | l1

so, for the american league, your input file will look like this:

http://zenmagiclove.com/simple/zml-input-table4.png

***

so much for the input. now let’s look at the output.

***

in the output, the national league will look like this:

http://zenmagiclove.com/simple/zml-output-table3.png

and the american league will look like this:

http://zenmagiclove.com/simple/zml-output-table4.png

these tables are almost certainly too wide to work on many smartphones,

so in general you will want to split tables so that they are more narrow,

but i just wanted to show you that it’s possible to do a very big table here.

***

poetry

the thing about poetry is that its indentation

is often quite crazy. to allow that to flourish

any line that starts with 6 spaces or more is

considered poetry, and the number of spaces

(after those starting 6) governs indentation.

this means that input like this:

will create output like this:

or, if you want to get really fweaky, input like this:

will create output like this:

note that you can also use the exclamation point tag

to indicate a block of poetry. the exclamantion point

was chosen as the tag for poetry because poetry is

wildly exciting. and because poets have bad teeth!

***

definition-blocks

sometimes, such as in a glossary, you will

want to provide definition(s) for a word.

use a semi-colon tag for this kind of block.

one tricky part of this particular type of tag

comes from the fact that it involves 2 parts.

the first is the term which is being defined

(which might be a single word, or a phrase).

the second part is the definition being given,

which is further complicated by the fact that

it is possible to provide _several_ definitions.

so this tag is more complicated than others.

first, the term being defined is a chunk _and_

then each definition given is a separate chunk.

for the term which is being defined, you will

use the “;” tag at the beginning of the chunk,

_plus_ you must end the term with a _colon_.

for every definition, you also use a “:” tag, and

you _cannot_ end any definition with a colon.

let’s say you have this text:

; irony:

; the expression of one’s meaning

by using language that normally

signifies the opposite, typically

for humorous or emphatic effect.

; a state of affairs or an event

that seems deliberately contrary

to what one expects and is

often amusing as a result.

; a literary technique,

originally used in Greek tragedy,

by which the full significance of

a character’s words or actions

are clear to the audience or reader

although unknown to the character.

your input file might look like this:

http://zenmagiclove.com/simple/zml-input-definition1.png

and your output file might look like this:

http://zenmagiclove.com/simple/zml-output-definition1.png

***

or say you had this text:

; sarcasm:

; the use of irony to mock or convey contempt

your input file might look like this:

http://zenmagiclove.com/simple/zml-input-definition2.png

and your output might look like this:

http://zenmagiclove.com/simple/zml-output-definition2.png

***

this is the current solution for this tag, but

it’s not one that i am yet satisfied is “best”;

it might get changed if we find a better way,

based on input from the z.m.l. community,

once such a mighty beast rears its ugly head.

***

actually, there are lots of such “flexibilities”

in the final decision-making in regard to the

“rules” that will define zen markup language.

i’ve spent enough time thinking about it

that i know where i have to be inflexible

— in order to ensure that things work —

and where i can afford to change my mind.

there’s a natural tension that revolves around

curating ability to customize to personal desire

versus ambiguity ruining the fun for everyone,

and i intend to attend to walking that tightrope

to best serve the needs of the z.m.l. community.

i won’t be an absentee landlord, nor collect rent.

***

space-period “empty” filler-line

as you’ve seen, blank lines are meaningful

in z.m.l., but sometimes you just want a

empty line in there, without any meaning.

for such an “empty” line, use a “filler-line”

— a line with a space followed by a period.

***

conclusion

this concludes our discussion of the “tags”

you can use to mark a “chunk” as a “block”,

so as to get the type of formatting you want.

next up, in part 5, we’ll discuss _headings_,

and then go on to a couple of odds and ends,

and then you’ll have a great handle on z.m.l.

after that, i’ll show you a z.m.l. editing tool,

with an on-the-fly live preview of the output

that is created from your input, so you can

experiment with z.m.l. using your own text,

and your own documents, to see the output.

that is where the rubber will meet the road.

book-learning is fun. but hands-on is better!

***

this is the end of “beyond markdown — part 4".

thanks for reading!

***

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