— part 11

congratulations on your commencement

***

congratulations!

you’ve finished the “beyond markdown” series!

or perhaps you haven’t. a list of the first 10 parts

of the series is at the bottom, complete with links,

if you want to go back and see what you missed.

or, if you prefer, you can have a more hands-on

type of experience, after you read this “part 11".

this series explained “zen markup language”,

a form of light-markup much like “markdown”.

zen markup language — or “z.m.l.” for short —

is similar to markdown in many ways, but it is

also quite different, especially in its philosophy,

the clarity and simplicity of its “mental model”,

and its primary focus on long-form documents.

some people are happy with markdown, and will

see little reason to switch to another formulation.

and that’s fine. as long as you’re happy, i’m happy.

but other people are not happy with markdown,

for a number of reasons, some of which might be

addressed with a switch to zen markup language.

i will be just as big of a “benevolent dictator” as

john gruber, owner of the markdown trademark

(in the practical sense, and perhaps a legal one).

but i intend to listen intently to the community

of people who cluster around z.m.l., and use it,

and will actively solicit their input to improve it.

so that’s another significant point of departure.

z.m.l. is geared to book-writers and book-readers,

people who can be very _interesting_ to listen to.

and i will begin listening almost immediately…

i just posted 10 articles giving the rules of z.m.l.,

and perhaps you noticed some “holes” in them.

(i put some in on purpose, just to make you think.)

if you intend to become a user of z.m.l., i am

interested in hearing what you think about it.

so let us commence…

this is the commencement…

so far you have read the z.m.l. documentation.

that’s given you some kind of “feel” for the thing.

but hands-on experience is much more vivid,

don’t you agree? so let’s get some of that, ok?

besides, z.m.l. is just a small piece of the bigger

concern — production, distribution, and remixing

of a global cyberlibrary of thoughtful documents

— so the toolset of the overall workflow matters,

probably more than the details of the file-format.

so let us turn now to the tools to support z.m.l.

here’s where you can find one demo-app for z.m.l.

> http://zenmarkuplanguage.com/cgi-bin/byondweb.cgi

what you will see is documentation for z.m.l.,

in the form of a “test-suite” to demonstrate it.

your initial view displays its converted z.m.l.

this is the web-page as it might be presented

to end-users interested in reading its content.

that’s fine, but…

now we’ll turn that webpage into a z.m.l. editor.

click the button at the top-right corner.

this opens a 2-pane interface, with the z.m.l.

input on the left, converted .html on the right,

showing the relationship of “input” to “output”.

for many people, it’s easier to understand it

when they actually see it, rather than if they

read documentation that explains the “rules”.

***

sometimes you want thepanels in sync, but

sometimes you want ‘em to be independent.

you can scroll each pane independently, and

match them manually if you are patient, but

to force the output side to sync to the input,

just double-click somewhere inside the input.

likewise, to make the input sync to the output,

just double-click somewhere inside the output.

(but make sure you don’t click a link, because

the .html on the right is “live”, so links work,

and they take priority over the sync capability.

to safely avoid a link, click to the right of text.)

to sum it up, simply double-click in one pane

and the other pane automatically syncs to it.

***

because the links work on the “display” side,

you can take advantage of those links to move

around the document. notice, most especially,

that the table of contents is completely linked,

plus you can click any of the chapter-headers

to jump back to the table of contents. handy.

also notice that, because the output is “live”,

the audio and video files should play correctly,

if you’re on a mac anyway. (others come later.)

***

seeing the parallel of input and output is good.

but it’s even better when you can experiment!

test for yourself the z.m.l. input can be edited;

just pick any paragraph at random and edit it;

after a 3-second delay, it gets converted, with

the just-converted .html shown on the right.

for instance, here’s a place where i did an edit,

a suggestion, which i mark with a “??” so i can

easily find it in a search before my “final” edit.

for the record, because this is a web-app, there are

lots of trips being made between server and client,

so peformance is not nearly as good as when we are

working with a local javascript file doing operations.

***

this app can answer any questions you have

about the actual operation of z.m.l. “rules”.

so if you wonder “what happens if i do this?”,

or “what about such-and-such a situation?”,

you can use this file to answer that question.

try it and see what happens!

if it is not what you think _should_ happen,

then perhaps you must adjust your thinking.

or maybe you should raise a question in the

z.m.l. community about changing that rule.

or perhaps you just ran into a program bug?,

because, as it is an early beta, crap happens.

***

ok, now this is not a “real” editor. (not yet.)

there’s no way, in this file, for you to “save”

your edits, so it’s just experimentation, but

playing around is a great way to learn z.m.l.

