Posted on

## MediaWiki vs. WordPress

There of course is no MediaWiki vs. WordPress in the sense of a battle. As Wiki and Blog platforms go, each is the winner in their category in terms of raw number of users/pageviews. That said, there are definitely (different) concerns with each platform, architecturally as well as accidentally. And therefore, we dreg up the battle metaphor. To the fighting pits!

## Markdown vs. Wikitext

Markdown isn't the default in WordPress, indeed there is way too much emphasis on the visual editor. That said, Markdown is common and available via plugins, and shortcode functionality is also prevalent. For MediaWiki, the wikitext markup remains dominant, to the exclusing of Markdown. But no where else than MediaWiki is wikitext deployed.

## Namespaces and Transclusion

MediaWiki namespaces are ways of organizing kinds of documents (sometimes without much real effect other than naming), as well as allowing for transclusions and templates. For WordPress templates, or better custom post types, are monolithic and govern an entire page of a certain kind (for example, products). While custom posts and templates are distinct, and there can be more than one template for a given custom post type, they essentially are managed as an area for programming, vs. the looser, and easier to edit templates (powered by WikiMedia transclusion extensions), so that moderately capable editors can customize the look and feel of pages without needing administrative access. This gives MediaWiki a more democratic and flexible system, that however ends up creating an additional level of administrative editing work. I've you've got millions of editors, this is fine, and necessary, but if not, it becomes more difficult to manage.

## Caching Techniques

MediaWiki has some built-in caching, and for WordPress this is the domain of plugins. Still, these sit on top of PHP, MySQL, and Apache, so the caching strategy is the same.

## Themes and Skins

Themes in WordPress are where the look and feel, layout and design live, while for MediWiki these are skins. As with most things CSS (and a little javascript), the customization can be extensive. The trouble with skins, besides the fact that most are very ugly, is that the paradigm of the Wikipedia page generally dominates. Wikiwand has gone far to beat back that design, and done so effectively.

## Templates, Templates, Templates

Templates tend to grow like mushrooms. For example this page has 53 templates. There are mainly just a few template types: - Page or fragment formatting templates - Info-box style templates - Weird parsing or inclusion templates From an architecture perspective, this is obviously nuts (a technical term). First off, getting down to the root of it, there should be widgets, templates, and plugins. While certainly it is convenient that this is the WordPress model, the reality is that not managing these issues site-wide is a recipe for disaster. One ends up with... 53 templates. Bartleby the Scrivener, indeed.

## Javascript and CSS

For WordPress, including javascript and css is generally straightforward, and there are plugins such as the masterful HeadSpace which makes insertion of includes straightforward. In comparison, MediaWiki's approach doesn't always work very well. There are the common files, but adding includes is not obvious. Wikia documentation helps out (but again, is incomplate). Technical documentation of MediaWiki is by far the weakest and most troubling part of the distribution. Technical documentation is either non-existent, incomplete, or out of date -- usually a combination of all three.

## MediaWiki and WordPress - Deep in Technical Debt

The attempts to make sane improvements to MediaWiki and WordPress (and most recently, WooCommerce) have exposed an enormous amount of technical debt. MediaWiki makes mention of this, but their attempts to address this are essentially don't touch what we can wait to touch later. WooCommerce 3.0, in less than a month, has released six bug-fix patches, having broken a huge amount of their customer base. The insanity continues on WordPress releases, which no longer have timelines (only some kind of undefined feature release rationale).

## A Revisit for Sanity

Both MediaWiki and WordPress have extremely poor core technology stack, and while it can be made to work and scale, the process is generally painful. In addition, with core version control distributed collaborative editing and website display, there are few reasons not to build something that can fix both of these problems, provided the core functionality of both applications is built first, and the architecture is thought out better. This should fix speed issues and caching issues.

## Challengers and Replacements

Because part of the issue has to do with the database requirements, flat file systems have a distinct advantage. Additionally, active, full-featured projects that are able to do some kind of migration/import, are a strong consideration. Two in particular are: - WordPress / Woocommerce --> Grav / Gravcart - Mediawiki --> Dokuwiki

Posted on

## Status of Copyright – Nov 2016

