gauthiier/wwwriting
gauthiier/wwwriting
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Lesson4 etc.

Browse Source
This commit is contained in:
gauthiier 2015-02-18 08:30:20 +01:00
parent fa93688603
commit 6095baeac4
17 changed files with 792 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Lesson1.html
View File

@ -9,11 +9,11 @@
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link rel="stylesheet" href="style/style.css">
<link rel="stylesheet" href="style/html5.css">
</head>
<body>
<content>
<h2 id="text-encoding">Text Encoding</h2>
<h1 id="text-encoding">Text Encoding</h1>
<p>We believe in approaching text writing by first understanding the core inscription mechanism upheld by modern computing machine. In this lesson we will hence look at how text and characters are inscribed and represented internally within computers. More specifically we will look at standards of text encoding (and decoding) and see how text editors can decode such encoding.</p>
<h3 id="goals">Goals</h3>
<p>The aim of this lesson is to present the various ways that computers represent text internally, that is, characters as digits. The lesson is tailored in giving the reader the basic knowledge of standards that establish the quanta of text (data). Our hope in doing so is to give a feel of a kind of materiality of text and present the ways in which various levels of abstraction are applied to it.</p>
@ -26,7 +26,7 @@
<li>Learn how to use a plain text editor to write, view and inspect different open standards encodings of a given text file.</li>
</ol>
<h3 id="history">History</h3>
<p>As everyone heard of the byte format? If you didn't it's about time you do as you employ this legacy format daily when using your computer. A byte is the most basic quanta of computing and is composed of 8 bits, where a bit stands for what is commonly represented by a 0 or 1. Hence a byte is a 8-bits &quot;packet&quot; which can represent decimal numbers ranging from 0 to 255 (or -128 to 127). In this lesson we will use the <a href="https://en.wikipedia.org/wiki/Hexadecimal">Hexadecimal</a> notation to represent bytes. A byte is an historical format and encapsulate the most basic data structure in computing machinery, a standard introduced by IBM for its flagship <a href="http://www.computermuseum.li/Testpage/IBM-360-1964.htm">IBM/360</a> mainframe machine in 1964.<a href="#fn1" class="footnoteRef" id="fnref1"><sup>1</sup></a></p>
<p>Has everyone heard of the byte format? If you didn't it's about time you do as you employ this legacy format daily when using your computer. A byte is the most basic quanta of computing and is composed of 8 bits, where a bit stands for what is commonly represented by a 0 or 1. Hence a byte is a 8-bits &quot;packet&quot; which can represent decimal numbers ranging from 0 to 255 (or -128 to 127). In this lesson we will use the <a href="https://en.wikipedia.org/wiki/Hexadecimal">Hexadecimal</a> notation to represent bytes. A byte is an historical format and encapsulate the most basic data structure in computing machinery, a standard introduced by IBM for its flagship <a href="http://www.computermuseum.li/Testpage/IBM-360-1964.htm">IBM/360</a> mainframe machine in 1964.<a href="#fn1" class="footnoteRef" id="fnref1"><sup>1</sup></a></p>
<p>Roughly at the same time (1963) another (updated) standard was devised for the encoding of characters: ASCII [ref]. ASCII conceived a 7-bit format for characters that was factorised into an 8-bit format on the IBM/360. With a 7-bit format, ASCII had the possibility to encode 127 characters. However, the IBM/360 opted to use the legacy <a href="https://en.wikipedia.org/wiki/EBCDIC">EBCDIC</a> 8-bit format as default character set (dubbed &quot;charset&quot;) on all software developed for the IBM/360<a href="#fn2" class="footnoteRef" id="fnref2"><sup>2</sup></a>. Hence the mass adoption of ASCII as main default charset in computing systems came years after mainly with the advent of PCs.</p>
<p>Is ASCII still in use today? Yes and no. ASCII has some important limitations as it was designed for Latin-based languages and does not support non-Latin characters (hence a 7-bit format for an Latin alphabet). With the wide spread of PCs around the world and the rise of the Internet as main communication infrastructure, the need for a single character format (albeit a Universal Format) accounting for both Latin and non-Latin characters (Cyrillic, Hebrew, Arabic, Turkish to name a few) was imminent at the beginning for the 90s.</p>
<p>Hence the establishment of the Unicode standard which aim is to devise and maintain a Universal Character Set (UCS) composed of special codes points for each character (a kind of &quot;meta&quot;-charset if you want, composed of specific unicode codes)<a href="#fn3" class="footnoteRef" id="fnref3"><sup>3</sup></a>. Unicode does not specify specific encodings for its code points. Rather, encodings are part of specific implementations of the UCS such as UTF (UCS Transformation Format). The most notable UTF being UTF-8.<a href="#fn4" class="footnoteRef" id="fnref4"><sup>4</sup></a> The special feature of UTF-8 is that it is directly backward compatible with ASCII (an 8-bit ASCII character as the same encoding as its UTF-8 version) and has the property of being variable in length, meaning that Latin characters are encoded with a single byte while other non-Latin characters may be encoded with up to 4 bytes.<a href="#fn5" class="footnoteRef" id="fnref5"><sup>5</sup></a> Nowadays, UTF-8 is one of the most (if not <em>the</em> most) mass adopted / ubiquitous character encoding format.<a href="#fn6" class="footnoteRef" id="fnref6"><sup>6</sup></a></p>

2
Lesson1.md
View File

