Courses/Hybrid publishing resources
<slidy theme="a" />
TO DO
- can Hybrid Publishing Resources guide the whole class?
- show that conversion as single command
- use make to generate a batch conversion
- proof read and tidy
publicationstation.wdka.hro.nl/wiki
Hybrid Publishing
Focus
Transforming a source (manuscript) into multiple publishable outputs, within a hybrid publishing workflow
Hybrid Publishing Workflow
- various outcomes from one workflow
- constant connection between source-content and outcome
- avoiding repeating tasks
Hybrid Publishing Workflow
How?
How can we achieve a publishing workflow where we can go from the source (a word document, a wiki page, a webpage) to several outputs (an EPUB, a website, an animated gif, an inDesign project)?
Structure
By putting the content into an explicit structure, which can withstand those transformations.
So what is a title (heading) in a format, remains a title when translated to a different format.
How to achieve explicit structure?
An explicit structure is achieved by marking the text with structural information.
marking the text = markup
Markup languages
HTML:
<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>
= 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
# 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
Pandoc
pandoc: software for converting between markups with
******************
mark a text in MS Word/Libre Office
create a .docx file and mark it up with a few of the following paragraph and characters styles:
- headings
- body text
- block quotes: indented blocks of text
- footnotes
- hyperlinks
- Preformatted text
- Bold
- Italics
Save in .docx
convert
Convert your docx file into a an HTML file using Pandoc.
- shell
pandoc -f docx -t html5 -s input.docx -o output.html
pandoc - program dedicate to the conversion between different markups.
-f - option standing for “from”, is followed by the input format;
-t - option standing for “to”, is followed by the output format;
-s - option standing for “standalone”, produces output with an appropriate header and footer;
-o - option for file output;
input.docx - docx input filename - you need to replace it by its actual name
convert once more, now toward Markdown
-t markdown Option: toward Markdown
--atx-headeres Option: use nice Markdown headers
Why Markdown ?
- simple
- only one way to create a structure
- compatible with HTML, but easier to read and write
- allows the inclusion of HTML tags.
- any plain text editor such as Sublime Text or Gedit can edit Markdown files.
- there are WYSIWYG Markdown editors such as MacDown.
*******
stream-line it
This same approach for converting between markups using Pandoc can be automated.
Since computers are good at doing repetitive and boring tasks, we can take advantage from it.
We can store commands in scripts and have them perform the same task on multiple source files, producing multiple outputs (E.G. EPUB, ICML, HTML).
Overview
In this process, from several .docx files we'll try to create two outputs:
- an ICML files for inDesign
- an EPUB
And we'll also try to keep a connection between the source and its outcomes.
Steps
This hybrid publishing recipe will involve the following steps:
- .docx - manuscript - editing the manuscript using word styles
- Markdown - source - converting the manuscript (.docx) files to Markdown (.md) files.
- ICML - output - converting Markdown source files into ICML files that can be imported into inDesign
- EPUB - output -converting the compound Markdown (book.md) into an EPUB
Note: The section "6.3. Do-it-yourself EPUB using Pandoc" form From Print to Ebooks is an important complement to this tutorial and set of tools
Makefile
My proposal involves using a Makefile to automate the conversions between markups.
Makefiles are used in the free-software community to compile source code into running applications. However they are not more than a notebook of commands to process stuff and generate other stuff from it. E.g. create executables programs out of source code files. There is nothing stopping us from using makefiles to automate conversions between markup-languages.
Read more about Makefiles in the context of hybrid publishing:
- blog post Make Book by Michael Murtaugh
- Report on the Don Marti's presentation at SCALE
- GNU Make official site
Recipe Preparation
http://27.media.tumblr.com/tumblr_lv1oy5tBwQ1qm4heyo1_500.gif
clone Hybrid Publishing Resources
- Download the Hybrid Publishing Resources code repository into your computer.
- Move the downloaded .zip into a dedicated folder (inside DATASTORAGE in WdKA computers).
- Unzip
- In terminal change directory
cdto the unzip folder
download content
- Download http://stuff2233.club/~iceking/content.zip
- Unzip
content.zip contains a couple of .docx files, which you will use as your content. Other structured(with Styles) .docx files could be used.
There is also a .ttf font file and an image.
end of recipe preparation / start cooking
http://jerichogaming.weebly.com/uploads/1/3/9/8/13982770/______7978332_orig.gif
0. Folder structure
To create folder structure, which will be understood by the scripts from this repository, you need to run:
./scripts/create_folders.sh
This script will generate the following folder structure, which you'll use to store the files essentially for the creation of the EPUB.
├── docx ├── epub ├── icml ├── md │ └── imgs └── scripts
1. Manuscript: .docx
This is a preparatory stage. Yet it is important for the series of conversions that will lead to the different publication's outputs.
You'll be editing the text document handed by the author - the manuscript -, possibly according to a style-guide.
(See a text in MS Word/Libre Office/Open Office previous section on how to structure a .docx file)
2. Source: converting the manuscript files to Markdown files
Run: make markdowns to start this stage.
This command will convert all the .docx files inside the docx/folder into corresponding markdown files inside md/ folder.
The resulting markdown files are the source files, from which all of the publication's outputs will be generated.
2.1 Images in Markdown
At this stage you should insert the images onto the essays, now in markdown format.
First of all, you need to save all the images included in the essays in the folder md/imgs/ Then place the images on the markdown document: 
Don't forget to include captions, if the image has them. Markdown captions will become visible, and associated to the image in the EPUB output.
3. make icmls - ICML files for inDesign
Run: make icmls to start this stage.
The individual Markdown source files, stored in md/, can be converted into ICML files which can be imported into inDesign.
Read more on ICML files and inDesign in section
4. make book.epub
4.0 make book.md
This step is essential to the creation of the EPUB. It generates a single Markdown file book.md and save it it inside the md/ folder. However, you don't have to perform this step, as the makefile does it for you.
book.md consists of the content from all the individual Markdow files inside the md/ folder, in alphabetical order (00 to ZZ). If you want to change the order the publication, you can change the filenames in order to do so.
Note: the Markdown filenames should NOT contain spaces or dots, except for the extension .md
To generate this single book.md, run: make book.md .
4.1 make book.epub (EPUB)
To obtain the epub file book.epub run: make book.epub to start this stage.
4.1.1 Essential files for EPUB =
To produce an EPUB a few resources (files) are needed, namely the cover image, metadata, stylesheet, and fonts.
This files will strongly influence the EPUB's outcome, and consequently should be edited for each publication or series of publication
epub/metadata.xml- EPUB metadataepub/styles.epub.css- EPUB css style-sheet MUST BE EDITEDepub/cover.jpg- EPUB cover MUST BE CHANGED
4.1.2 Fonts (optional) for EPUB
lib/ is folder for storing custom fonts, that will be used in the EPUB
Note on the use of custom fonts: If you choose to use fonts, make sure to change the makefile to include the use of fonts in the makefile epub rule, such as in the rule bellow, where --epub-embed-font=lib/UbuntuMono-B.ttf \ was added to allow for the use of the Ubuntu Mono font. Also include the font on th EPUB style-sheet with @font-face rule
4.1.3 EPUB check
The health of the created EPUB can be checked with http://validator.idpf.org/
4.1.5 make book.epub : An iterative process
This work is in many way as an iterative process.
You work in circles: changing the source files (markdown files, the EPUB's stylesheet, the EPUB's metadata) and seeing the results of those changes in Calibre (or other ebook-viwerer)
working with ICML files
ICML files are useful, since they ensure that the structural information of the Markdown source files is also present in the inDesign projects, which use them.
Another point in favor of ICML is the possibility of updating the content and structure of the inDesign projects, by updating the Markdown source files, converting the once more to ICML. For this to happens is however necessary that inDesign remains linked to its source, and that the designers works with paragraph and chapter styles, instead of directly into the text.
Note: malformatted links in the markdown files will create problems when imported into inDesign.
Place ICMLs
Open inDesign and ...
Place your output.icml in a inDesign project.
The Place function is in: File > Place (shortcut: Apple+D)
Design with Styles
Style the content using paragraph and character styles.
Paragraph/Characters styles are in: Type > Paragraph/Character Styles
ICML Content updates
Using Sublime Text, edit one ICML file adding some text to it.
See the content being updated in inDesign.
Hands off content
In in inDesgin content shall remain untouched until the last moment
If you change the content of the articles inDesign, the link between the inDesign content and its source ICML file will be lost, and it no longer be able to be updated.
This "disconnection" should only be the last step to be done on your design workflow.
****=
software used
- Shell terminal - a text-based interface to your file system. there are plenty of terminal tutorial online, here are some:
- pandoc - markup converter software
- plain-text editor: Sublime Text or Gedit
- Markdown syntax: http://daringfireball.net/projects/markdown/syntax provides a good overview not only of the syntax, but also the philosophy behind Markdown.