There have been several developments regarding copyright law, the most profound being that TPP appears to be dead in the water. TPP copyright provisions would have negatively impacted many countries in terms of costs to consumers, including Canada, Brunei, Japan, Malaysia, New Zealand, and Viet Nam. - A New Zealand analysis disingenuously compares Australian with New Zealand impacts and claims that the New Zealand impact is less believable because it is three times per capita of the Australian estimate. However, Australia has less to implement, specifically the Life + 70 provision for copyright length (Australia already has this, New Zealand has Life + 50). Nevertheless the costs are high, at $55m NZD for New Zealand, a country with 4.5 million population, and$ 88m AUD for Australia, a country with 23.1 million population. Canada's cost based, on the New Zealand study, is set to be around \$ 454m CAD, for a population of 35.2 million. - However, because John Key and his corrupt government is in the pockets of big media, they have actually passed all provisions required to meet the TPP guidelines, even after Obama has called an end to TTP promotion and the president-elect of the United States has campaigned against TPP and made a statement after the election that he will withdraw from the TPP in the first 100 days. Really this is a time-wasting exercise since these new provisions become law only if the TPP comes into effect, which requires 85% of GDP signatories, and without the US, that bar cannot be passed. Still, the political language is unclear and copyright length in particular may be extended without any reference to the TPP. - Note that this is the same government which implemented an ebook tax of 15%. Since this is collected by ebook providers (specifically, the big five of ebook publishing: Amazon, Apple, Barnes & Noble, Kobo, and Google) - Japan is in a particularly difficult position with extending copyright length as well as other provisions, as there are healthy creative communities which rely on current protections and fair use. Anime and Manga are particularly at risk. In addition, any benefits to Japan and Japanese creators would be far outweighed by increased costs largely to the United States media companies. Not only would certain creative traditions and markets be made illegal based on an alien law foisted upon them -- a law whose passing in the United States was solely based on the vast lobbying funds of the US media conglomerates. This is a corporate power and money grab of historic proportions.

## WIPO Marrakesh Treaty Comes into Effect

In September 2016, Canada became the 20th signatory to the Marrakesh Treaty of the World Intellectual Property Organization (WIPO). This is the first WIPO copyright treaty which expressly promulgates limitations and exceptions for consumers, rather than increased property rights for creators. Marrakesh becomes effective 30 September 2016. Fifty one countries were signatories to the treaty, and twenty countries have ratified it, including: Argentina, Australia, Brazil, Canada, Chile, Ecuador, El Salvador, Guatemala, India, Israel, Mali, Mexico, Mongolia, North Korea, Paraguay, Peru, Singapore, South Korea, United Arab Emirates, and Uruguay. Marrakesh is not a law, per se, but rather a requirement on countries to include in their copyright laws, specific provisions regarding accessibility to works for the blind, visually impaired, or otherwise print disabled.

## Purpose of Text Style Guide

This Text Style Guide is for all textual communication including email, website, social media, brochures, ebooks, etc. as well as all printed material. This guide includes markup style and writing style. Markup Style Google Docs will be the primary repository of edited documents. However, there are additional editors which can be used, with documents saved in Google Docs and/or Dropbox. This is based on writer choice. Markup using Google Drive First, turn off the Smart Quotes and Automatic Substitution in Google Drive: (TOOLS > PREFERENCES). This needs to be done one time apparently for the user. So open a document, change the preference, close the document, then open other documents the setting should remain changed.

## Markup using WriteBox

Writebox has several options including iOS, Android and Chrome apps as well as a generic webapp. It is fast and works well, though it does not have a side-by-side code/preview pane as Stackedit supports. Writebox also supports Google Drive and Dropbox storage. http://writeboxapps.com/

## Standard Markdown Syntax

## H2 (subheads) ### H3 (sub-subheads) *italic* italic **bold** bold - Bullet - Bullet - Bullet - Bullet > Quote (use this for callouts, note that this can wrap but if there is a new line, there needs to be a new greater-than sign and space. > For multiple paragraph asides, there needs to be another right angle bracket + space for each subsequently indented paragraph or element. > > This would be a second paragraph. It is suggested to have a line space between paragraphs, but there should not be when dealing with such things as bulleted lists, such as: > - This is the first bullet point > - This is the second bullet point NOTE: the Quote format should be use for "Asides" or "Side Text". See also "Callouts/Pullquotes" section in the writing style guide below. Tables Item | Value --------- | ----- Item A | 1600 USD Item B | 12 USD Item C | 1 USD Specify column alignment with one or two colons: | Item | Value | Qty | | :-------- | --------:| :--: | | Item A | 1600 USD | 5 | | Item B | 12 USD | 121 | | Item C | 1 USD| | 234 | (Left align, right align, center align) Comments We can use the extended HTML comment syntax. Note that there are three hyphens ("-") on the left side, and two on the right site. There should be no spaces between angle bracket, bang and hyphen on either side. For readability there should be a space separating the actual comment from the comment markup: It is best to have an extra line spacing between the paragraph text, the comment, and the next paragraph text. When using this comment markup, in Multimarkdown and Pandoc, the comment is stripped out of LaTeX generation (given directives) but does not show up visibly in preview (though it does exist as an HTML comment, therefore invisible). In Stackedit.io the comment apprears as highlighted in red, but in Writebox it does not display (being treated like raw HTML markup). Footnotes, Citations and References To make things easy, we will use a simple footnote syntax for all citations, glossary terms and references: Some text1. Final sentences at end of the paragraph.