@ -3,7 +3,7 @@ bibliography: wwwrite.bib
cover: img/enco.png
---
## Text Encoding
# Text Encoding
We believe in approaching text writing by first understanding the core inscription mechanism upheld by modern computing machine. In this lesson we will hence look at how text and characters are inscribed and represented internally within computers. More specifically we will look at standards of text encoding (and decoding) and see how text editors can decode such encoding.

8
Lesson2.html
View File

@ -9,21 +9,21 @@
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link rel="stylesheet" href="style/style.css">
<link rel="stylesheet" href="style/html5.css">
</head>
<body>
<content>
<h2 id="cli-or-the-command-line-interface">CLI or the Command Line Interface</h2>
<h1 id="cli-or-the-command-line-interface">CLI or the Command Line Interface</h1>
<p>The Command Line Interface is the most common and pervasive interface directly linking fingers typing on a keyboard (text) and the computer (commands). The CLI is a legacy mode of operating computing system which can be traced back to early telegraphic devices. In this lesson we will look at your computer's own CLI and present ways in which you can use it to write, manipulate, analyse and transform text on your own computer system.</p>
<div class="figure">
<img src="img/rkwk101.gif" />
</div>
<h3 id="goals">Goals</h3>
<p>The aim of this lesson is for readers to develop an appreciation of the advantages of using the CLI for certain types of work involving text editing on a computer. As the CLI itself is text based, our goal is to present the history of the CLI and discuss how text-based computer interfaces are still up to this day on of the most important ways to communicate with the computer systems.</p>
<p>The goals of the lesson are:</p>
<p>The goals of this lesson are:</p>
<ol style="list-style-type: decimal">
<li>Acquire basic knowledge on how to operate the CLI of your own computer.</li>
<li>Acquire just-enough basic CLI vocabulary to be used in future work.</li>
<li>Acquire just-enough CLI vocabulary to be used in future work.</li>
</ol>
<h3 id="how">How</h3>
<p>To access to the Command Line Interface of your computer you need a Command Line Interpreter. Every mdoern Operating System (OS) have such interpreter built-in. In fact, the Command Line Interpreter are legacy systems on most OS (OSX, Windows, Linux, Unix, etc.) because there was a time when interfacing with a computer was solely done typing commands on a terminal.<a href="#fn1" class="footnoteRef" id="fnref1"><sup>1</sup></a> Most computer programmers, even nowadays, use the computer CLI on a daily basis to write and run software and even to debug hardware.</p>

4
Lesson2.md
View File

@ -1,5 +1,5 @@
## CLI or the Command Line Interface
# CLI or the Command Line Interface
The Command Line Interface is the most common and pervasive interface directly linking fingers typing on a keyboard (text) and the computer (commands). The CLI is a legacy mode of operating computing system which can be traced back to early telegraphic devices. In this lesson we will look at your computer's own CLI and present ways in which you can use it to write, manipulate, analyse and transform text on your own computer system.
@ -11,7 +11,7 @@ The Command Line Interface is the most common and pervasive interface directly l
The aim of this lesson is for readers to develop an appreciation of the advantages of using the CLI for certain types of work involving text editing on a computer. As the CLI itself is text based, our goal is to present the history of the CLI and discuss how text-based computer interfaces are still up to this day on of the most important ways to communicate with the computer systems.
The goals of the lesson are:
The goals of this lesson are:
1. Acquire basic knowledge on how to operate the CLI of your own computer.
2. Acquire just-enough CLI vocabulary to be used in future work.

4
Lesson3.html
View File

@ -9,11 +9,11 @@
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link rel="stylesheet" href="style/style.css">
<link rel="stylesheet" href="style/html5.css">
</head>
<body>
<content>
<h2 id="markup-markdown">Markup / Markdown</h2>
<h1 id="markup-markdown">Markup / Markdown</h1>
<p>Markup languages are one of the most pervasive and common types of language on the Internet. In fact HTML is a type of markup language responsible to instruct our web browsers on how to layout text, images and the likes on our screens. Behind all web pages, there is a markup text file that is sent from a server to our browsers when we type in a URL. The beauty of markup languages is that they are both <a href="https://en.wikipedia.org/wiki/Human-readable_medium">human-readable</a> and <a href="https://en.wikipedia.org/wiki/Machine-readable_data">machine-readable</a> and written in plain text format. Reading a marked up text one can notice the special &quot;meta-codes&quot; and related syntax that direct machines in interpreting the same text. The idea is thus to have some standards and conventions describing these meta-codes and expected machine interpretation.</p>
<h3 id="goals">Goals</h3>
<p>In this lesson we will introduce the Markdown language for writing (academic) texts. Markdown is a type of markup language that features very intuitive set of meta-codes and a simple syntax that can seamlessly integrate with normal text without transforming them much.</p>

2
Lesson3.md
View File

