Difference between revisions of "Courses/Hybrid publishing resources"
Line 147: | Line 147: | ||
* [http://www.gnu.org/software/make/ GNU Make official site ] | * [http://www.gnu.org/software/make/ GNU Make official site ] | ||
== | |||
== overview == | |||
The conversion from a manuscript to EPUB it is a step by step process, that consists of: | |||
# '''.docx - Manuscript''' - .docx - editing the manuscript according to the INC style guide | |||
# '''Markdown - Source''' - converting the manuscript files to Markdown files. | |||
# '''ICML files for inDesign''' - converting the individual Markdown source into ICML files that can be imported into inDesign | |||
# '''EPUB Output''' -converting the compound Markdown source file to an EPUB | |||
Note: The section "6.3. Do-it-yourself EPUB using Pandoc" form [[From%20Print%20to%20Ebooks|http://networkcultures.org/blog/publication/from-print-to-ebooks-a-hybrid-publishing-toolkit-for-the-arts/]] is an important complement to this tutorial and set of tools | |||
[[Image:http://networkcultures.org/wp-content/uploads/2015/02/workflow.png]] | |||
== (install Make) == | |||
* Download http://rudix.org/download/2014/10.8/make-3.82-4.pkg | |||
* Using the finder go to Downloads and begin installing that package | |||
== clone Hybrid Publishing Resources == | |||
* Download the [https://gitlab.com/DigitalPublishingToolkit/Hybrid-Publishing-Resources/tree/wdka code repository] into your computer. Download link: https://gitlab.com/DigitalPublishingToolkit/Hybrid-Publishing-Resources/repository/archive.zip?ref=wdka | * Download the [https://gitlab.com/DigitalPublishingToolkit/Hybrid-Publishing-Resources/tree/wdka code repository] into your computer. Download link: https://gitlab.com/DigitalPublishingToolkit/Hybrid-Publishing-Resources/repository/archive.zip?ref=wdka | ||
* Move the downloaded .zip into a dedicated folder (inside DATASTORAGE in WdKA computers). | * Move the downloaded .zip into a dedicated folder (inside DATASTORAGE in WdKA computers). | ||
* Unzip | * Unzip | ||
* In terminal change directory <code>cd </code> to the unzip folder | * In terminal change directory <code>cd </code> to 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. Any other structured (with Styles).docx files could be used. | |||
There is also a .ttf font file and an image. | |||
---- | |||
==start cooking== | |||
== 0. Folder structure == | |||
To create folder structure, which will be understood by the scripts from this repository, you need to run: | |||
<code>./scripts/create_folders.sh</code> | |||
This script will generate the following folder structure, which you'll use to store the files essentially for the creation of the EPUB. <code>├── docx ├── epub ├── icml ├── md │ └── imgs └── scripts</code> | |||
== 1. Manuscript: .docx == | |||
This is a preparatory stage. Yet it is highly 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 -, according to [[INC styleguide]]: section "Document Formatting/Layout", subsection "General". | |||
Do pay special attention to this part of the [[INC styleguide]]. Following it rigorously will ensure that your manuscripts will convert flawlessly to markdown (the next step). | |||
== 2. Source: converting the manuscript files to Markdown files == | |||
Run: <code>make markdowns</code> to start this stage. | |||
This command will '''convert all the <code>.docx</code> files inside the <code>docx/</code>folder into corresponding markdown files inside <code>md/ folder</code>'''. | |||
The resulting '''markdown files are meant as source files''', from which all of the publication's outputs will be generated. | |||
The reason for using markdown as a the ''source format'' comes from easiness by which they can be read and written, they high compatibility with other markup languages (HTML, ICML) and the corresponding outputs (EPUB/Website, inDesign Project) | |||
=== 2.1 Images in Markdown === | |||
At this stage you should insert the images in to the essay, now in markdown format. | |||
First of all, you need to '''save all the images included in the essays in the folder''' <code>md/imgs/</code> Then '''place the images on the markdown files''': <code>![My image caption](imgs/myImage.jpg)</code> | |||
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 | |||
=== 2.2 Metadata in Markdown === | |||
Each of the resulting markdown files contain a '''metadata header'''. You can fill those fields with the corresponding information. | |||
Note on metadata: You can change the metadata fields and values that are added to each article, by editing the template file used to generate the markdown files: <code>essay.md.template</code> | |||
'''Masterclass:''' In <code>md/1_1-Hart_Keith.md</code> complete the metadata, and insert images in their correct location. | |||
== 3 ICML files for inDesign == | |||
Run: <code>make icmls</code> to start this stage. | |||
The individual Markdown source files, stored in <code>md/</code>, can be converted into ICML files which can be imported into inDesign. | |||
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.''' | |||
= 4. '''Outputs''' = | |||
== (Assembling the Markdown source files into book.md) == | |||
This step is essential to the creation of the EPUB. However, '''you don't have to perform this step, as the makefile does it for you'''. | |||
It generates a single Markdown file <code>book.md</code> and save it it inside the <code>md/</code> folder. <code>book.md</code> is comprised of the content from all the individual Markdown source files inside the <code>md/</code> folder, in alphabetical order (00 to ZZ). | |||
The <code>book.md</code> file will, in step 4.1 give origin to the | |||
If you need for any reason to generate this single Markdown file <code>book.md</code>, run: <code>make book.md</code> . | |||
== 4.1 EPUB Output == | |||
<code>book.epub</code> | |||
Run: <code>make book.epub</code> to start this stage. | |||
=== Essential files: === | |||
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 | |||
* <code>epub/metadata.xml</code> - EPUB metadata | |||
* <code>epub/styles.epub.css</code> - EPUB css style-sheet '''MUST BE EDITED''' | |||
* <code>epub/cover.jpg</code> - EPUB cover '''MUST BE CHANGED''' | |||
=== Optional fonts: === | |||
* lib/ - 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 <code>--epub-embed-font=lib/UbuntuMono-B.ttf \</code> was added to allow for the use of the Ubuntu Mono font. Also include the font on th EPUB style-sheet with <code>@font-face</code> rule | |||
== 4.2 EPUB check == | |||
The health of the created EPUB can be checked with http://validator.idpf.org/ | |||
== 4.3 EPUB edit == | |||
Once it has been created the EPUB can be change manually by using Calibre's recent tool [http://manual.calibre-ebook.com/edit.html Edit Book] | |||
== the makefile == | == the makefile == |
Revision as of 17:58, 11 March 2015
<slidy theme="a" />
publicationstation.wdka.hro.nl/wiki
Hybrid Publishing
Focus
Transforming a source (manuscript) into multiple publishable outputs
In 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.
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
http://johnmacfarlane.net/pandoc/diagram.png
markup a text in MS Word/Libre Office/Open Office
- styles; Test on WDKA
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 command
convert once more, now to EPUB
Can you instead of converting the .docx into HTML convert into an EPUB?
- clues
Markdown
Markdown as the source file.
- link to Markdown syntax
Any plain text editor such as Sublime Text or Gedit can be used to edit Markdown files. There are also WYSIWYG Markdown editors such as MacDown.
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. E.g.
<!-- an html comment --> <span id="mrspan">a div</span>
convert once more, now to Markdown
- pandoc argument
****
stream line: makefile
This same approach of converting between markups using Pandoc can be automated through scripts that execute the commands we have been writing in the terminal.
Ands since computers are good at doing repetitive and boring tasks, we can take advantage from it.
We can make them perform the same task on multiple source files, and make them produce multiple outputs (E.G. EPUB, ICML, HTML).
makefile
My proposal involves using a Makefile to automate conversions between markup-languages
Makefiles are usually used to 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:
- the blog post Make Book by Michael Murtaugh
- the report on the Don Marti's presentation at SCALE
- GNU Make official site
overview
The conversion from a manuscript to EPUB it is a step by step process, that consists of:
- .docx - Manuscript - .docx - editing the manuscript according to the INC style guide
- Markdown - Source - converting the manuscript files to Markdown files.
- ICML files for inDesign - converting the individual Markdown source into ICML files that can be imported into inDesign
- EPUB Output -converting the compound Markdown source file to an EPUB
Note: The section "6.3. Do-it-yourself EPUB using Pandoc" form http://networkcultures.org/blog/publication/from-print-to-ebooks-a-hybrid-publishing-toolkit-for-the-arts/ is an important complement to this tutorial and set of tools
File:Http://networkcultures.org/wp-content/uploads/2015/02/workflow.png
(install Make)
- Download http://rudix.org/download/2014/10.8/make-3.82-4.pkg
- Using the finder go to Downloads and begin installing that package
clone Hybrid Publishing Resources
- Download the code repository into your computer. Download link: https://gitlab.com/DigitalPublishingToolkit/Hybrid-Publishing-Resources/repository/archive.zip?ref=wdka
- Move the downloaded .zip into a dedicated folder (inside DATASTORAGE in WdKA computers).
- Unzip
- In terminal change directory
cd
to 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. Any other structured (with Styles).docx files could be used.
There is also a .ttf font file and an image.
start cooking
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 highly 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 -, according to INC styleguide: section "Document Formatting/Layout", subsection "General".
Do pay special attention to this part of the INC styleguide. Following it rigorously will ensure that your manuscripts will convert flawlessly to markdown (the next step).
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 meant as source files, from which all of the publication's outputs will be generated.
The reason for using markdown as a the source format comes from easiness by which they can be read and written, they high compatibility with other markup languages (HTML, ICML) and the corresponding outputs (EPUB/Website, inDesign Project)
2.1 Images in Markdown
At this stage you should insert the images in to the essay, 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 files: ![My image caption](imgs/myImage.jpg)
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
2.2 Metadata in Markdown
Each of the resulting markdown files contain a metadata header. You can fill those fields with the corresponding information.
Note on metadata: You can change the metadata fields and values that are added to each article, by editing the template file used to generate the markdown files: essay.md.template
Masterclass: In md/1_1-Hart_Keith.md
complete the metadata, and insert images in their correct location.
3 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.
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.
4. Outputs
(Assembling the Markdown source files into book.md)
This step is essential to the creation of the EPUB. However, you don't have to perform this step, as the makefile does it for you.
It generates a single Markdown file book.md
and save it it inside the md/
folder. book.md
is comprised of the content from all the individual Markdown source files inside the md/
folder, in alphabetical order (00 to ZZ).
The book.md
file will, in step 4.1 give origin to the
If you need for any reason to generate this single Markdown file book.md
, run: make book.md
.
4.1 EPUB Output
book.epub
Run: make book.epub
to start this stage.
Essential files:
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
Optional fonts:
- lib/ - 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.2 EPUB check
The health of the created EPUB can be checked with http://validator.idpf.org/
4.3 EPUB edit
Once it has been created the EPUB can be change manually by using Calibre's recent tool Edit Book
the makefile
*****
IMCL
- to be edited
Recipe Ingredients
- empty folder - to create the recipe
- content in a markup language: HTML (or wiki syntax)
- terminal - a text-based interface to your file system
- pandoc - markup converter software
- plain-text editor: Sublime Text or Gedit
- your favorite text layout software
Testing the Recipe
Testing the Recipe step#1
In on empty folder in your computer save 1 BS article in HTML.
Testing the Recipe step#2
Convert that HTML file into an ICML file.
pandoc -f html -t icml -s input.html -o output.icml
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.html - html input filename - you need to replace it by its actual name
Testing the Recipe step#3
Open inDesign and ...
Place your output.icml in a inDesign project.
The Place function is in: File > Place (shortcut: Apple+D)
Testing the Recipe step#4
Style the content using paragraph and character styles.
Paragraph/Characters styles are in: Type > Paragraph/Character Styles
Testing the Recipe step#5
Content updates
Using Sublime Text, edit the source html file adding something or extracting something to it.
Repeat the whole recipe, so that you see the content being updated in inDesign.
Recipe Warning
Content should 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.
Recipe Tips
Loading paragraph styles
Recipe Questions
Can CSS rules be imported and used as inDesign Paragraph/Character Styles ?
Can inDesign styles be exported as CSS style-sheets ?
+ ... ?
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.