1. Here is the text of the footnote. Note that the [^footnote] name can be named anything (no spaces or numbers, prefer lower-case, short, descriptive of the source and the information. Note also that there needs to be an extra blank line between these two lines, as well as an extra blank line to begin the next paragraph. Third note: the footnote text should not be placed at the end of the edited chapter or book, but rather in the immediate vicinity of the initial footnote indicator. Automation software (XeLaTeX) will be used to move it to be an in-line footnote, an endnote, or a chaptered end-of-book footnote, as needed. Note that Stackedit is "smarter" than the markdown parsers we use on the website and also when generating pdf/epub. So we need to use the "dumber" syntax as found in the style guide. There are two problems. The first is that the footnote link is not in a lowercase-plus-hyphen source description format. The second is that the URLs being put into the footnote text are not being marked up as URLs. Again, Stackedit can deal with this, so it looks ok in that editor, but other parsers cannot. Below is an example of your markup, and corrected version to use. CURRENT MARKUP ... a staggering 400 million people -- are enrolled in some degree of English-language instruction2. As more people learn to speak English...

2. 2010 data, http://english.people.com.cn/90001/90776/90882/7093494.html CORRECTED MARKUP ... a staggering 400 million people -- are enrolled in some degree of English-language instruction3. As more people learn to speak English...

## As a technique for interviewing, it is a good idea to get some yes/no questions, some “how important is”-type questions, and several open-ended questions that may result in useful information not previously known to the interviewer. Get permission in writing to use the interview. We can provide anonymity to our sources and still use their words and ideas, but we still need written permission. Anything said in public does not require the same level of permission, but it is always good to seek this out.

This Document Part of a Complete Set of Style Guides

Posted on

## Video Workflow – Free Tools

The best part of video is how convenient it has become. However, it is still a lot of work. The tools I like to use also need to be fast... and free. This is an important aspect of liberty. Even for short videos there is usually a combination of images, video clips and audio that needs some kind of manipulation. I've got a quick workflow that seems to do the trick.

The key to this is the YouTube video editor, which enables very fast splitting and combining of video and also the creation of single image video segments as well as slideshow videos. Where this falls down is on the audio side, as YouTube does not allow (though it once did some time ago in the past) the uploading of one's own audio (apart from audio already embedded in an uploaded video).

## Creating Audio files for use in YouTube

To get your audio up so it can be added to YouTube: 1. Create a black image 1920 x 1080 (Inkscape or Gimp) 2. Upload to YouTube in the video editor 3. Drag the image into the video timeline, and extend the image time from the default 5 seconds to the length of the audio track 4. Create the video (set to private) 5. Download the video 6. Open the video inside of Avidemux 7. Add the audio track 8. Set for MPeg4 AVC (x264) video, AAC (Faac) audio, MP4 Muxer output format 9. Save the video 10. Import that back up to YouTube Note that there is a little glitch in that the audio track must be continuous, so add the same audio but set the volume to zero, so that there is a placeholder. For cutting to a different video (but same audio) of say a narrator, just use multiple copies with segments that cross back and forth from (video + audio) to (audio only) to (video + audio) This may seem like a bit of a contortion, but we are still dealing with a free, fast, web-based video editor.

## Video Editors and Other Tools

• Avidemux is a cross platform open source video editing tool. It does a few things quickly, especially swapping out audio, slicing video into smaller parts, transcoding, etc.
• Inkscape is a fantastic vector graphics drawing tool with PNG output
• Gimp is a painful to use, but fully featured (if you can find out how) image editor and painting tool
• Blender is a 2d and 3d animation tool with a built-in NLE (non-linear video editor). It takes a bit of configuring, but when dealing with more complex issues than a five minute video with a few different cuts, this the tool par excellence.
Posted on

## Audiobooks – Mono in a Stereo World

Audiobooks are generally a neglected/emerging area in much of the world. If one is in the US, of course it is less of a problem, but even Apple has a half-assed approach currently.

## Apple / iOS / OSX

While it appears Apple is trying to get its act together, it is a far distance from right just yet: - On iOS audiobooks are now in iBooks (great!) - On OSX that is not the case. And no iBooks on Windows, much less Android. - Many countries are still not supported for audiobooks (in ibooks AND itunes), as well as various video formats Audible is the only lifesaver. Akin to Kindle for ebooks, with apps for every device, and it happens to be the only way to get an audiobook into Amazon and iTunes (and Audible itself, which has good apps). Note that Audible appears to get around the iTunes country restrictions for content, because the purchase is made at Audible.com (or other market) and then Audible apps are used for play. However, the download via iTunes option that is offered for OSX or other uses likely will fail because of the geographical restrictions at iTunes).