plus you can use this little file to see if z.m.l.

that you wrote in your preferred text-editor

was entered correctly to look like you want.

just “select all” on the input side, delete it,

and copy in your own text, to see if it works.

let’s look a bit more closely

if you’re a tech person, you might want to

know some details, so let’s discuss them.

(if you don’t care, skip to the next section,

entitled “the people, the ports, the path”.)

remember, the actual working app is here:

> http://zenmarkuplanguage.com/cgi-bin/byondweb.cgi

if you could do a view-source on the .html

(you can’t, for reasons i’ll discuss shortly)

you would see that it is “straightforward”

— utterly so, in a plain-text sort of fashion —

because that’s what it is — a z.m.l. input file.

i admit that might seem that i’m a bit confused

— so what is it?, a z.m.l. file or an .html file? —

so i’ll actually show you a copy of the file, here:

> http://zenmagiclove.com/simple/byond-dot-html.txt

or, if you want to see this file as an .html file:

> http://zenmagiclove.com/simple/byond.html

whether you do a view-source on *that* file,

or review the .txt-file equivalent, you learn

it has a handful of .html header lines up top,

which technically make it an .html file, with

as you see, one dependency, a javascript file.

and _vanilla_ javascript, at that, with no jquery.

but after the header-lines, for the most part,

the file is largely .zml “input”, pure plain text.

(and yes, this .html file does validate, as is.)

as opposed to the actual working app, however,

the javascript file for this *copy* is a “stand-in”,

which is why this copy doesn’t act like the app.

you can view the “stand-in” javascript file here:

> http://zenmagiclove.com/simple/byond.js

now, in the working web-app, that z.m.l. gets

converted to .html by the real javascript file,

which also builds the page, and the .css too,

and administers the 2-up “editing” interface,

all done client-side, on-the-fly, after “onload”.

now, as far as this client-side processing goes…

you don’t have to use .zml like this, of course.

you can do it traditionally, convert offline and

use the results to make a fully-contained page

— without client-side “onload” conversion —

and mount it as a traditional static .html file,

the same way that most people use markdown.

but it is _possible_ to use .zml in this manner

of doing the conversion real-time client-side,

and that’s one of the things i illustrate here.

and i chose to do so, for this demo, because

it helps show how viral z.m.l. can grow to be.

from the standpoint of a writer using z.m.l.,

it’s ridiculously easy just to tack your z.m.l.

to the end of a small file of .html boilerplate.

just by mounting one simple javascript file —

which, by the way, weighs in less than 44k —

alongside that .html file containing your .zml

(underneath that .html header boiler-plate),

you can become almost entirely free of .html,

yet still present a readable, nice-looking page.

there’s no need for you to fuss with .html at all.

no conversion hassle, no work to create a page.

all you need to know is how to mount two files.

moreover — and this is where the word “viral”

comes into play — when one person does that,

they provide the tool-chain (i.e., those 2 files)

for the next person to use, and pass along too,

by merely replacing your z.m.l. text with theirs.

***

now, i’m not suggesting you do that quite yet.

indeed, i originally planned to respectfully ask

you *not* to pass along the javascript quite yet.

that’s because the routines aren’t hardened yet.

yes, the conversion appears to work correctly,

but the javascript is “tentative” in some places,

and geared to the text in the sample right now,

and undoubtedly has some bugs and problems.

it’s simply not robust enough to pass along yet.

but instead of “asking” you not to pass it along,

i wrapped the javascript file into a web-app and

therefore made it fairly difficult for you to grab,

for a short time, until it’s ready for its close-up.

so test it, shake the bugs out of it, so i know that

it’s robust enough to release, and you will get it.

***

for now, i *do* want you to ponder the potential

for z.m.l. to go viral via these 2 convenient files,

a dozen .html header-lines and a <44k javascript.

non-techie writers don’t want to have to bother

installing bulky converters on their computers.

but anyone can handle downloading 2 little files,

and putting their plain-text z.m.l. in one of them,

and using the 2-up interface for quality-assurance.

so please imagine how _easy_ it will be to do that,

once it’s ready, and think about the ramifications.

(of course, you could also do this with markdown;

indeed, somebody — i.e. strapdown — already has.

but if you did, you’d be passing along one “flavor”,

and it’d have to be one with a javascript converter,

so you’d first have to decide what flavor that’d be,

which — if you’re here reading this — is something

you probably already decided you have no time for.

but it’s technically possible to convert client-side.

then again, markdown doesn’t have to think about

what it needs to do to become “viral”; it already is.)

the people, the ports, the path

the people

so, once the z.m.l. _community_ decides that z.m.l. is

solid and ready to roll, we can spread it like wildfire.

