# Softcover-flavored Markdown
\label{cha:softcover_flavored_markdown}
As noted in Chapter~\ref{cha:introduction_to_markdown}, the classic implementation of Markdown is beautifully simple but is not adequate for serious typesetting. Softcover therefore supports a *superset* of vanilla Markdown called *Softcovered-flavored Markdown* (SFM), which includes select [*kramdown*](http://kramdown.gettalong.org/) extensions (Section~\ref{sec:kramdown}), advanced enhancements such as GitHub-style fenced code blocks (Section~\ref{sec:advanced_enhancements}), and *super*-advanced additions via embedded \LaTeX\ (Section~\ref{sec:embedded_latex}). As noted in Chapter~\ref{cha:introduction_to_markdown}, the Softcover dialect of Markdown is, to our knowledge, the most powerful one available.
Softcover-flavored Markdown derives much of its power by converting \linebreak Markdown first to \PolyTeX, a strict subset of the \LaTeX\ typesetting language (Section~\ref{sec:softcover_system}), and then from \PolyTeX\ to HTML, EPUB, MOBI, and PDF\@. The result is an [abstraction layer](https://en.wikipedia.org/wiki/Abstraction_layer) over the underlying \LaTeX;[^latex_polytex] by allowing *embedded* \LaTeX\ as well, Softcover lets users pierce this abstraction layer to typeset things impossible for vanilla Markdown---for example, "\texttt{typewriter text} \textsc{is different from} `code`". (See Section~\ref{sec:embedded_latex} to learn how to typeset this.)
The resulting hybrid input language, though powerful, can get a bit messy, and
adding features to Markdown as described above is a prime example of how weak systems tend to evolve toward strong ones in an [*ad hoc*](http://en.wikipedia.org/wiki/Ad_hoc) way (Box~\ref{aside:polytex_markdown}). Users who want a consistent input syntax with maximum control can dispense with the abstraction layer and write in raw \PolyTeX\ instead (Chapter~\ref{cha:polytex_tutorial}). Indeed, because the Markdown conversion runs through the \PolyTeX\ pipeline, it's possible to start with Markdown and change over to \PolyTeX\ at any time (Section~\ref{sec:markdown_to_polytex}).
\begin{aside}
\label{aside:polytex_markdown}
\heading{Markdown, \PolyTeX, and Hartl's Tenth Rule of Typesetting}
\noindent I've been a fan of Markdown since it first appeared in 2004. Markdown is my first choice for things like [README files](https://github.com/softcover/softcover/blob/master/README.md) and [short news announcements](http://news.railstutorial.org/), and in my view Markdown deserves the enormous popularity it has achieved. Indeed, in a sense it has succeeded a little *too* well, to the point where people use it even when it may not be the best tool for the job. In particular, because it is essentially a thin layer on top of HTML, the original "vanilla" Markdown is ill-suited to producing longer or more structured documents. As a result, virtually every system using "Markdown" for ebook publishing in reality uses some augmented version of the original markup language---an implicit acknowledgment that vanilla Markdown is insufficient for industrial-strength typesetting.
On the other end of the spectrum from Markdown is \LaTeX, an industrial-strength typesetting system if ever there was one. \LaTeX, like the Lisp programming language in its domain, can essentially "do anything"; thus, in the spirit of [Greenspun's Tenth Rule of Programming](https://en.wikipedia.org/wiki/Greenspun's_tenth_rule) on Lisp, I hereby offer the following maxim on \LaTeX:
> **Hartl's Tenth Rule of Typesetting**\\
> *Any sufficiently complicated typesetting system contains an ad hoc,
> informally specified, bug-ridden, slow implementation of half of \LaTeX.*
\noindent Looking at the ever-expanding definition of "Markdown"---from [GitHub-flavored Markdown](http://github.github.com/github-flavored-markdown/) to [kramdown](http://kramdown.gettalong.org/) to Softcover-flavored Markdown itself---we see the pattern of Hartl's Tenth Rule emerge. (As with Greenspun's Tenth Rule of Programming, there are no rules 1--9 preceding Hartl's Tenth Rule of Typesetting; calling it the "tenth rule" is part of the joke.)
Of course, there's no law saying that we *have* to use Markdown, augmented or otherwise, and Hartl's Tenth Rule suggests a second possibility: *actually using \LaTeX*. Since \LaTeX\ is designed to make print-quality formats like PostScript and PDF, we do have to make some concessions when outputting multi-format ebooks, mainly because the popular EPUB and MOBI formats ultimately are based on HTML, and there's simply no general mapping from \LaTeX\ to HTML\@. But what we *can* do is support a *subset* of \LaTeX\ that maps nicely to HTML (and thence to EPUB and MOBI). The result is a version of \LaTeX\ that supports *polymorphic output*---i.e., *\PolyTeX*. (Unfortunately, even \PolyTeX\ can't fully escape Hartl's Tenth Rule, since producing HTML output from \LaTeX\ requires writing just such an implementation of half of \LaTeX\@. But by using \PolyTeX\ we at least avoid creating an *ad hoc*, informally specified *syntax* as well.)
\PolyTeX, at the cost of some complexity, gives authors considerably more power, flexibility, and extensibility than any variant of Markdown, Softcover-flavored Markdown included. If you already know HTML or Markdown, \PolyTeX\ is not hard to learn, with the only really scary syntax being for math input---but if you want to typeset mathematics, you need to learn \LaTeX\ anyway:
\[ \left(-\frac{\hbar^2}{2m}\nabla^2 + V\right)\psi = E\psi \]
\[
\left(\frac{p}{q}\right) \left(\frac{q}{p}\right) = (-1)^{[(p-1)/2][(q-1)/2]} \quad\text{($p$, $q$ distinct odd primes)}
\]
(These are the [time-independent Schr\"{o}dinger equation](https://en.wikipedia.org/wiki/Schr%C3%B6dinger_equation#Time-independent_equation) and the [law of quadratic reciprocity](https://en.wikipedia.org/wiki/Quadratic_reciprocity), respectively.) As a bonus, the resulting \texttt{.tex} files have the highest level of trustworthiness of any file extension (Figure~\ref{fig:xkcd_extensions}).
Despite my fondness for Markdown, \PolyTeX's superior power makes it my preferred Softcover input format. If your curiosity about \PolyTeX\ has been piqued, Chapter~\ref{cha:polytex_tutorial} will help get you started.
\end{aside}
![\href{http://www.xkcd.com/1301/}{XKCD 1301}.\label{fig:xkcd_extensions}](images/figures/file_extensions.png)
## The kramdown extensions
\label{sec:kramdown}
The [kramdown](http://kramdown.gettalong.org/) [[sic](https://en.wikipedia.org/wiki/Sic)] project is a pure-Ruby library that supports a superset of Markdown inspired by [Maruku](http://maruku.rubyforge.org/) and [PHP Markdown Extra](http://michelf.ca/projects/php-markdown/extra/). From the perspective of the Softcover platform, the most important additions are support for simple embedded tables and numbered footnotes.
The Softcover system piggybacks on kramdown's internals, which include a Markdown-to-\LaTeX\ converter to support PDF output. As a result, Softcover doesn't support kramdown syntax (such as embedded `div` tags) that can't be converted naturally to \LaTeX\@. This means that Softcover is intentionally less flexible in this regard in order to avoid the supporting HTML output that doesn't also work in PDFs.
### Tables
\label{sec:kramdown_tables}
The kramdown converter includes a lightweight syntax for making tables using pipes (`|`), dashes (`-`), and equals signs (`=`). Pipes define cells as follows:
| A simple | table |
| with multiple | lines|
\noindent This is produced by the following code:
```
| A simple | table |
| with multiple | lines|
```
Slightly more complicated tables can be defined using dashes to define a header and equals signs to define a footer:
| Header1 | Header2 | Header3 |
|---------|---------|---------|
| cell1 | cell2 | cell3 |
| cell4 | cell5 | cell6 |
| cell1 | cell2 | cell3 |
| cell4 | cell5 | cell6 |
|=======
| Foot1 | Foot2 | Foot3
This is produced by the following code
```
| Header1 | Header2 | Header3 |
|---------|---------|---------|
| cell1 | cell2 | cell3 |
| cell4 | cell5 | cell6 |
| cell1 | cell2 | cell3 |
| cell4 | cell5 | cell6 |
|=======
| Foot1 | Foot2 | Foot3
```
One important caveat is that dashes *can't* be used to define horizontal rules, so
```
| Header1 | Header2 | Header3 |
|---------|---------|---------|
| cell1 | cell2 | cell3 |
|---------|---------|---------|
| cell4 | cell5 | cell6 |
```
\noindent produces
| Header1 | Header2 | Header3 |
|---------|---------|---------|
| cell1 | cell2 | cell3 |
|---------|---------|---------|
| cell4 | cell5 | cell6 |
\noindent instead of the expected
\begin{center}
\begin{tabular}{|c|c|c|}
\hline
Header1 & Header2 & Header3 \\ \hline
cell1 & cell2 & cell3 \\ \hline
cell4 & cell5 & cell6 \\
\hline
\end{tabular}
\end{center}
\noindent Authors who want to produce tables with horizontal rules (or other more complicated effects) should use embedded \LaTeX\ (Section~\ref{sec:embedded_latex}) or \PolyTeX\ (Chapter~\ref{cha:polytex_tutorial}).
### Numbered footnotes
Vanilla Markdown doesn't support numbered footnotes, so kramdown adds them using the following syntax:[^example_footnote]
```text
kramdown adds them using the following syntax:[^example_footnote]
.
.
.
[^example_footnote]: This is an example footnote.
```
\noindent The vertical ellipsis indicates that intervening text has been omitted, and the code
```text
[^example_footnote]: This is an example footnote.
```
\noindent conventionally appears at the bottom of the file. Note that the order of the footnotes is determined by the order of their appearance in the main text; the order at the bottom of the file is irrelevant.
### Miscellaneous features
\label{sec:miscellaneous_features}
In addition to tables and footnotes, kramdown includes other miscellaneous features, including a verbatim override to prevent Markdown processing. This means, for example, that you can typeset a literal example of Markdown's double-asterisk boldface syntax {::nomarkdown}**like this**{:/}:
```
you can demonstrate Markdown's double-asterisk boldface syntax
{::nomarkdown}**like this**{:/}
```
(I personally find this syntax ugly and hard to remember, and prefer to typeset inline verbatim text using \LaTeX's \verb+\verb+ syntax; see Section~\ref{sec:embedded_latex_commands} for details.)
If you just want to escape individual characters, such as \*, you can do so with a backslash:
```
such as \*, you can do so with a backslash
```
\noindent Here are some other common characters you might want to escape:
```
* asterisk
` back tick
<< left guillemet
>> right guillemet
{} braces
| Unix pipe
```
\noindent Note that some of \LaTeX's special characters, such as $, are automatically escaped when using Markdown input.
Finally, in kramdown snake_case_words appear with underscores (a feature it shares with GitHub-flavored Markdown). This is convenient because vanilla Markdown would interpret the underscores as emphasis, yielding "snake*case*\-words", which probably isn't what you intended.
## Other advanced enhancements
\label{sec:advanced_enhancements}
Softcover-flavored Markdown includes several additional advanced en\-hance\-ments over vanilla Markdown and kramdown. Principal among these are *fenced code blocks* (Section~\ref{sec:code_fencing}), which are the preferred way to include code blocks in the Softcover system, and *code inclusion* (Section~\ref{sec:code_inclusion}), which allows you to include code snippets from the local filesystem into the current document.
### GitHub-flavored fenced code blocks
\label{sec:code_fencing}
Softcover borrows one key feature from [Github-flavored Markdown](https://help.github.com/articles/github-flavored-markdown), namely, [fenced code blocks](https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks), or "code fencing" for short. This syntax involves placing code samples inside "fences" composed of three backticks (\verb+```+):
```
# "Hello, world!" in Ruby
def hello
puts "hello, world!"
end
```
\noindent In Markdown, this is produced by the following code:
{lang="text"}
```
# "Hello, world!" in Ruby
def hello
puts "hello, world!"
end
```
\noindent
Following GitHub's example, Softcover supports an optional string after the opening of the fence indicating the language of the sample, yielding language-specific syntax highlighting:
```ruby
# Prints a greeting.
def hello
puts "hello, world!"
end
```
\noindent This is produced by the following Markdown:
```
```ruby
# Prints a greeting.
def hello
puts "hello, world!"
end
```
```
\noindent The language designation (e.g., `ruby`) can be any language supported by the [available Pygments lexers](http://pygments.org/docs/lexers/) which is most of them, including Ruby and \LaTeX\ (though not, annoyingly, Markdown). For example, here is the highlighting for a combination of HTML and PHP:
```html+php
Name:
```
\noindent This is produced by the code
```
```html+php
Name:
```
```
As a final enhancement, Softcover adds a hook directly into the [Pygments formatter options](http://pygments.org/docs/formatters/) via an options hash. This allows, for example, turning on line numbering and highlighting specific lines:
```ruby, options: "linenos": true, "hl_lines": [1, 3]
# Prints a greeting.
def hello
puts "hello, world!"
end
```
\noindent This is produced by the following Markdown:
```text
```ruby, options: "linenos": true, "hl_lines": [1, 3]
# Prints a greeting.
def hello
puts "hello, world!"
end
```
```
\noindent Here the hash
```
options: "linenos": true, "hl_lines": [1, 3]
```
\noindent gets passed directly to Pygments, so any option listed on the [Pygments formatter options page](http://pygments.org/docs/formatters/) is automatically supported by Softcover.
Because of how Softcover processes code blocks, any text immediately after code will be treated as a new paragraph. This isn't a problem in HTML output, but in the ebook formats (EPUB, MOBI, and PDF) new paragraphs are indented by default. If this isn't what you want---i.e., if the code block should be considered part of the middle of a paragraph---it is necessary to prepend the \LaTeX\ command \verb+\noindent+ before the first line after the block, as follows:
```text
```ruby
# Prints a greeting.
def hello
puts "hello, world!"
end
```
\noindent This is produced by the following Markdown
```
\noindent See Section~\ref{sec:embedded_latex_commands} for more details.
### Leanpub-style language blocks
SFM supports indented code blocks with an explicit language designation, which is based on [Leanpub](http://leanpub.com/)'s proprietary Markdown variant. This is mainly useful when using SFM to talk about SFM\@. In particular, plain code fences can't talk about themselves, because there's no way for the parser to know if the first inner \verb+```+ is the end of a fenced block or the beginning of example code. Thus, a code block like
{lang="text"}
```
# "Hello, world!" in Ruby
def hello
puts "hello, world!"
end
```
\noindent can't be set by nesting one fenced block inside another. Instead, we use
```
{lang="text"}
```
# "Hello, world!" in Ruby
def hello
puts "hello, world!"
end
```
```
\noindent where the line
```
{lang="text"}
```
\noindent specifies the language explicitly (in this case, `text`, because, as noted in Section~\ref{sec:code_fencing}, Pygments lacks a Markdown lexer).
Although this syntax can be used to typeset highlighted code like
{lang="ruby"}
# Prints a greeting.
def hello
puts "hello, world!"
end
\noindent using
```
{lang="ruby"}
# Prints a greeting.
def hello
puts "hello, world!"
end
```
\noindent I virtually always prefer to use code fencing instead, i.e.,
{lang="text"}
```ruby
# Prints a greeting.
def hello
puts "hello, world!"
end
````
### Code inclusion
\label{sec:code_inclusion}
Softcover supports code inclusion directly from local files, such as this program to wish "goodnight" to the Moon:
<<(source/goodnight.rb)
\noindent The corresponding file is in `source/goodnight.rb`, so the markup
```text
<<(source/goodnight.rb)
```
\noindent includes the source of the file into the current document. Because Softcover automatically associates the `.rb` filename extension with the code block, syntax highlighting comes for free via Pygments. For extensions that Pygments doesn't understand, you can add additional information as in Section~\ref{sec:code_fencing}. For example, this is the `book.yml` file for a newly generated example book (last seen in Listing~\ref{code:book_yml}):
<<(example_book/config/book.yml, lang: yaml)
\noindent Because Pygments (for some odd reason) doesn't understand `.yml` but *does* understand `.yaml`, we can arrange for the proper highlighting by passing the `lang: yaml` option, which tells Pygments to highlight the code as [YAML](https://en.wikipedia.org/wiki/YAML):
```text
<<(example_book/config/book.yml, lang: yaml)
```
### Embedded math
\label{sec:terrible_math}
Softcover supports embedded math via the terrible syntax `{\$\$\}...\{/\$\$\}`, as in {$$}\phi^2 - \phi - 1 = 0{/$$}, and centered math, as in
{$$}
\phi = \frac{1+\sqrt{5}}{2}.
{/$$}
\noindent This works for both inline and centered math, with the only difference being the absence or presence of newlines:
```
Softcover supports embedded math via the terrible syntax `{\$\$\}...\{/\$\$\}`,
as in {$$}\phi^2 - \phi - 1 = 0{/$$}, and centered math, as in
{$$}
\phi = \frac{1+\sqrt{5}}{2}.
{/$$}
```
\noindent This syntax is included only for compatibility with other systems (particularly Leanpub Markdown); Softcover also supports the proper \LaTeX\ syntax (Section~\ref{sec:embedded_math}), which is strongly preferred.
## Embedded \LaTeX
\label{sec:embedded_latex}
Short of using raw \PolyTeX\ (Chapter~\ref{cha:polytex_tutorial}), the most advanced typesetting options supported by Softcover involve embedding \LaTeX\ code directly in Markdown. As noted in the introduction to this chapter, this allows us to typeset things like "\texttt{typewriter text} \textsc{is different from} `code`", which in embedded \LaTeX\ appears as follows:
```latex
"\texttt{typewriter text} \textsc{is different from} `code`"
```
\noindent This uses \verb+\texttt+ (read "text-tee-tee") to set \texttt{typewriter text} and \linebreak \verb+\textsc+ to set \textsc{small caps}.
Not all of \LaTeX\ is supported, of course. The embeddable subset consists of single commands such as \verb+\texttt+ and \verb+\label+ (Section~\ref{sec:embedded_latex_commands} and Section~\ref{sec:embedded_labels_and_cross_references}), tables (Section~\ref{sec:embedded_tabular_and_tables}), figures (Section~\ref{sec:embedded_figures}), code listings (Section~\ref{sec:embedded_code_listings}), aside boxes (Section~\ref{sec:embedded_asides}), and mathematics (Section~\ref{sec:embedded_math}). That's still a lot, though, and experienced Markdown users new to \LaTeX\ will be amazed at all the things it can do.
Incidentally, in addition to the commands mentioned above, Softcover also supports \LaTeX's syntax for en-dashes using two dashes (\verb+--+), as in "1740--1780", and em-dashes---like this---using three dashes (\verb+---+):
```latex
as in "1740--1780", and em-dashes---like this---using
```
### \LaTeX\ commands
\label{sec:embedded_latex_commands}
In order to use embedded \LaTeX, we need a crash course on \LaTeX\ syntax. Luckily, the basics are not complicated. All \LaTeX\ commands start with a backslash `\`, and typically take 0 or 1 arguments inside curly braces. For example, we saw above how to typeset \texttt{typewriter text}:
```latex
we saw above how to typeset \texttt{typewriter text}
```
\noindent Here \verb+\texttt+ is the command and `typewriter text` is the argument.[^nesting_caveat]
The \LaTeX\ command itself is an example of a command taking no arguments:
```latex
The \LaTeX\ command itself
```
\noindent Because of how \LaTeX\ processes text, any space *after* a command gets "eaten", so here we've used the special "backslash space" command `\ ` to insert a space after the \verb+\LaTeX+ command.
We mentioned \verb+\noindent+, another command with zero arguments, back at the end of Section~\ref{sec:code_fencing}; when producing PDFs, it prevents indenting lines after things like code blocks:
```text
The \LaTeX\ command itself is an example of a command taking no arguments:
```latex
The \LaTeX\ command itself
```
\noindent Because of how \LaTeX\ processes text
```
\LaTeX\ also supports various *environments*, which are defined by the special `begin` and `end` commands. For example, we'll see in Section~\ref{sec:embedded_tabular_and_tables} that tables are set using the `tabular` environment as follows:
```latex
\begin{tabular}
.
.
.
\end{tabular}
```
\noindent Similarly, in Section~\ref{sec:embedded_math} we'll see how to typeset numbered equations using the `equation` environment:
```latex
\begin{equation}