Posted on

Pandoc, Markdown, XeLaTeX, EPUB

EPUB documents are essentially a kind of html document as a collection of files which are zipped, and include html, css, and images. There are several ways of organizing these, but the most straightforward is one html document for each chapter (or section), a set of images organized in a subfolder, and a few metadata files regarding the collection. An epub document can be even simpler, and consist of a single html file, no images, and a few metadata files. Generating an EPUB can be as straightforward as editing html and the metadata files with a simple text editor, such as Atom. It is about this point that the simplicity ends.

Install XeLaTeX, Pandoc, Calibre, Atom, Kindlegen

These five tools provide the editing (Atom), typesetting (XeLaTeX, Pandoc), file generation (Pandoc, Kindlegen), and auditing (Calibre E-book Editor).

sudo apt-get install -y texlive-xetex
sudo apt-get install -y pandoc
sudo apt-get install -y calibre
sudo apt-get install -y atom

Note: Pandoc is ancient on the Debian distribution, best to install from Pandoc on Github, or better the Unofficial Nightly Builds. Install Amazon Kindlegen manually - See also the Amazon Kindle Publishing Guidelines

Elements of a Publication

There are several elements of a publication which recur from one publication to another. It is best to get organized. - Metadata: Title, Subtitle, BISAC code(s), pages, date of publication, date of revision, Author, etc. - There are two files for this in ebook generation: title.txt and metadata.xml - Cover image (this will be in several different sizes depending where it is used) - Title Page, Copyright, Dedication, Preface, Introduction, Content (Chapters), Acknowledgments, Glossary, Index - Note that the above sections can be one document, or several documents - Any fonts specifically used/embedded /fonts/ - Additional images (figures, tables) /images/ - Stylesheet stylesheet.css - Table of contents (should be generated) - Note that there are two tables of contents, one automatically created via the reader, and another in html (helpful for pdf files as well). - For a print edition, a full cover is needed, and one will want ISBN barcodes and perhaps a qrcode as well.

Edit, Transform, Publish

Editing all html by hand can be tedious, and certain markup can best be managed with markup tools such as Pandoc-flavored Markdown and XeLaTeX, and text transformation tools such as Pandoc. If no extended external font support is needed, markdown alone and some YAML/XML files are all that is needed. - Note that with XeLaTeX, one can do some extensive formatting, such as ShareLaTeX's nifty sample templates. - For more about Markdown, but sticking with Markdown Extra, which is generally suppored by Pandoc. Steps - Work out the document structure, list of files, get everything in place. - With all files or a set of example chapters, get the epub generation process and specific command line to use - Organize the final epub (and print pdf) into different marketplace versions, e.g., Apple iBooks (epub), Amazon Kindle (print, azw), Google Play Books (epub), Ingram (print, epub), Kobo (epub). For the Thai market, Meb and Okbee. Audio/Video - Create additional audiobook, spoken word, video directories (audiobooks via Findaway Voices), as well as spoken word audio and video distribution on all major channels via RouteNote. Note the shortform video opportunities (30-60 second Facebook, Instagram, Twitter). This is also where Blender creative content can come into play.

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

TPP and Copyright provisions

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.

Writing Style Guide