@ -1,4 +1,4 @@
## Markup / Markdown
# Markup / Markdown
Markup languages are one of the most pervasive and common types of language on the Internet. In fact HTML is a type of markup language responsible to instruct our web browsers on how to layout text, images and the likes on our screens. Behind all web pages, there is a markup text file that is sent from a server to our browsers when we type in a URL. The beauty of markup languages is that they are both [human-readable](https://en.wikipedia.org/wiki/Human-readable_medium) and [machine-readable](https://en.wikipedia.org/wiki/Machine-readable_data) and written in plain text format. Reading a marked up text one can notice the special "meta-codes" and related syntax that direct machines in interpreting the same text. The idea is thus to have some standards and conventions describing these meta-codes and expected machine interpretation.

93
Lesson4.html Normal file
View File

@ -0,0 +1,93 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="generator" content="pandoc">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<title></title>
<style type="text/css">code{white-space: pre;}</style>
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link rel="stylesheet" href="style/html5.css">
</head>
<body>
<content>
<h1 id="textdocument-processor">(Text/Document) Processor</h1>
<p>A document processor is a piece of software that interprets text and transcode its content from one form to another. There are many types of processors, yet for the purpose of this lesson we focus on only two types: (1) <strong>Interpreter</strong> and (2) <strong>Converter</strong>. An interpreter is very similar to your web browser: it gets as input an html file (and related scripts), interprets their syntax and content and display the results on the screen. More generally, an interpreter first parses the content of an input file, then creates its own representation of it and finally performs the commands it has interpreted. In the process, there is a translation stage where the input syntax and content is read (parsed) and transformed into a transitional or median representation. This median representation is then linked to specific commands that are in turn executed locally on the interpreters machine. In the case of the converter, such median representation get transcoded into a specified format with a specific syntax written in a file. For example, an HTML file can be converted into both a PDF <em>and/or</em> a DOC file. Interpreters and converters are ubiquitous systems which are fundamental for both publishing and archiving practices.</p>
<h3 id="goals">Goals</h3>
<p>Assuming that you have a basic knowledge of the Markdown language, in this lesson you will learn how to convert a text file written in markdown to both an HTML and EPUB3 output. In order to do so, you need to instal <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> on your system as we will be using this specific markdown converter.</p>
<p>The goals of this lesson are:</p>
<ol style="list-style-type: decimal">
<li>Acquire the basic understanding of how to employ pandoc to produce both HTML and EPUB output.</li>
<li>Acquire the basic knoeledge of how pandoc can be tailored to produce other types of output.</li>
</ol>
<h3 id="how">How</h3>
<p>In order to complete this lesson, you should be familiar with how to operated your computer's CLI (<a href="Lesson2.html">Lesson2</a>) and capable of writing markdown valid text (<a href="Lesson3.html">Lesson3</a>).</p>
<p>The following exercises assumes that you have markdown input file ready to convert to both HTML and EPUB. If you don't already, simply use this file (<a href="Lesson4.md">Lesson4.md</a>).</p>
<p>To make sure that your system is set up properly, open a CLI window and type the following</p>
<pre><code>pandoc --version</code></pre>
<p>If you get an error message, this means that you did not install pandoc properly. If so please visit <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> and install the required software. If not you are ready to go!</p>
<p>Now since pandoc is a document converter its most basic form of usage consists of an <em>input</em> file and an <em>output</em> file.</p>
<p>A command like</p>
<pre><code>pandoc -s Lesson4.md -o Lesson4.html</code></pre>
<p>will produce an <em>output</em> file (-o Lesson4.html) from the <em>input</em> file (<em>Lesson4.md</em>). Here the argument -s will force pandoc to produce an entire valid document rather than a snippet of it.</p>
<p>More formally, the former command could be</p>
<pre><code>pandoc -s -f markdown Lesson4.md -t html5 -o Lesson4.html</code></pre>
<p>meaning the input file (Lesson4.md) is of type &quot;markdown&quot; and the output file (-o Lesson4.html) is of type &quot;html5&quot;. You can basically omit these details if you want, markdown can recognise valid input files while the extension of your output file (here .html) will inform the program on the type of output expected. However, since pandoc has multiple possible output files to choose from, some of them of the same type but of different version (for example html and html5), it is a good practice to specify the type of output.</p>
<p>Now let's simply change the output to the Rich Text Format (rtf)</p>
<pre><code>pandoc -s -f markdown Lesson4.md -t rtf -o Lesson4.rtf</code></pre>
<p>or in a more compact version</p>
<pre><code>pandoc -s Lesson4.md -o Lesson4.rtf</code></pre>
<p>It is indeed very straight forward change output formats. As explained in the beginning of this Lesson, pandoc is a converter which can produce various outputs out of its internal median representation of a parsed input.</p>
<p>More precisely, pandoc can read:</p>
<blockquote>
<p>markdown and (subsets of) Textile, reStructuredText, HTML, LaTeX, MediaWiki markup, TWiki markup, Haddock markup, OPML, Emacs Org-mode, DocBook, txt2tags, EPUB and Word docx</p>
</blockquote>
<p>And from these documents it can write:</p>
<blockquote>
<p>plain text, markdown, reStructuredText, XHTML, HTML 5, LaTeX (including beamer slide shows), ConTeXt, RTF, OPML, DocBook, OpenDocument, ODT, Word docx, GNU Texinfo, MediaWiki markup, DokuWiki markup, Haddock markup, EPUB (v2 or v3), FictionBook2, Textile, groff man pages, Emacs Org-Mode, AsciiDoc, InDesign ICML, and Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows. It can also produce PDF output on systems where LaTeX is installed.</p>
</blockquote>
<p>For the purpose of this lesson we will focus on HTML(5) and EPUB(3).</p>
<h4 id="html5">HTML(5)</h4>
<p>Now that we have been experiencing pandoc a little already, we will proceed by directly discussing the pandoc command used to generate this site and explain the options that we have set. To generate this html5 web page issue the following command</p>
<pre><code>pandoc -s Lesson4.md --template=style/template.html5 -c style/html5.css --bibliography=wwwrite.bib -o Lesson4.html</code></pre>
<p>Now refresh your web browser and see if something changed. Perhaps not (yet). You may not realise it but you have (re)generated the entire HTML in a single pandoc command!</p>
<p>As you can see there is a little more arguments in the above pandoc than previously exposed in the first section.</p>
<ol style="list-style-type: decimal">
<li><p>As expected we have</p>
<pre><code>-s Lesson4.md -o Lesson4.html</code></pre>
<p>which specifies the markdown <em>input</em> (Lesson4.md) and HTML <em>output</em> (Lesson4.html)</p></li>
<li><p>There is a few extra options</p>
<pre><code>--template=style/template.html5 -c style/html5.css --bibliography=wwwrite.bib</code></pre>
<p>which are instructing pandoc to (1) use the HTML5 template &quot;style/template.html5&quot;, (2) use the <a href="https://en.wikipedia.org/wiki/Cascading_Style_Sheets">stylesheet</a> &quot;style/html5.css&quot; and (3) use the bibliographical information in &quot;wwwrite.bib&quot; if in-text referencing is needed.</p></li>
</ol>
<p>Without going in too much details (since this is the topic of <a href="/">Lesson6</a>), the current site employs custom templates and stylesheets (in the directory <a href="style/">&quot;style/&quot;</a>). In these file you will find all the markup code used to (automatically) generate the layout this web page in HTML and <a href="(https://en.wikipedia.org/wiki/Cascading_Style_Sheets)">CSS</a> formats. In a nutshell, on the one hand a template is responsible to instruct how to convert pandoc's median representation into an HTML format while on the other a CSS stylesheet is responsible for the layout and (design) parametrisation of the content of this HTML. Hence, rather than specifying a default pandoc output, we use our own custom templates to generate our own tailored HTML outputs.</p>
<h4 id="epub3">EPUB(3)</h4>
<p>It is worth mentioning at this stage that in previous example, pandoc is converting files written in one markup language &quot;markdown&quot; to another markup language &quot;HTML5&quot;. At its core, EPUB is yet another markup language. Both HTML and EPUB are standard markups that are both interpreted by a web browser and epub reader respectively.</p>
<p>Now here is the pandoc command to generate an epub(3) of the whole site</p>
<pre><code>pandoc -S index.md Lesson1.md Lesson2.md Lesson3.md metadata.epub3.yaml --toc --template=style/template.epub3 --epub-stylesheet=style/epub3.css --epub-cover-image=img/DSP6.png --bibliography=wwwrite.bib -o WWWRITE.epub </code></pre>
<p>As you may notice, the command is a bit more &quot;complex&quot; than the previous HTML one, yet basically resembles it in many ways.</p>
<p>The arguments</p>
<pre><code>-S index.md Lesson1.md Lesson2.md Lesson3.md Lesson4.md metadata.epub3.yaml -o WWWRITE.epub </code></pre>
<p>specify a list of <em>input</em> files (index.md, Lesson1.md, Lesson2.md, Lesson3.md, Lesson4.md, and metadata.epub3.yaml) and an <em>output</em> file (-o WWWRITE.epub). Pandoc will concatenate input files into a single one when listed as inputs. This is convenient as it enables a writer to segment a book into self-contained chapters for example.</p>
<p>Styling and template options are specified with</p>
<pre><code>--template=style/template.epub3 --epub-stylesheet=style/epub3.css --bibliography=wwwrite.bib</code></pre>
<p>these are exactly the same as in the previous HTML example. In fact, in one looks at the template and CSS you could notice that that are to some extent very similar to the HTML5 ones. This is because the EPUB markup language is based on HTML!</p>
<p>Also notice the</p>
<pre><code>--epub-cover-image=img/DSP6.png</code></pre>
<p>which tells pandoc to use the specified image as cover for the EPUB.</p>
<p>Finally the argument</p>
<pre><code>--toc</code></pre>
<p>is a feature that instructs pandoc to generate a &quot;Table Of Content&quot; (toc) out of the various markdown Headings (symbol '#' <a href="Lesson3.html">Lesson3</a>) present in the input files.</p>
<p>Let's now have a look at the EPUB output!</p>
<h3 id="extra">Extra</h3>
<p><a href="http://johnmacfarlane.net/pandoc/try/">Try pandoc!</a></p>
<p><a href="http://johnmacfarlane.net/pandoc/README.html#epub-metadata">Pandoc User's Guide</a></p>
<p><a href="http://johnmacfarlane.net/pandoc/getting-started.html">Getting Started</a></p>
<div class="references">
</div>
</content>
</body>
</html>

123
Lesson4.md
View File

@ -1,9 +1,128 @@
## (Text) Processor
# (Text/Document) Processor
A document processor is a piece of software that interprets text and transcode its content from one form to another. There are many types of processors, yet for the purpose of this lesson we focus on only two types: (1) __Interpreter__ and (2) __Converter__. An interpreter is very similar to your web browser: it gets as input an html file (and related scripts), interprets their syntax and content and display the results on the screen. More generally, an interpreter first parses the content of an input file, then creates its own representation of it and finally performs the commands it has interpreted. In the process, there is a translation stage where the input syntax and content is read (parsed) and transformed into a transitional or median representation. This median representation is then linked to specific commands that are in turn executed locally on the interpreters machine. In the case of the converter, such median representation get transcoded into a specified format with a specific syntax written in a file. For example, an HTML file can be converted into both a PDF _and/or_ a DOC file. Interpreters and converters are ubiquitous systems which are fundamental for both publishing and archiving practices.
### Goals
### History
Assuming that you have a basic knowledge of the Markdown language, in this lesson you will learn how to convert a text file written in markdown to both an HTML and EPUB3 output. In order to do so, you need to instal [Pandoc](http://johnmacfarlane.net/pandoc/) on your system as we will be using this specific markdown converter.
The goals of this lesson are:
1. Acquire the basic understanding of how to employ pandoc to produce both HTML and EPUB output.
2. Acquire the basic knoeledge of how pandoc can be tailored to produce other types of output.
### How
In order to complete this lesson, you should be familiar with how to operated your computer's CLI ([Lesson2](Lesson2.html)) and capable of writing markdown valid text ([Lesson3](Lesson3.html)).
The following exercises assumes that you have markdown input file ready to convert to both HTML and EPUB. If you don't already, simply use this file ([Lesson4.md](Lesson4.md)).
To make sure that your system is set up properly, open a CLI window and type the following
pandoc --version
If you get an error message, this means that you did not install pandoc properly. If so please visit [Pandoc](http://johnmacfarlane.net/pandoc/) and install the required software. If not you are ready to go!
Now since pandoc is a document converter its most basic form of usage consists of an _input_ file and an _output_ file.
A command like
pandoc -s Lesson4.md -o Lesson4.html
will produce an _output_ file (-o Lesson4.html) from the _input_ file (_Lesson4.md_). Here the argument -s will force pandoc to produce an entire valid document rather than a snippet of it.
More formally, the former command could be
pandoc -s -f markdown Lesson4.md -t html5 -o Lesson4.html
meaning the input file (Lesson4.md) is of type "markdown" and the output file (-o Lesson4.html) is of type "html5". You can basically omit these details if you want, markdown can recognise valid input files while the extension of your output file (here .html) will inform the program on the type of output expected. However, since pandoc has multiple possible output files to choose from, some of them of the same type but of different version (for example html and html5), it is a good practice to specify the type of output.
Now let's simply change the output to the Rich Text Format (rtf)
pandoc -s -f markdown Lesson4.md -t rtf -o Lesson4.rtf
or in a more compact version
pandoc -s Lesson4.md -o Lesson4.rtf
It is indeed very straight forward change output formats. As explained in the beginning of this Lesson, pandoc is a converter which can produce various outputs out of its internal median representation of a parsed input.
More precisely, pandoc can read:
> markdown and (subsets of) Textile, reStructuredText, HTML, LaTeX, MediaWiki markup, TWiki markup, Haddock markup, OPML, Emacs Org-mode, DocBook, txt2tags, EPUB and Word docx
And from these documents it can write:
>plain text, markdown, reStructuredText, XHTML, HTML 5, LaTeX (including beamer slide shows), ConTeXt, RTF, OPML, DocBook, OpenDocument, ODT, Word docx, GNU Texinfo, MediaWiki markup, DokuWiki markup, Haddock markup, EPUB (v2 or v3), FictionBook2, Textile, groff man pages, Emacs Org-Mode, AsciiDoc, InDesign ICML, and Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows. It can also produce PDF output on systems where LaTeX is installed.
For the purpose of this lesson we will focus on HTML(5) and EPUB(3).
#### HTML(5)
Now that we have been experiencing pandoc a little already, we will proceed by directly discussing the pandoc command used to generate this site and explain the options that we have set. To generate this html5 web page issue the following command
pandoc -s Lesson4.md --template=style/template.html5 -c style/html5.css --bibliography=wwwrite.bib -o Lesson4.html
Now refresh your web browser and see if something changed. Perhaps not (yet). You may not realise it but you have (re)generated the entire HTML in a single pandoc command!
As you can see there is a little more arguments in the above pandoc than previously exposed in the first section.
1. As expected we have
-s Lesson4.md -o Lesson4.html
which specifies the markdown _input_ (Lesson4.md) and HTML _output_ (Lesson4.html)
2. There is a few extra options
--template=style/template.html5 -c style/html5.css --bibliography=wwwrite.bib
which are instructing pandoc to (1) use the HTML5 template "style/template.html5", (2) use the [stylesheet](https://en.wikipedia.org/wiki/Cascading_Style_Sheets) "style/html5.css" and (3) use the bibliographical information in "wwwrite.bib" if in-text referencing is needed.
Without going in too much details (since this is the topic of [Lesson6](/)), the current site employs custom templates and stylesheets (in the directory ["style/"](style/)). In these file you will find all the markup code used to (automatically) generate the layout this web page in HTML and [CSS]((https://en.wikipedia.org/wiki/Cascading_Style_Sheets)) formats. In a nutshell, on the one hand a template is responsible to instruct how to convert pandoc's median representation into an HTML format while on the other a CSS stylesheet is responsible for the layout and (design) parametrisation of the content of this HTML. Hence, rather than specifying a default pandoc output, we use our own custom templates to generate our own tailored HTML outputs.
#### EPUB(3)
It is worth mentioning at this stage that in previous example, pandoc is converting files written in one markup language "markdown" to another markup language "HTML5". At its core, EPUB is yet another markup language. Both HTML and EPUB are standard markups that are both interpreted by a web browser and epub reader respectively.
Now here is the pandoc command to generate an epub(3) of the whole site
pandoc -S index.md Lesson1.md Lesson2.md Lesson3.md metadata.epub3.yaml --toc --template=style/template.epub3 --epub-stylesheet=style/epub3.css --epub-cover-image=img/DSP6.png --bibliography=wwwrite.bib -o WWWRITE.epub
As you may notice, the command is a bit more "complex" than the previous HTML one, yet basically resembles it in many ways.
The arguments
-S index.md Lesson1.md Lesson2.md Lesson3.md Lesson4.md metadata.epub3.yaml -o WWWRITE.epub
specify a list of _input_ files (index.md, Lesson1.md, Lesson2.md, Lesson3.md, Lesson4.md, and metadata.epub3.yaml) and an _output_ file (-o WWWRITE.epub). Pandoc will concatenate input files into a single one when listed as inputs. This is convenient as it enables a writer to segment a book into self-contained chapters for example.
Styling and template options are specified with
--template=style/template.epub3 --epub-stylesheet=style/epub3.css --bibliography=wwwrite.bib
these are exactly the same as in the previous HTML example. In fact, in one looks at the template and CSS you could notice that that are to some extent very similar to the HTML5 ones. This is because the EPUB markup language is based on HTML!
Also notice the
--epub-cover-image=img/DSP6.png
which tells pandoc to use the specified image as cover for the EPUB.
Finally the argument
--toc
is a feature that instructs pandoc to generate a "Table Of Content" (toc) out of the various markdown Headings (symbol '#' [Lesson3](Lesson3.html)) present in the input files.
Let's now have a look at the EPUB output!
### Extra
[Try pandoc!](http://johnmacfarlane.net/pandoc/try/)
[Pandoc User's Guide](http://johnmacfarlane.net/pandoc/README.html#epub-metadata)
[Getting Started](http://johnmacfarlane.net/pandoc/getting-started.html)

2
Lesson5.md
View File

@ -1,4 +1,4 @@
## Bibliographer
# Bibliographer
### Goals

2
Lesson6.md
View File

@ -1,4 +1,4 @@
## Styling
# Styling
### Goals

4
index.html
View File

@ -9,7 +9,7 @@
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link rel="stylesheet" href="style/style.css">
<link rel="stylesheet" href="style/html5.css">
</head>
<body>
<content>
@ -39,7 +39,7 @@
<p>Presents how one can manipulate files and issue computing commands using what is known as a terminal.</p></li>
<li><p><a href="Lesson3.html">Lesson 3: Markup / Markdown</a></p>
<p>Introduces a markup language (<a href="http://daringfireball.net/projects/markdown/">Markdown</a>) that is used to format and annotate text.</p></li>
<li><p><a href="/">Lesson 4: (Text/Document) Processor</a></p>
<li><p><a href="Lesson4.html">Lesson 4: (Text/Document) Processor</a></p>
<p>Introduces a text / document processor (<a href="http://johnmacfarlane.net/pandoc/">Pandoc</a>) which converts files written in a format into another.</p></li>
<li><p><a href="/">Lesson 5: Bibliographer</a></p>
<p>Looks at how to compile and maintain a bibliography using open source software (<a href="https://www.zotero.org">Zotero</a>) and export references into a document.</p></li>

4
index.md
View File

@ -1,7 +1,7 @@
---
title: WWWRITING WITH WIT
bibliography: wwwrite.bib
cover: img/DSP6.png
coverpage: img/DSP6.png
---
## Intent
@ -40,7 +40,7 @@ The current site is segmented in six lessons covering the (very) basics of writi
Introduces a markup language ([Markdown](http://daringfireball.net/projects/markdown/)) that is used to format and annotate text.
* [Lesson 4: (Text/Document) Processor](/)
* [Lesson 4: (Text/Document) Processor](Lesson4.html)
Introduces a text / document processor ([Pandoc](http://johnmacfarlane.net/pandoc/)) which converts files written in a format into another.

18
metadata.epub3.yaml Normal file
View File

@ -0,0 +1,18 @@
---
title:
- type: main
text: WWWriting With Wit
- type: subtitle
text: Lessons of modern text writing
creator:
- role: author
text: David Gauthier
- role: editor
text: Erin La Cour
identifier:
- scheme: DOI
text: doi:10.234234.234/33
publisher: Amsterdammm University Press
rights: © 2015 David Gauthier, CC BY-NC
---

0
style/style.css → style/epub3.css
View File

483
style/html5.css Normal file
View File

@ -0,0 +1,483 @@
/*
Style.css
A revised Pandoc/Markdown/Multi-Markdown CSS stylesheet tailored for html5
output for the wwwriting site hosted on ....
Author: gauthiier
Revised: 10 Feb 2015
This file is based on:
Buttondown
A Markdown/MultiMarkdown/Pandoc HTML output CSS stylesheet
Author: Ryan Gray
Date: 15 Feb 2011
Revised: 21 Feb 2012
General style is clean, with minimal re-definition of the defaults or
overrides of user font settings. The body text and header styles are
left alone except title, author and date classes are centered. A Pandoc TOC
is not printed, URLs are printed after hyperlinks in parentheses.
Block quotes are italicized. Tables are lightly styled with lines above
and below the table and below the header with a boldface header. Code
blocks are line wrapped.
All elements that Pandoc and MultiMarkdown use should be listed here, even
if the style is empty so you can easily add styling to anything.
There are some elements in here for HTML5 output of Pandoc, but I have not
gotten around to testing that yet.
*/
/* NOTES:
Stuff tried and failed:
It seems that specifying font-family:serif in Safari will always use
Times New Roman rather than the user's preferences setting.
Making the font size different or a fixed value for print in case the screen
font size is making the print font too big: Making font-size different for
print than for screen causes horizontal lines to disappear in math when using
MathJax under Safari.
*/
/* ---- Front Matter ---- */
/* Pandoc header DIV. Contains .title, .author and .date. Comes before div#TOC.
Only appears if one of those three are in the document.
*/
div#header, header
{
/* Put border on bottom. Separates it from TOC or body that comes after it. */
border-bottom: 1px solid #aaa;
margin-bottom: 0.5em;
}
.title /* Pandoc title header (h1.title) */
{
text-align: center;
}
.author, .date /* Pandoc author(s) and date headers (h2.author and h3.date) */
{
text-align: center;
}
/* Pandoc table of contents DIV when using the --toc option.
NOTE: this doesn't support Pandoc's --id-prefix option for #TOC and #header.
Probably would need to use div[id$='TOC'] and div[id$='header'] as selectors.
*/
div#TOC, nav#TOC
{
/* Put border on bottom to separate it from body. */
border-bottom: 1px solid #aaa;
margin-bottom: 0.5em;
}
@media print
{
div#TOC, nav#TOC
{
/* Don't display TOC in print */
display: none;
}
}
/* ---- Headers and sections ---- */
h1, h2, h3, h4, h5, h6
{
/* font-family: "Helvetica Neue", Helvetica, "Liberation Sans", Calibri, Arial, sans-serif; /* Sans-serif headers */
font-family: "Liberation Serif", "Georgia", "Times New Roman", serif; /* Serif headers */
page-break-after: avoid; /* Firefox, Chrome, and Safari do not support the property value "avoid" */
}
/* Pandoc with --section-divs option */
div div, section section /* Nested sections */
{
margin-left: 2em; /* This will increasingly indent nested header sections */
}
p {}
/* Main container for the whole content / body section -- html5 */
content {
padding: 0.9em;
max-width: 45em;
display: block;
text-align: justify;
margin: auto;
word-wrap: break-word;
}
.references {
text-align: left;
}
blockquote
{
font-style: italic;
}
li /* All list items */
{
}
li > p /* Loosely spaced list item */
{
margin-top: 1em; /* IE: lack of space above a <li> when the item is inside a <p> */
}
ul /* Whole unordered list */
{
}
ul li /* Unordered list item */
{
}
ol /* Whole ordered list */
{
}
ol li /* Ordered list item */
{
}
hr {}
/* ---- Some span elements --- */
sub /* Subscripts. Pandoc: H~2~O */
{
}
sup /* Superscripts. Pandoc: The 2^nd^ try. */
{
}
em /* Emphasis. Markdown: *emphasis* or _emphasis_ */
{
}
em > em /* Emphasis within emphasis: *This is all *emphasized* except that* */
{
font-style: normal;
}
strong /* Markdown **strong** or __strong__ */
{
}
/* ---- Links (anchors) ---- */
a /* All links */
{
/* Keep links clean. On screen, they are colored; in print, they do nothing anyway. */
text-decoration: none;
}
@media screen
{
a:hover
{
/* On hover, we indicate a bit more that it is a link. */
text-decoration: underline;
}
}
@media print
{
a {
/* In print, a colored link is useless, so un-style it. */
color: black;
background: transparent;
}
a[href^="http://"]:after, a[href^="https://"]:after
{
/* However, links that go somewhere else, might be useful to the reader,
so for http and https links, print the URL after what was the link
text in parens
*/
content: " (" attr(href) ") ";
font-size: 90%;
}
}
/* ---- Images ---- */
img
{
/* Let it be inline left/right where it wants to be, but verticality make
it in the middle to look nicer, but opinions differ, and if in a multi-line
paragraph, it might not be so great.
*/
vertical-align: middle;
max-width: 100%;
}
div.figure /* Pandoc figure-style image */
{
/* Center the image and caption */
margin-left: auto;
margin-right: auto;
text-align: center;
font-style: italic;
}
/** EXXXTRA **/
figure /* Pandoc figure-style image */
{
/* Center the image and caption */
margin-left: auto;
margin-right: auto;
text-align: center;
font-style: italic;
}
p.caption /* Pandoc figure-style caption within div.figure */
{
/* Inherits div.figure props by default */
}
/* ---- Code blocks and spans ---- */
pre, code
{
background-color: #fdf7ee;
/* BEGIN word wrap */
/* Need all the following to word wrap instead of scroll box */
/* This will override the overflow:auto if present */
white-space: pre-wrap; /* css-3 */
white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */
white-space: -pre-wrap; /* Opera 4-6 */
white-space: -o-pre-wrap; /* Opera 7 */
word-wrap: break-word; /* Internet Explorer 5.5+ */
/* END word wrap */
}
pre /* Code blocks */
{
/* Distinguish pre blocks from other text by more than the font with a background tint. */
padding: 0.5em; /* Since we have a background color */
border-radius: 5px; /* Softens it */
/* Give it a some definition */
border: 1px solid #aaa;
/* Set it off left and right, seems to look a bit nicer when we have a background */
margin-left: 0.5em;
margin-right: 0.5em;
}
@media screen
{
pre
{
/* On screen, use an auto scroll box for long lines, unless word-wrap is enabled */
white-space: pre;
overflow: auto;
/* Dotted looks better on screen and solid seems to print better. */
border: 1px dotted #777;
}
}
code /* All inline code spans */
{
}
p > code, li > code /* Code spans in paragraphs and tight lists */
{
/* Pad a little from adjacent text */
padding-left: 2px;
padding-right: 2px;
}
li > p code /* Code span in a loose list */
{
/* We have room for some more background color above and below */
padding: 2px;
}
/* ---- Math ---- */
span.math /* Pandoc inline math default and --jsmath inline math */
{
/* Tried font-style:italic here, and it messed up MathJax rendering in some browsers. Maybe don't mess with at all. */
}
div.math /* Pandoc --jsmath display math */
{
}
span.LaTeX /* Pandoc --latexmathml math */
{
}
eq /* Pandoc --gladtex math */
{
}
/* ---- Tables ---- */
/* A clean textbook-like style with horizontal lines above and below and under
the header. Rows highlight on hover to help scanning the table on screen.
*/
table
{
border-collapse: collapse;
border-spacing: 0; /* IE 6 */
border-bottom: 2pt solid #000;
border-top: 2pt solid #000; /* The caption on top will not have a bottom-border */
/* Center */
margin-left: auto;
margin-right: auto;
}
thead /* Entire table header */
{
border-bottom: 1pt solid #000;
background-color: #eee; /* Does this BG print well? */
}
tr.header /* Each header row */
{
}
tbody /* Entire table body */
{
}
/* Table body rows */
tr {
}
tr.odd:hover, tr.even:hover /* Use .odd and .even classes to avoid styling rows in other tables */
{
background-color: #eee;
}
/* Odd and even rows */
tr.odd {}
tr.even {}
td, th /* Table cells and table header cells */
{
vertical-align: top; /* Word */
vertical-align: baseline; /* Others */
padding-left: 0.5em;
padding-right: 0.5em;
padding-top: 0.2em;
padding-bottom: 0.2em;
}
/* Removes padding on left and right of table for a tight look. Good if thead has no background color*/
/*
tr td:last-child, tr th:last-child
{
padding-right: 0;
}
tr td:first-child, tr th:first-child
{
padding-left: 0;
}
*/
th /* Table header cells */
{
font-weight: bold;
}
tfoot /* Table footer (what appears here if caption is on top?) */
{
}
caption /* This is for a table caption tag, not the p.caption Pandoc uses in a div.figure */
{
caption-side: top;
border: none;
font-size: 0.9em;
font-style: italic;
text-align: center;
margin-bottom: 0.3em; /* Good for when on top */
padding-bottom: 0.2em;
}
/* ---- Definition lists ---- */
dl /* The whole list */
{
border-top: 2pt solid black;
padding-top: 0.5em;
border-bottom: 2pt solid black;
}
dt /* Definition term */
{
font-weight: bold;
}
dd+dt /* 2nd or greater term in the list */
{
border-top: 1pt solid black;
padding-top: 0.5em;
}
dd /* A definition */
{
margin-bottom: 0.5em;
}
dd+dd /* 2nd or greater definition of a term */
{
border-top: 1px solid black; /* To separate multiple definitions */
}
/* ---- Footnotes ---- */
a.footnote, a.footnoteRef { /* Pandoc, MultiMarkdown footnote links */
font-size: small;
vertical-align: text-top;
}
a[href^="#fnref"], a.reversefootnote /* Pandoc, MultiMarkdown, ?? footnote back links */
{
}
@media print
{
a[href^="#fnref"], a.reversefootnote /* Pandoc, MultiMarkdown */
{
/* Don't display these at all in print since the arrow is only something to click on */
display: none;
}
}
div.footnotes /* Pandoc footnotes div at end of the document */
{
}
div.footnotes li[id^="fn"] /* A footnote item within that div */
{
}
/* You can class stuff as "noprint" to not print.
Useful since you can't set this media conditional inside an HTML element's
style attribute (I think), and you don't want to make another stylesheet that
imports this one and adds a class just to do this.
*/
@media print
{
.noprint
{
display:none;
}
}

56
style/template.epub3 Normal file
View File

@ -0,0 +1,56 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops"$if(lang)$ xml:lang="$lang$"$endif$>
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<title>$pagetitle$</title>
$if(quotes)$
<style type="text/css">
q { quotes: "“" "”" "‘" "’"; }
</style>
$endif$
$if(highlighting-css)$
<style type="text/css">
$highlighting-css$
</style>
$endif$
$for(css)$
<link rel="stylesheet" type="text/css" href="$css$" />
$endfor$
</head>
<body$if(coverpage)$ id="cover"$endif$>
$if(titlepage)$
<section epub:type="titlepage">
$for(title)$
$if(title.type)$
<h1 class="$title.type$">$title.text$</h1>
$else$
<h1 class="title">$title$</h1>
$endif$
$endfor$
$if(subtitle)$
<h1 class="subtitle">$subtitle$</h1>
$endif$
$for(author)$
<h2 class="author">$author$</h2>
$endfor$
$for(creator)$
<h2 class="$creator.type$">$creator.text$</h2>
$endfor$
$if(publisher)$
<p class="publisher">$publisher$</p>
$endif$
$if(date)$
<p class="date">$date$</p>
$endif$
$if(rights)$
<div class="rights">$rights$</div>
$endif$
</section>
$else$
$body$
$endif$
</body>
</html>

4
style/template.html5
View File

@ -44,9 +44,9 @@ $if(title)$
$if(subtitle)$
<h1 class="subtitle">$subtitle$</h1>
$endif$
$if(cover)$
$if(coverpage)$
<figure>
<img src="$cover$"/>
<img src="$coverpage$"/>
</figure>
$endif$
$for(author)$