but the community must decide z.m.l. has grown ready.

and for that, a community must first _come_ _together._

as i said, i’m ready to listen to the community of users.

but i have lotsa z.m.l. work already, _without_ taking on

the task of organizing the process of such a community.

so that’s something that the z.m.l. community is going to

have to do itself. that’s the first _test_ of that community:

organize yourself, and find a way to talk, and poll yourself,

because we’re going to use polls to assess feature demand.

plus, as i said, there are many holes in the documentation:

some “rules” are not completely nailed down, on purpose,

because we can possibly take z.m.l. in different directions.

and i will listen to community feedback to nail those down.

but first, get yourself organized. i will provide web-space,

and must be consulted, but you’ll have to do the leg-work

of organizing a community that can speak with coherence.

meanwhile, lots of work _has_ been done. much more than

you might imagine, as i’ve worked on z.m.l. for a long time.

so let me hit some high points about the various products

that i will release — in coming days, weeks, and months —

so you have an idea about the path we will soon be taking.

the ports

the next apps to come out are native versions of the

web-app featured above, for mac, pc, and linux. soon!

probably in the next few days, certainly by next week.

check the “news” page (given below) for the details…

and after that, native “preview-apps”, which will convert

an offline text-file, live, as you edit it in another program.

the preview gets auto-updated whenever you save the file.

since these are a variant on the native apps just mentioned,

you can expect them very soon as well, say within 2 weeks.

on online authoring-tool, saving files online, should also be

available quite soon. i already have various versions of these,

so i just need to implement the latest code into one of them.

so once again, you can expect to get that within a few weeks.

as a function of the online authoring-tool, we’ll have an a.p.i.,

you will send it z.m.l. input, and the a.p.i. will send back .html.

this means you can incorporate z.m.l. into your own tools and

not have to bother with any of the details of doing conversions.

this online authoring-tool can also be used for live-previewing

of online files, redoing the preview whenever the file updates.

of course, we can also have the native preview-apps monitoring

an online file — or dozens of online files — if that’s useful to you.

as you see, many of these capabilities “piggy-back” each other,

so there are lots of different functionalities that we could offer,

if you have a use for them. i encourage your imagination to run.

the path

here’s a “top-20" list of the ports that will be done next,

and thus represent the “path” that this project will take.

indeed, a good number of them have already been coded,

and nearly all of them have been the subject of a first pass.

if you’d like to volunteer to steward one of these, please do!

of course, as i mentioned above, the javascript converter is

probably gonna be the key to a viral explosion of z.m.l., but

we’ll also have parallel converters in other languages for you.

however, do *not* proceed on your own coding a converter;

public forks of z.m.l. are actively discouraged and denounced.

don’t make a public fork, and don’t support anyone who does.



1. introduction/documentation to .zml

2. rules/samples/test-suite for .zml 3. offline authoring-tools

4. mac jaguar.app

5. windows jaguar.exe

6. linux jaguar.linux 7. online tools

8. web-based authoring-tool

9. web-based live previewer

10. web-based a.p.i. 11. ios tools 12. the .zml converters:

12a. javascript (client-side & server-side)

12b. python

12c. perl

12d. php

12e. ruby

12f. swift

12g. xcode 13. there is no #13. 14. output formats:

14a. .html5

14b. .epub

14c. .mobi

14d. .kf8

14e. .pdf

14f. our own online book-paginated format 15. .zml instructional(s) 16. slideshow output:

16a. reveal

16b. bespoke

16c. impress

16d. deck

16e. etc.

16g. again, our own dogfood 17. more viewers and previewers, offline & online



18. cloud-based storage (e.g., dropbox, icloud) 19. eventual github deposit (for archival, *not* forking) 20. community suggestions, requests, and demands



***

i’ve sat on z.m.l. for a long time, figuring that the world

wasn’t quite dissatisfied enough with markdown yet to

seek out a replacement. but the commonmark brouhaha

has led me to wonder if the tipping-point of time is here.

if not, i’m fine with putting it back on the shelf until later.

but if a community of people is ready to move on with me,

let’s go…

***

i will put up ongoing news about all of the projects here:

> http://zenmagiclove.com/simple/zml-news.html

you can reach me via e-mail at bowerbird at aol dot com.

(oh, and if you think you can tease me about being on aol,

think again, chum. i’m tremendously proud i’m old-school.

i’ve had that address for 20 years. how long you had yours?)

***

that’s all for now! keep in touch with zen markup language!

***

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

beyond markdown — part 11 — congratulations on your commencement

https://medium.com/@bbirdiman/beyond-markdown-part-11-444393af1ed0

***

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