This is of course the worst situation. Audiobooks are in the Music section, and of course some countries do not have music supported (such as Thailand and others). So no audiobook market. Horrible, just horrible. I suppose the best thing is to go through a third party such as Audible, or distribute one's own audiobooks and promote using a third party (free) audiobook player, or create one's own app for the appstore (but again, not where people look for audiobooks).

## Audiobooks, Podcasts, and Spoken Word Music

In sum, audio books can be found in various formats in iTunes (and elsewhere), the technical format can be identical, but the metadata and where to find and what app to use to consume and manage audio books can differ significantly, as well as geographical restrictions. - Audio books are only available as spoken word music in Google Play, as well as suffering from geographical limitations (e.g., in Thailand Google Play Music simply doesn't exist) - Audio books as Audiobooks are available in iOS in iBooks (with geographical limitations) and as Audiobooks in iTunes for desktop (OSX, Windows) - and Apple uses Audible as the exclusive publisher of Audiobooks - Audio books as Spoken Word Music are available in iTunes (all platforms), and can be accessed through various third party aggregators, such as cdBaby, RouteNote, and Tunecore. - Audio books as Apps are available through various app stores, though one would need to build the app themselves. This is an interesting option, in that audio, text, and some kind of synchronization between the two could be useful (one could easily switch between reading text and having audio read). - Audio books as Video is more complicated as places like iTunes, Netflix, Amazon and the like are focused on TV and movie formats. Distribution on YouTube makes the most sense, but likely it is still best as a preview/trailer and free content to build leads for sales of other formats. - Podcasts are an older format but it is difficult to monetize on iTunes, as they are mostly and widely considered to be free. Podcasts are really more like radio, and radio is monetized through advertising. It is best to consider

## Thailand Options

Thailand actually has a pretty good option for both ebook, and more recently audiobooks, and that is Ookbee. This is for the Thai speaking marketplace only, but works well. For English-speaking markets, one can only rely on the fact that people would have accounts in non-Thailand markets for iTunes/iBooks and Android, or rely on Appstore apps (Music for Android and Audiobooks for iTunes are simply not available).

Posted on

## Publishing Genre

While there is quite a bit of literary genre everywhere alive and well, there are certain publication genre which are not. The Chapbook (still popular) and the Almanac(k), as well but we don't hear about it much anymore.

## Chapbook in the Age of Print-on-Demand

The Chapbook seems like a wonder in the age of Print-on-Demand. With a lovely history, the Chapbook nowadays means 40 pages or less. Of course, one can't get a printed binding at that size, and the economics are not very good, but the e-chapbook should be popular, and of course its cousin the essay, may also be making a return. A specific kind of essay, or another cousin perhaps, is the Manifesto, a keen piece of writing which could be presented in Chapbook form. It is my belief we don't have enough Chapbooks, Essays and Manifestos in daily literary life, and instead have too many blog posts, articles, and otherwise unoriginal or spurious content.

## Almanacks for Today

Which brings us to the Almanack, that is of somewhat ancient purview, and deals with heavenly bodies. And of course for Americans, Poor Richard's Almanack is a slice of history which survives to this day. Living in Thailand, the use of lunisolar calendar reckoning is still extremely important. It turns out that when trying to find out when the Chiang Mai Pillar Festival will be held, the Thai provincial government has no idea, but the little old lady selling votives outside the temples has her own book and can indicate with certainty when the fairly significant annual event will be held. Time for more Almanacks, for chapbooks and essays, and for manifestos, of which this is one (albeit small) one.

## Summary

More: - Chapbooks - Essays - Manifestos - Almanacks

Posted on

## Style Guide

This is a permanent page about style guides used in writing and for marketing. In particular there two kinds of Style Guides: - Brand Style Guide (for product designers, pr types, and all public and corporate communications) - Publishing Style Guide (for writers, editors, publishers) These two intersect and the Brand Style Guide should refer to the Publishing Style Guide.

## Publishing Style Guide

This includes all forms of media (text, audio, video, graphics) and includes those elements and forms usually covered by manuals of style. Included are such things as spelling preferences, form of English (American, British, etc.), punctuation (Oxford comma), preferred voice/pronoun use (3rd person). As well the kinds of markup used (PHP Markdown Extra) and preferred editors and other writing and publishing tools. Workflow can be included in the Publishing Style Guide to some extent, but likely is best in a separate document, titled Publishing Workflow.

## Brand Style Guide

This includes all forms of media related to the brand imagery including graphic logos, typography, color palette, as well as contact information and other standardized corporate boilerplate. Everything about the brand name and visual and interactive personality should be included. Also such things as the corporate mission, vision, tag-lines, and the like, as well as things like business card templates, letterhead, etc. - Example of color palette

Posted on

## Update Mar-2018 - I'm going with Caret which is both a desktop markdown app, as well as an (unrelated) chromeOS app. I still like Atom, however, it's still great!

For Open Source, Atom is a great editor (Brackets is another). But there are still a few warts, and of course plugins must be used for full functionality. All can be installed with: > apm install APPNAME

apm install autosave
apm install dash
apm install language-latex
apm install markdown-preview
apm install meteor-api
apm install meteor-helper
apm install meteor-snippets
apm install sort-lines
apm install tree-ignore
apm install wordcount


Note that for autosave, need to toggle it on in the settings For themes, I am going with the simple Atom Light UI and Solarized Light syntax. To open atom, do it from the command line, by cd-ing into a given directory, then invoking it with: > atom . This will support multiple windows/directories with open tabs. Another problem currently is with printing, but that we can work around by shoving things through pandoc in the meantime.

Posted on

## Markdown Specifications and Editors

Note: This post is nearly two years old and in need of a revamp. It is too longish but most of the information is there. Need to do a few things: - Remove any redundancy - Reorganize with a table of contents - Rename markdown: Original, Standard, Github, Stackedit, Extra, Markua - Note that standard is simply the specific syntax that will work on all the implemenations - Focus on fenced codeblocks vs. publishing-specific extensions (footnotes, figures), as well as including things like html anchors and css classes - Python implementations - Editors: Atom, Stackedit.io, mobile apps (?) - The comments crap below can be removed, it is too tedious - Do integrate fountain (screenplay markup), and look closer at markua for this - This: and

## Begin Article

Markdown, a sleepy little implementation and thousands of related projects has finally metastasized into several projects/collections aimed to provide better guidance. Basically it is growing up, Gruber be damned. As such, editing (and storing) markdown text is important as well.

## What to Know - Markdown and Editors

Below are more resources, but in simple terms, markdown (now wrested out of Gruber's grasp), however it may be called or named, is the means by which we edit text that will be displayed in books and on the web and mobile devices. Yes, there are helpers and complementors, and TeX/LaTeX/XeLaTeX does not go away (but becomes more important). So, all writing should be in this format, get rid of the WYSIWYG, stop using Google Docs, get everything into plaintext with simple markup. True, there are problems with spreadsheets as they don't markup easily/well, but we'll deal with that later. Editors should be open source, period. Yes, we can use cloud services, but all data in the cloud should be (with minor exceptions such as configuration) downloadable and editable offline (and of course portable, that is in plaintext). Github issues is a great example: - Offline Issues - Issues Sync So, we go with the Atom editor. If that makes us a Github fanboy, so be it.

## Retarded Markdown

Markdown qua Markdown has been retarded since birth (or slightly thereafter). In that sense it is kind of a dwarf or a little person. That is, it can do some things, but not the kind of workload required of the fully grown. People make a big deal out of Markdown not being broken, and it certainly isn't, when taken at face value and measured at the level of a dwarf. But we need more grown up and developed markup in the modern world, and all the grafted-on appendages will not due. Hence the proliferation of Markdown extensions. People call these flavors, and they are certainly enhancements to make Markdown taste better (or really, become more functional). But this grafting on of limbs always has the feeling of personal modifications and the result a beauty contest between Frankenstein monsters.

## Recent Developments in Markdown

Interestingly, there are two significant developments in Markdown, a more-fully-specified Markdown syntax called Common Markdown and an IETF/APPSAWG Markdown media type draft. Both represented long-needed steps forward, Gruber be damned. CommonMark has both C and Javascript implementations of Markdown as well. These changes are significant in that, text/markdown can be recognized as a media type, that is a label for content, such as that transported via HTTP/HTTPS. So better, let's start with a plan, not to operate on the small historical body of markdown, but to see it as a single species in a world of evolution, and to learn better and more from its better adapted cousins. Namely: TeX/LaTeX/XeLaTeX, HTML, and ePub (a form of HTML). For this is where we have come - Example of simple need to extend markdown but with the incessant rejoinders that extending it makes it not markdown

## Markup for Publishers = MarkPub

What we have are several standards that we use, as well as specific needs (publishing, though that could be considered to be quite broad). And so, we can produce a markup which can be used in these cases (and possibly others). There are several limitations of retarded markdown vis-a-vis html which make for an easy target, specifically the use of CSS classes.

## Math Issues

MathJax (see StackEditor implementation) vs. MathML vs. other such...

## Commenting

Some text1. Final bit of text for the paragraph.

# Header


### Ordered and Unordered Lists

Ordered lists are numbered lists, and unordered lists are bulleted lists. Bulleted lists are to be created using the minus sign.

- We suggest the minus sign, as it is easier to type than a plus sign
- And will not be confused with the asterisks used for bold and italics


Whereas ordered lists have actual numbers and periods in them (though in fact ordered lists ignore the actual number and create a new numbered order starting at 1).

1. The first item
2. The second item


### Bold and Italics (aka Strong and Emphasis)

*Italics*
**Bold**
***Bolded Italics***


Notes: For a while I was using underscores (_italics_, __bold__, and ___bold italics___) but I ran across some incompatibilities in some markdown implementations. At the time I was also using * as bullets, but prefer to use a character to mean only one thing in the Bland syntax recommendation (either bullets, or italics/bold, but not both). If you can support both formats, then that would be the most compatible and portable in terms of markdown marked up content. For more about _ vs * for em/strong See: Commonmark discussion. Note that it is useful to go back to the typewriter, which had only two options: - Underscore was used for emphasis, which has now become italics in printed material (and on the web is replaced by html markup or a typeface), though some typographic philistines still use underscore. - ALL CAPS was used for STRONG, which still exists but is largely replaced by bold strong (which is now, as with italics/emphasis, in html markup or a typeface). Bland Markdown is a syntax recommendation that tries for compatibility and portability of content across systems, which is why we want to use asterisks for both italics and bold, as it behaves more consistently, and has the merits of providing a better visual indicator in untransformed text (along with a hyphen used for unordered list items).

### Images

> ![Alt text](URL to image) optionally include a title > ![Alt text](URL to image "Optional Title") Note also that we do not recommend any kind of Figure markup, as this is not straightforward and can best be handled manually (in a separate paragraph, say with manually numbered and italicized text) or with external scripts. - Thanks to Andy Van Den Heuvel of Shuttle for pointing out that Alt Text is required in HTML. Another great feature of Markdown Extra is the ability to add classes and IDs, such as: > ![Alt text](URL to image "Optional Title"){.img-right} This would add class="img-right" which in the css style could image float right. Note, if you wanted to have an image link to a different image, the syntax can follow this image style guide: > [![](/images/mcneill/2016/future-of-the-desktop/intel-compute-stick-t.jpg > "Intel Compute Stick"){.img-right}] > (/images/mcneill/2016/future-of-the-desktop/intel-compute-stick-l.jpg > "Intel Compute Stick") (Note the code here has been artificially truncated for legibility, the four lines above are a single line.)

### URLs

URLs are either plain (where the link text is nearly identical to the URL) or with custom link text. In the case of plain URLs, simply enclose in angle brackets (less than and greater than signs), as such: >  > Hence, If URLs have link text, then use the image markup, minus the exclamation mark, as such: > [Jeff Mcneill](https://jeffmcneill.com) > Hence, Jeff Mcneill

### Code Blocks

Paragraph-level code blocks simply have four spaces to begin each line, whereas inline code is marked up with backticks, as in: > This is marked up code Escaping backticks is performed by using double backticks to enclose the code block and inside single backticks will be exposed as literals.

### Fenced Code Blocks

Fenced code blocks come in many flavors: Github, PHP Markdown Extra, Pandoc (a superset) and MultiMarkdown just adopted the Github style of fenced code blocks (following Github). Four spaces or three backticks and a newline provide Github style, as well as some syntax highlighting by naming the code being fenced. PHP Markdown Extra uses three tildes, and also supports class naming (as does Pandoc).

### Line Breaks

Handily, line breaks can be instituted by typing two spaces at the end of a line. For visuals, simply add a single hard return after the two spaces, and not two hard returns as normally to institute a paragraph break. Note: This alone (the use of two spaces to create a <br />) should be a caution to people who have the unfortunate two spaces after each period habit.

### Horizontal Rule

Five asterisks separated by two hard returns above and below is the most compatible format, as such: > *****

### Quoted Text

Taken from email correspondence, quoted text simply has a greater-than symbol &gt; and a space for each line, as such: > &gt; Quoted text

### Tables

Tables are trouble for several reasons. While Markdown is an improvement over basic HTML, tables are difficult to edit in terms of viewing the data. Also, not all Markdown flavors support Markdown inside of the tables, and there is also a variety of formatting that would need to be done in raw HTML. Finally, there are many viewers, i.e., early ebook readers, which do not deal with tables well if at all. Therefore, most tables are best rendered as images and then used and shared as such. That said, sometimes an HTML table is something to have. Therefore we suggest the following syntax: > Right | Left | Default | Center > -----:|:-----|---------|:-----: > 12 | 12 | 12 | 12 > 123 | 123 | 123 | 123 > 1 | 1 | 1 | 1 Renders as follows:

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

## Bland Markdown Extended (aka Spicy Markdown)

There are two kinds of extensions to Bland Markdown, one for the web, and another for print/epub (sometimes for both). In the future, this may be dispensed with, but each has some requirements that can both be met. A full implementation of Spicy Markdown (SM) will be developed in 2014.

### Superscript and Subscript

MultiMarkdown recently adopted a similar syntax for superscript and subscript to that of Pandoc. For syntax, use carets or tildes, as in: > x^2 or x^2^ > y~z or y~z~ The single delimiter terminates at first whitespace or punctuation. Dual delimiter allows for punctuation to be scripted, but not white space.

### Footnotes

Footnotes are supported similarly (though not identically) in PHP Markdown Extra, MultiMarkdown and Pandoc. The markdown consists of a named footnote marker (rendered as a superscripted number), and the footnote itself. > [^footnote-name] > Hence, [^footnote-name]: Footnote text

### Math Formulas

We recommend the use of LaTeX (XeLaTeX) and for the web some kind of plugin to parse the native LaTeX markup, such as Enable LaTeX or LaTeX for WordPress.

This part is left to be done, including Pandoc, MultiMarkdown and LaTeX document metadata styles.

### CriticMarkup

As more applications integrate CriticMarkup this somewhat unwieldy markup, it can be used (or perhaps a more streamlined version).

### Image Markup

A part of the syntax recommendation should also be image naming and location, but that is more along the lines of a Common URL Structure. Another key factor of image markup has to do with captioning as well as figure numbering. This can be done in CSS (for x/html/ebook implementations) as well as LaTeX, but there should be something that works well in Markdown. Unfortunately, the MMD syntax doesn't work for Pandoc, or something is screwy. I've got to work this out further. See a fork of the Php Markdown extra... Better would be to also include layout information such float:left;margins 0 10px 0 0. People make a big deal about partitioning this information, but that becomes harder to maintaim. When one is inserting an image, they are thinking about layout and presentation, which is why having that facility is important.

### Video Markup

There is a handy Smart YouTube plugin which allows for appending a v at the end of http of a YouTube video url, and will embed it (along with HTML5 support). Other video sources are also supported. In addition, there are many controls for default site-wide YouTube video settings in the plugin. A better approach would be simply embedding a YouTube video URL within something like [ embed ] . . . [ /embed ]

### Embedded Slideshows

Slideshare slideshows can be embedded in WordPress with a plugin. That supports the embedding of the Slideshare share code for wordpress.com but better is the use of open-source slideshows and/or documents (especially open standards). Wikipedia and other wiki projects have struggled with this with alternative viewers/players and such, but if we focus on syntax there should be some kind of embedding or playing that could have a markdown-like syntax (perhaps in the future). Note also that I've yet to work out Markdown markup for slideshows that could then be converted into X/HTML/ePub/PDF slideshows and then uploaded to Slideshare (to be embedded as such). There are various syntax options out there for this, such as found in Pandoc. TBD...

## Spicy Markdown

Spicy Markdown is a significant departure from Bland Markdown as well as many/most other Markdown implementations. Most such implementations try and limit themselves to the spirit of original markdown in terms of parsimony, and extend it only in terms of some additional incremental (but important) extensions. Pandoc tries to do a bit more. Note: This post is under occasional update.

## Difference in Spicy Markdown from other Markdown

Spicy Markdown is different because it is an attempt not so much to extend Markdown but to create a superset of website tools. It might be better called Spicy Shortcode instead of Spicy Markdown but indeed Markdown is the core markup. Spicy Markdown aims to produce a static html page that is fast, and includes ways of optimizing images for effective display. Spicy Markdown also supports various other kinds of features of Wordress (such as  Continue reading Markdown Specifications and Editors

1. Here is the text of the footnote. Some more text, another paragraph here. ![This is the figure caption][fig_id] [fig_id]: http://mmd.png "This is where the title goes" height=45px width=120px To strike-through text: This is is a test. This is {--is --}a test. This is is a test. To add text: This a test. This {++is ++}a test. This is a test. to change text: This isn't a test. This {~~isn't~&gt;is~~} a test. This is a test. to add comments: This is a test {&lt;&gt;} This is a test.`

## Bland Markdown

As noted, there are various flavors of markdown (see also whatismarkdown.com), including original markdown, as well as Github Flavored, Reddit flavored, StackOverflow flavored, SourceForge flavored, Tumblr markdown (possibly PHP Markdown Extra), PHP Markdown Extra, MultiMarkdown, and Pandoc flavored. This is not to mention supersets such as Maruku and Kramdown.

## Non-Implementation Syntax Recommendation

So, due to this proliferation, we introduce a non-implementation recommendation. The need for this is felt most by editors and writers (and publishers), for whom implementation details are not important, but a single style guide syntax to follow is a necessity. In order for one's Markdown code to be as portable as possible, a single subset that is most widely used is seen as the best approach for an organization as well as individuals who produce and edit Markdown markup now and in the future. Hence, Bland Markdown aka Markdown bland aka Mb.

## Bland Markdown Syntax Rationale

The main features animating the decision regarding the particular syntax of Bland Markdown is to define a set of syntax that is easy to use and edit. This means that in some cases where there are several options for particular Markdown markup, a single markup is chosen for memorability and ease of use, along with the widest Markdown flavor implementation support. We use a modified icon based on the Markdown icon, with the down arrow replaced with a lower case b for bland. Note that a recommended bland syntax is preferable over testing tools such as Babelmark 2 (which doesn't fully work properly as the PHP Markdown is not parsing, as of this posting). (See also the PHP Markdown dingus for markdown reformatting.) Note also that Jeff Atwood tried to do a call for large site users of Markdown to get together and create a standard, which unfortunately has not gotten much mileage, another reason for a bland syntax. Update: this actually did get takeup and became CommonMark. And there are still yet reasons for a non-implementation syntax recommendation, along the lines of a Markdown Style Guide.

## Bland Markdown Syntax

Hash/Pound sign is used to denote H1, H2, etc., as in:

## Publishing Workflow

In rough, this is the publishing workflow that gets books from conception/marketing to publishing and distribution.

## Marketing, Marketing, Marketing

Publishing a book or journal is first and foremost a marketing decision. That is, it has to in some way reach and appeal to a readership, and that includes who are the distributors (electronic and print), who the competitors, and who the market, including market size and pricing considerations.

## Commitment and Timeline

Once really good reasons for publishing are discovered, then there needs to be an identification and commitment to the resources needed to get the book written, composed, and typeset. This includes identifying writers, sources of material, editors, photographers and/or illustrators.

## Collaborative Documentation and Process

At this point, when people agree verbally and by handshake (real or virtual) then the set of documents can be produced and the stages of conceptualizing and concretizing the book begins.

## Brainstorming and Contract Drafts

In step 1 there are three usually parallel discussions: - Legal: This is the publishing contract, and includes who pays, when and how much, and who receives, when and how much, financial and intellectual property benefits - Content: This is the initial brainstorming document, which has content that are then organized into chapters and chapter outlines - Market: Contents and Scope has a marketing part and a finalized table of contents that comes out of the content brainstorming document

## Contract Signing, Chapter Outlines, Style Guide, Progress Spreadsheet

At this stage contracts are signed. Next, chapter outlines are generated from the Contents and Scope document (each becomes an individual document for managing the writing/editing process), including pseudo-chapters such as the introduction, any indices, appendices, and glossary. Next a style guide is finalized, which includes authorial voice, kind of English to be used (US English, UK English, etc.), capitalization and abbreviation rules, as well as formatting style. A figures spreadsheet is created, to be filled in with any images, figures or tables to be deployed in the book. Some of these are known ahead of time, others are thought of as chapters and sections are completed, or as artwork is discovered or created. This spreadsheet also tracks the source of any images, drawings, tables (and table data) to be used. A progress spreadsheet is created, including (at least provisional) due dates for chapter draft completion.

## Publication Kickoff

The writing, researching and figure generation begins in earnest. I prefer meetings every two weeks, though once per week is much better and will move things along. Working with professionals it is possible to do once per month meetings, but less time between meetings usually spurs work along.

## Publication Editing

There are of course several kinds of editing, including copyediting, fact-checking, and also layout and design editing. These should happen in an ongoing process rather that waiting until an endpoint. Memories fade and even written notes are neglected. Make changes as the need for changes arise.

## Publication Finalization

A final approval of the document (preferably confirmed in writing/email) should signal the end of the writing and the clock starting on the publishing process. Getting a draft printed via Print-on-Demand is a good next step to see what kind of errors there are and read something physically in book form. From here it becomes a matter of finalizing the product, getting it vetted by distributors and the submission process. Report milestones achieved on a weekly basis to keep everyone informed of the progress toward publication. Send out draft versions to reviewers.

## Technical Aspects

I've left out a bunch of technical aspects in terms of tools. Partially because people and organizations can use different tools, this is not important. However, for good quality control and a beautiful product, the use of XeLaTeX for typesetting is vital.