This Document Part of a Complete Set of Style Guides

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.

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 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, CORRECTED MARKUP ... a staggering 400 million people -- are enrolled in some degree of English-language instruction3. As more people learn to speak English... 

  3. China Daily 2010 data English course enrolment Note that the footnote marker is more descriptive of the source and kind of data, and the footnote itself has more descriptive link text as well as link markup. Images For a book, we want captions to display under the images, so use the following syntax: ![Figure Caption][image-filename.jpg "Figure Caption"] Figure Caption The Figure Caption is written three times (once for the ALT, once for the TITLE, and once for the Caption formatted in italics) it should be the same in all three cases. The image-filename.jpg should be short, descriptive, lowercase and using hyphens between words ("-"). For various reasons regarding Kindle, all images should be .jpg files. Note: There are more sophisticated captioning syntax but our wordpress plugin does not support this, so the text cannot be reused there. See also the Image Style Guide for more information about Image parameters and naming. URLs URLs should be used only in footnotes, not throughout the text. Linked text or if an email address is used, or a full website address: Writing Style Guide Writer Profile The best writer is one who is a dedicated professional, has a thick skin, is detail-oriented and client-focused. This is the writer who can adapt their writing to the style and form needed, and understand that the writing required will help them develop professionally. Because we are focused, some might say picky or detail-obsessed, the writer and the writing reaches a higher level of specificity. This is then recognized by our readers and becomes a part of our brand. Original Writing and Writing Style All writing needs to be original. Paraphrase of ideas and facts is generally fine, especially where a link to the source can be found. These are not research papers, obviously. However, paraphrasing the sentence-level construction should not be done. No chapters or chapter sections should feel like rewritten articles found on other websites. The simple approach is to have unique articles which have different meaning (and therefore will have to have different words). This is actually a lot less tedious than trying to find new ways of saying the same thing in different articles. Writing should be robust and break away from a conventional guidebook style. Each chapter or chapter section should be less conversational and more straightforward and pithy. Easy generalizations that are overly positive should be dispensed with. Words such as amazing, wonderful, great, beautiful, stunning, and the like should be used sparingly, and more subdued adjectives and adverbs deployed, such as interesting, unique, worthwhile, and the like. Significant factual detail - such as that found in historical sections of articles, or detailing climates, or a long list of airports - should be reduced or eliminated. It is enough to point to this information in other onsite articles or other websites. Organizing information in chapters and chapter sections so that each component tells a small but interesting and important story and provides insight and utility. The Lonely Planet guidebook style of including all detail at one-size-fits-all is not relevant for our purposes. Chapter Style for Books Chapters are usually around 2,000-3,000 words. In a 50,000 word book around 20 chapters is the appropriate target. However, the actual material may create shorter or longer chapters, as well as fewer or more of them. Chapters should be ordered in a way that they develop from each other and form a useful narrative. At the same time each chapter should be self-contained as much as possible, and should be meaningful if read alone. Reference to other chapters is entirely appropriate, e.g., "See the chapter on Risks and Hazards for more information about inoculations and other health precautions previous to travel to Thailand". Inverted Pyramid Facts and keywords should be near the front of the chapter, just as they should be up front in a given section and a given paragraph. Supporting information falls below. This is known as the inverted pyramid of journalism. Cultural Elements and Teacher Experiences Two kinds of specific information can be highlighted throughout the book in two ways: in a section near the end of most chapters, or using Asides. These are Cultural Elements and Teacher Experiences. Because culture touches nearly everything, even in chapters where it is not the focus, some elements of culture can be mentioned as asides or perhaps as a section near the end of the chapter. Teacher experiences are similar, that is actual experiences of actual teachers in any of the situations/logistics discussed can be presented, again as asides, or as a section at the end of the chapter. Chapter Summary and Further Reading At the end of each chapter should a summary of 4-7 one-sentence bullet points. This section should have a subhead of Chapter Summary. There should also be a subsection called Further Reading with 2-4 references. Some may be websites, especially Wikipedia pages, but it is strongly preferred to have full-length books or more extensive references. The goal is to provide a short, curated list of references in which the reader would find more information, rather than the same information. Call-Outs (Pull-Quotes) and Asides Some published works use include asides, which are generally used to introduce new but tangential material, examples or stories/references. Some works use call-outs (sometimes called pull-quotes), which emphasize a particular part of the text, usually a prominent statement or quotation. We want asides in our work, but want to avoid call-outs. From one to five asides can be used in a given chapter. An example would be reference to a scientific study or publication that might illustrate a claim being made in the text. Another example would be illustrating a point by making reference to a prominent individual involved with the topic at hand. Asides should have references so that the reader may seek more information if they so desire. Asides can also be used for anecdotes and personal stories and experiences, as well as direct quotation. We use the quotation markup to indicate an aside, as in: > Quote (use this for callouts, note that this can wrap but if there is a new line (second paragraph), there needs to be another greater-than sign after two hard returns). Section Style Each chapter, article, press release or web page has several sections to it and each section should start with a subhead. These subheads are marked up with double hash marks and a space before the subhead, concluding with a space and double hash marks again. Note that the subheads need to include keywords, be clear and descriptive. After the subhead, a hard-return (ENTER key) should be used before the start of the first paragraph of the section. Subheads should be in Title Capitalization Format. A section should be a logical division of the chapter which is not too long or too short relative to other sections. Sections can be 250-500 words on average, but they can be longer or shorter. The subhead itself should be clear, concise and descriptive of the content in the section, and should be meaningful to someone who is browsing through the book. Use of common terms is strongly preferred over terms that are themselves defined in the section. However, if the section is about that topic then the use of the term as well as a short description may be best for the subhead. E.g., poor subhead: Krabi Krabong, better subhead: Krabi Krabong - Thai Weapons Martial Art; best subhead: Thai Weapons Martial Art - Krabi Krabong. Having the more common term of Thai Weapons Martial Art come first is better for the reader as well as online SEO of this section. Note: the Editor/Publisher can help with Headers and Subheads, don't worry too much about this. A section should be somewhat self-contained. That is, the section would make sense if read on its own. Sections should be in order of more general to more specific, as well as more important to less important. The first paragraph of the section should be descriptive of the content in the section and a general statement of that content. However, language such as "this section is about..." should be strongly avoided. (These formulations are unnecessary and represent a more academic style.) Paragraph style Paragraphs are roughly 4-5 sentences in length and should be thought of as a coherent subsection of the given section they are in. Individual writing style may have more say over paragraph-level organization. Between two paragraphs should be two hard-returns (ENTER key strokes). Spelling, Grammar and Punctuation It is best to avoid single quotes and double quotes as much as possible, especially when they are used semantically, e.g., to change the meaning or offset the words as being not fully literal. In most cases these marks are not needed, and when clarification of a term or some editorial distance, then the word so-called can be used or in some (few) cases, the italics formatting. For book-length content, any one single English, e.g., American English, Australian English, British English, should be used throughout a given work. Pick one standard and stick to it, is the only firm rule. Spelling and usage should be consistent. Overall, shorter sentences with few punctuation marks are strongly preferred. Each sentence should have no more than one idea, whenever possible. Avoid contractions such as it’s for it is, they’ve for they have, etc. In many cases the grammar can be changed to remove these words, or simply remove the contraction and replace with component words. - American English Comma Usage: - Differences between American and British English Comma Usage - Use or discarding of Serial Comma should be decided upon and then consistently applied. Diacritics Please avoid use of any Diacritics: The reason is, people do not use them when they search in English, and Google in many cases treats them as different words. For example:,+Cafe This makes Vietnamese especially difficult, by the way. The French really cursed them. The diacritics have a lot of information but they are dropped when interacting in email/texting and the web. Avoid all sub/superscripts. These are generally formatting issues in Word (as well for the spelling corrections which add diacritics). You have to train/configure your text editor not to do these things. Diacritics just don't work on the web in terms of search. Word Choice, Voice, Pronouns and Reference Word choice should be common language usage at all times, except in terms of necessarily technical discussion. Do not use a more obscure word when a plain, everyday word is available. Contraindications should become warning signs; assuage should be reduce; cultivated should become developed; realm should become area. In most cases the word like is not appropriate when providing examples, but should be replaced with such as. In nearly all cases a neutral, 3rd person voice should be employed. The imperative can be used, e.g., Contact someone for help. But the first and second person should be largely avoided, e.g., do not write You should contact someone for help. Affect vs Effect: Use of Third Person For gender pronouns with indeterminate reference (i.e., not to a specific known individual), use of the third person plural is preferred, e.g., use they or their for he/she or his/her. Lists, Tables and Figures The use of lists, tables and figures are strongly encouraged. When done well, these are very helpful to the reader and especially the potential customer who is browsing through the work. Whenever a list of things are discussed, a bulleted list should likely be included. Tables are very helpful for any systematically discussed comparisons or contrasts. Any pictures or drawings which can help illustrate the work should be identified, if only as an idea. All figures and tables need a caption in italic, such as: Asean countries with English teacher salary and cost of living comparison Citation, Reference and Copyright Quotation should be avoided whenever possible. Paraphrase is ideal, however it is not always possible. For direct quotation, an in-line citation should be used, but full bibliographic information is not needed. Use of Foreign Language Terms Use of foreign language terms which are common should be formatted in italics (surrounded by a single asterisk, e.g., krengjai), along with a parenthetical original script and definition, e.g., Kreng jai (เกรงใจ) means being considerate or respectful, not wanting to bother someone. Note that any definitions should also be included in the Glossary document. Please copy/paste the term (and definition) into the glossary as well. We will ensure that the Glossary definitions match the text within the chapters as part of the final editing process, so there is no need to manually keep these in sync. Currency Codes and Currency Conversion For currency, the capitalized, three letter currency code from the ISO 4217 specification: This should be appended as a suffix after a space, e.g., 100 THB. If the currency needs to be spelled out, use capitalization, e.g., One Hundred Thai Baht. Avoid using the dollar, baht, pound, euro and other currency symbols. These are ambiguous and also not effective in search. When discussing currency exchange rates, it is useful to mention (e.g., regarding the Thai Baht) the Bangkok Bank conversion page: as well as the site (which is commonly used) as well as the approximation found in search engines Google, Yahoo, Bing, Wolfram Alpha, etc. For example, typing in "1 USD in THB" into search engines will produce a conversion rate calculation. Another point is when trying to do currency conversion between two currencies which are not geographically or economically close to each other, it is best to use a more common currency as an intermediary. For example, THB to VND or IDR to THB. The most efficient approach is to change THB into USD while in Thailand, and then once arriving in say Vietnam, change USD into VND. The same would be true in traveling from Indonesia to Thailand, first change IDR into USD and then upon arrival in Thailand, USD into THB. Punctuation - Use of a parenthetical dash shall be " -- " (space, hyphen, hyphen, space). - Only a single space after a period. - There should not be any double spaces anywhere in the text (these can have negative effects when transforming from markdown to LaTeX). - For apostrophe and single quote use only the character ('), and not a so-called fancy quote or the backtick. Many text editing programs do automatic substitution, but the characters are different from each other in terms of unicode, and cause problems. - The same goes for double quote marks, use only (") and not fancy double quotes. - There should not be any spacing or tab marks to begin paragraphs. These will be placed in the text upon transformation. Instead, there should be double-enter/return characters so that there is a blank line between each paragraph. Notes on Interviewing

    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.

YouTube Video Editor

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.
  • YouTube Video Downloader Chrome Extension
  • FBDown Video Downloader Chrome Extension
  • 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 (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).

Android / Google Play Books / Google Play Music

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.


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

Atom Editor

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,, 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.

Markdown Initiatives

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...


Some text1. Final bit of text for the paragraph.

# Header
## Subhead

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)

***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).


> ![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 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]( > 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 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 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.

Document metadata

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


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 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. Spicy Markdown 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, 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

    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

    License: Bland Markdown is released under a Creative Commons Attribution license.


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