FAQ

Why not just use Google Docs, Microsoft Word, Open Office or some other word processor?

A number of reasons:

  1. Compatibility
  2. Stability
  3. Sustainability
  4. Versioning

The short answer is for all the same reasons that software developers have been using it for the last decade. It is extremely rare to find any software documentation written in anything but Markdown these days. Most software development teams would literally laugh in your face if you asked them to document their work in a word processor of any kind.

šŸ’¬ There are ancient institutions and enterprises that still have ridiculous Word templates for everything but agile companies that are dominating the industry are way beyond those outdated and unsustainable practices.

Compatibility

Despite what many would have you believe these tools are not compatible with one another. The document format underneath what you see is wildly complicated, unnecessarily.

Stability

With all that bloated unnecessary stuff comes a high-degree of risk that stuff just won't work as expected. That you will get weird formatting conditions and bugs and spend all your time learning how to keep your word processor from crashing.

Sustainability

BaseML is the closest thing to digital paper that there is. It is 100% CommonMark, the closest thing to a web content documentation standard the world has ever known. It is universal and supported by every major text and word processor there is. You never have to worry about your content being held hostage by the eventually outdated applications you created it with. This is particularly important for educational content and the reason BaseML is the core language for all SOIL module knowledge source.

Versioning

Keeping your knowledge source in this most basic form allows it to benefit from all the same approaches and tools that software source code does including versioning. There is no need to lock into a specific word processor's way of implementing some substitute for version management that resemblesā€”even copiesā€”the real thing used for the world's leading software source repositoriesā€”primarily Git. For example, you can review the entire change history of this content using the world's leading source management service GitHub. But here's the amazing part, anyone with a copy of that repository has all that same history as well in an internationally recognized format and open standard for source management. You will never get that with a word processor.

Why not use Ogg format for sound and video?

Because you no longer need it. No one does. The MP3 licensing officially ended on April 23, 2017.

BaseML is hard to read with just a plain text editor.

First of all, that is not a question. šŸ˜

You have to remember the priority of BaseML is not source readability, it is primarily convenience in writing and efficient parsing and assumes you are using a modern editor with line wrapping capability.

If your priority is readability of the plain text source perhaps stick with CommonMark or Pandoc or the IETF document specification.

Why not just use CommonMark?

BaseML is not CommonMark. The elimination of many things and the inclusion of front matter and contextual smart quote conversion prevents this, strictly speaking. BaseML is, however, compatible with most CommonMark and Markdown parsers out there, such as that in Microsoft Visual Studio Code.

The CommonMark JavaScript parser is 63KB gzipped.

CommonMark is great for larger documentation projects, as is Pandoc, but BaseML is designedā€”above allā€”to be the simplest and compatible with services such as Medium.

A BaseML rendered document can be cut and paste without alteration directly into the Medium (and other) editors. CommonMark cannot.

The CommonMark team is aware of these limitations to the historical Markdown implementation and written up a great summary of the challenges which BaseML addresses directly by simply removing the complicated options entirely.

You can use plain text for your links if you simply want the text of the link available to the reader, but you can never assume it will be autodetected and rendered as a link. BaseML prefers doing things such as this explicitly. So if you want that URL to be linked you could include it in a standard link as the text for the link.

Does BaseML impose any particular writing style?

No. But we recommend the SOIL style standard which prioritizes screen rendering.

Why did you include smart quotes in the standard?

Typography matters.

Smart quotes have been the defacto standard in most word-processors for years. So much so that they have been blamed for potential changes in accepted punctuation rules. The errors, however, could have easily been avoided by writers and editors simply using a single right quotation mark instead of the single "dumb quote".

Most Markdown parsers and renderers have a smart quote option. The only difference with BaseML is that they are built into the standard so the method of evaluating them can be relied upon by everyone using a compliant parser and renderer. This is particularly important because smart quote conversion in the wrong place within any document can be catastrophic. By including them in the standard we specify precisely where they will be evaluated and where they will not. All other Markdown versions lack this important specificity.

Why did you exclude ...?

Nothing else from any markup claiming to be Markdown compatible is allowed. Specifically this means the following are not allowed in BaseML. Usually you can use many of these with other versions, just not BaseML. For this reasonā€”combined with the emphasis on quickly over clearly written sourceā€”the name ā€œMarkdownā€ was dropped.

Carriage Returns

Thankfully modern plain-text editors use only a single line return (\n). Those that do not are simply not modern and should be avoided unless they improve. Removing this redundancy simplifies parsing for everyone. Eliminating them means the raw files are always consistent. They are easy enough to remove before sending them to any compliant parser.

If detected compliant parsers must fail with a syntax error.

Tabs

While it is understandable that tabs are used for come programming languages, when writing a BaseML plain-text document tabs have always been problematic because the distance of a single tab can vary both while editing and when rendered. All modern editors seamlessly convert from tab to spaces.

If detected compliant parsers must fail with a syntax error.

The Byte Order Mark (BOM, U+FEFF) Byte

The BOM must be supported by anything that supports UTF-8 but it is always optional. Please do not add it even though all EzMark compliant parsers must account for and ignore it.

When present it must be the first code point in the file or stream and will be ignored.

Custom Containers

::: some
:::

While these are very useful when creating Vuepress documentation they're not specifically needed nor standard. Use an initial contextual emoji with a normal blockquote instead:

šŸ’¬ Like this.

These will not raise a syntax error but will be simply passed as text.

Use of Underscore for Formatting

Not only is this incredibly ugly and slightly harder to type. It is simply redundant and unnecessary.

Strike-Through.

This extension to Markdown is unnecessary and problematic when considering content that might be voiced. Essentially the same could be written out as the following:

I hate, um, I mean *strongly dislike* ..

Some argue that errata in a document justify it, but in every case an italicized update and explanation are always better.

Unordered Lists

Anything but * is unnecessary and redundant.

Ordered Lists

Not only is anything but 1. unnecessary and redundant but it stops renderers from using another language with a different numbering system. Think of 1. as a token and not a number.

This particular point in Markdown implementations is all over the map. Some allow using different numbering systems by changing the 1, others use the initial number to indicate what to start on and then the next one is the amount to increment by, still others do not respect different numbers forcing their own counting.

The simplest solution to all of this is to force it to 1. and just know that counting will begin at whatever the number one is in the target language.

Nested Lists

More than one study has shown that nested lists are too dense for most reasonable reading unless it is in a table of contents specifically. Medium agrees.

One level of nesting also makes text-to-speech seem more natural.

Nested Blockquotes

Nested blockquotes might have occurred in 1990s emails and newsgroups but they are no longer useful. Why would we want to encourage cutting and pasting from deeply nested email threads anyway? A better approach is to isolate any specific quotable content of value and put that into a single blockquote.

Tables

Tables have dubious value both in HTML and Markdown. They are unresponsive, take longer to render than div in HTML, and are usually far too dense to provide meaningful content to the reader. This is why Medium does not support them.

Instead, if such a graphic is required put it into an image instead, which is equally easy to maintain and provides consistent appearance.

Or, if you insist on using them compose them in HTML, which is ignored, and pass them to a full HTML renderer.

Footnote style link syntax provides a more pleasant reading experience when looking at plain text Markdown source, but it comes at a huge cost in cognitive overhead and efficiency when writing documents because one always has to look to the bottom of the document to check the link.

Also, when that content is cut and paste into another document the footnoted links must be also copied and pasted removing the ease of modularity if the link is place inline instead.

Inline links are far easier to parse programmatically because the parenthesis signals caching of the link URL until the ending parenthesis is scanned. Footnoted links require complicated approaches that wait until the entire document is parsed before the links can be activated. As the length of BaseML documents might be very long, this delays rendering unnecessarily.

Remotely Sourced Images

Strictly speaking remotely sourced images are not excluded, just strongly discouraged.

At worst, remotely sourcing an image is illegal or a method of tracking you (via tracking pixels). At best, remote images are an unnecessary dependency on an Internet connection and usage of bandwidth. If an image is needed it is always better to make a copy (appropriately) and include it locally. If you absolutely need an external link to an image, perhaps because it is dynamically generated, then link to it instead without adding it as a linked image. This has the added benefit of tagging the external link visually in renderers such as VuePress.

Remote images are commonly used on GitHub and other services to display the current status of the project or content. This creates an unnecessary dependency on the Internet which is trumped by the priority of creating offline-first content. This includes all the use of dynamically generated images for things like number of stars or likes or continuous integration testing and the like. If such things are required it is always better to automate the download of such images into the source itself. Web documents are not intended to be pseudo-real-time dashboards for compliance and hit statistics.

Image formats than PNG, GIF, JPG

Strictly speaking other image formats are not excluded, just strongly discouraged.

Raster Only

These raster image formats are widely supported and provide the least complication to both inclusion and rendering. For example, Medium does not support anything but JPEG, PNG, and GIF. A simple screenshot can be added without a problem.

SVG images are not included because of the added complexity required for renderers to parse and render them. When an SVG is needed link to it just like any other file (PDF, etc.).

Videos and audio formats other than MP4 and MP3

Strictly speaking other video and audio formats are not excluded, just strongly discouraged.

MP4 and MP3 are the world standards and free from any licensing restriction at this point. BaseML promotes one best solution and standard where one clearly exists.

Horizontal Rules Other Than Four Dashes

Redundant and unnecessary.

Typographer shortcuts: (c)

Use either the text standard or an standard emoji directly.

Inserted text

Unnecessary and never part of the original.

Marked Text

Unnecessary and never part of the original.

Emoji Escapes

Defunct now that editors can directly insert the emoji.

Emoticon Shortcuts

Defunct now that editors can directly insert them.

Sub and Superscript

Unnecessary extension and not part of original Markdown. Use a UNICODE character instead.

Footnotes

Unnecessary and never part of the original.

Definition lists

Unnecessary and never part of the original.

Abbreviations

Unnecessary and never part of the original.

Backslash Escapes

The minimal nature of BaseML means that backslash escapes are simply not needed.

Initial Whitespace

Unnecessary and makes source editing more difficult.

Line Returns

John Gruber made Markdown at a time when editors were not nearly as capable as they are now. Plus he intended to make Markdown source as readable as any rendering of it.

Times have changed and EzMark prioritizes speed of writing and parsing at the slight cost of some source readability (which does not seem to bother most people since most Markdown in the wild does exactly that today).

All modern editors support soft-wrapping leaving a line return useful for inserting a hard line break (which can optionally include two spaces before the line return to maintain CommonMark compatibility).

Supporting line returns in any other construct unnecessarily complicates both parsing and consistent writing.

These are redundant, slower to type, and ugly despite their increased visibility in the source.

Although no one uses them much in practice. Links in CommonMark are allowed to have a space and a title. BaseML does not allow this.

HTML, XML, Latex, KaTeX, MathML

These are parsed but ignored by most BaseML renderers. This allows BaseML parsers to pass off rendering of this content to other renderers or plugins.

Code Syntax Hilighting

One of the biggest diversions from the original intent of Markdown is the addition of syntax hilighting by parsing the contents of code blocks into any of a number of different HTML markup interpretations. This has never had any place in any Markdown standard or parser but can easily be added through render pipelining.

Last Updated: 1/1/2019, 7:37:24 PM