Editing Courses/Wikis-Publishing Platforms (section)

=Day 2=
==The Importance of Being Markup==
''Converting wiki content into other formats''.

==Markups==
Wiki syntax is a [http://en.wikipedia.org/wiki/Markup_language markup language]. Markup languages are exclusive to plain text formats (as opposed to rich text or binary formats). In plain-text file text-formating is applied to the text through a series of "marks" or tags. The marks or tags are like instructions, on how each marked segment of text should be interpreted or rendered. 

==Markups: write/interpret==
You have be doing been using the wiki Markup during this workshop. 
You've probably noticed how, when in writing mode, symbols as <code>=heading= '''bold''' [[Page]]</code> '''are interpreted and given a specific meaning or style when the wiki page is rendered''', or in other words, is in read mode.

Like the markup of the following segment, originates a styled and structured [[Revenge of the Text|page]].
<pre>
= Revenge of the Text =

There is a room in the '''Musée d’Orsay''' that I call the ''room of possibilities''.

That room contains:
* a snow flake
* the end of a cloud
* a bit of nothing
</pre>

==Markup: explicit structure==
One of the advantages of markup languages is that they imply an '''explicit text structure'''.

In order words, markups force you to declare: 
* "this sentence is a section heading": <code>=section heading=</code> 
* "this word is bold": <code>bold '''word'''.</code>
* "this hyperlink has x as URL and" <code>[x-URL title]</code>

You are not allowed to give meaning or structure to the text by visually styling (like you'd do in inDesign or Word).

'''Meaning or structure can only be given to the text semantically'''. That means adding ''marks'' to the segments of text we want to format. 

==Markups: interchangeable==
One advantage of this explicit semantic formating is that conversions between different markups (Wiki, HTML, Markdown, LaTeX, etc) are made easy.

In most cases markups have HTML as a reference, allowing only formating options that are available in HTML. 
 
Consequently converting between markups is easy. 

A markups converter software has to ''only'' to know the meaning of all the '''meta-characters''' in a markup and what are the corresponding '''meta-characters''' in another markup. 

If the software knows that it can convert <pre>=title=</pre> to <pre><h1>title</h1></pre>, <pre># title</pre>, <pre>\section{title}</pre> 

==Examples: the same text in different Markup ==
[http://en.wikipedia.org/wiki/HTML HTML]:
<source lang="html5">
<h1>Revenge of the Text</h1>
 <p>There is a room in the <strong>Musée d’Orsay</strong> that I call the <em>room of possibilities</em>.</p>
 <p>That room contains:</p>
 <ul>
  <li>a snow flake</li>
  <li>the end of a cloud</li>
  <li>a bit of nothing</li>
 </ul>
</source>

[http://en.wikipedia.org/wiki/Wiki_markup Wiki markup]:
<source lang="text">
= Revenge of the Text =
There is a room in the '''Musée d’Orsay''' that I call the ''room of possibilities''.

That room contains:
* a snow flake
* the end of a cloud
* a bit of nothing
</source>
 
[http://en.wikipedia.org/wiki/Markdown Markdown]:
<source lang="text">
# Revenge of the Text
There is a room in the **Musée d’Orsay** that I call the *room of possibilities*.

That room contains:
* a snow flake
* the end of a cloud
* a bit of nothing
</source>

[http://en.wikipedia.org/wiki/LaTeX LaTeX]
<source lang="latex">
\section{Revenge of the Text}\label{revenge-of-the-text}

There is a room in the \textbf{Musée d'Orsay} that I call the \emph{room
of possibilities}.

That room contains:

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  a snow flake
\item
  the end of a cloud
\item
  a bit of nothing
\end{itemize}
</source>

== Pandoc ==
One popular software for converting between markups is [http://johnmacfarlane.net/pandoc '''Pandoc''']

[[File:pandoc_diagram.png]]

==Working with Pandoc==
Pandoc is a command-line tool. This means that instead of a GUI it uses a [http://en.wikipedia.org/wiki/Command-line_interface command line interpreter] or shell, where the interaction with it is based on text commands.
  
There a few web interfaces to Pandoc, such as http://pandoc.org/try/, but they are not as flexible as the command-line interface to Pandoc.

==Pandoc conversions: wiki to HTML==
Convert a file containing mediawiki syntax, into a an HTML file.

 pandoc --from mediawiki --to html5 --standalone input.wiki --output=output.html

'''pandoc''' - program dedicate to the conversion between different markups.

'''--from''' - option standing for “from”, is followed by the input format;

'''--to''' - option standing for “to”, is followed by the output format;

'''--standalone''' - option standing for “standalone”, produces output with an appropriate header and footer;

'''--output''' - option for file output;

'''input.wiki''' - plain-text file with wiki syntax  - you need to replace it by its actual name

==Pandoc conversions: HTML to wiki==
 pandoc --from mediawiki --to html5 --standalone input.wiki --output=output.html

==Pandoc conversions: wiki to ICML==
ICML files can be imported into inDesign. See [[Hybrid publishing/publishing resources#working_with_ICML_files ]] for more information.


==Pandoc conversions: wiki to EPUB==
It is also possible to use Pandoc to produce an EPUB from a single <pre>.wiki</pre> file, or any other markup accepted by Pandoc.  

A few extra resources, such the cover image, metadata, and stylesheet should be included, as they  strongly influence the EPUB's outcome.

 pandoc --from wiki --to epub3 --self-contained --epub-chapter-level=1 --epub-stylesheet=styles.epub.css  --epub-cover-image=cover.jpg --epub-metadata=metadata.xml --toc-depth=1 --output=book.epub     book.wiki 

New options:
* '''--epub-chapter-level=1''' - at what titles' level chapters occur: heading 1 
* '''--epub-stylesheet=styles.epub.css'''  - css style sheet for epub
* '''--epub-cover-image=cover.jpg'''  - epub cover image
* '''--epub-metadata=metadata.xml''' - 
* '''--toc-depth=1'''

Example of metadata.xml
<source lang="xml">
<dc:title id="epub-title-1">MAIN TITLE</dc:title>
<meta refines="#epub-title-1" property="title-type">main</meta>
<dc:publisher>Your Publisher</dc:publisher>    
<dc:date id="epub-date">2015</dc:date>
<dc:language>en-US</dc:language>
<dc:creator id="epub-creator-0">AUTHOR'S NAME</dc:creator>
<meta refines="#epub-creator-0" property="role" scheme="marc:relators">aut</meta>
<dc:contributor id="epub-contributor-1">EDITOR'S NAME</dc:contributor>
<meta refines="#epub-contributor-1" property="role" scheme="marc:relators">edt</meta>
<dc:contributor id="epub-contributor-5">DESIGNER'S NAME</dc:contributor>
<meta refines="#epub-contributor-5" property="role" scheme="marc:relators">dsr</meta>
<dc:subject>TAGS, SEPARATED BY, COMAS</dc:subject>
<dc:description>PUBLICATION SYNOPSIS</dc:description>
</source>


==Conclusion: wiki as hybrid publishing tools==
Hopefully these examples make more clear what I stated in day#1 wikis are inherently hybrid publishing tools, as 
* wikis are about publishing quickly and easily
* wiki content can be easily converted to other formats, since it uses a Markup languange.

As a result many derived works, or re-mediations of wiki content exist. From the more pragmatic examples, such as Wikipedia Export book function, [http://toneelstof.be/ Toneelstof], [http://beyond-social.org/ Beyond Social], or this presentation (both wiki content and slide show); To more artistic interventions such as [http://p-dpa.net/work/iraq-war-wikihistoriography/ The Iraq War: A History of Wikipedia Changelogs] by James Bridle or [http://www.epicpedia.org/ Epicpedia] by Annemieke van der Hoek.


We'll continue looking re-mediations of wiki content. In the next day we'll focus on the MediaWiki API, an interface to Mediawiki wikis, which allows  retrieving and editing content programatically.