Hybrid publishing resources - Revision history

Andre: /* 0. Folder structure */

2016-05-27T09:21:19Z

0. Folder structure

← Older revision		Revision as of 09:21, 27 May 2016
Line 41:		Line 41:
	To create folder structure, which will be understood by the scripts from this repository, you need to run:		To create folder structure, which will be understood by the scripts from this repository, you need to run:

	<code>make ~~folderd~~</code>		<code>make folders</code>

	This script will generate the following folder structure, which you'll use to store the files essentially for the creation of the EPUB.		This script will generate the following folder structure, which you'll use to store the files essentially for the creation of the EPUB.

Andre: /* 0. Folder structure */

2016-05-27T09:20:30Z

0. Folder structure

← Older revision		Revision as of 09:20, 27 May 2016
Line 41:		Line 41:
	To create folder structure, which will be understood by the scripts from this repository, you need to run:		To create folder structure, which will be understood by the scripts from this repository, you need to run:

	<code>~~./scripts/create_folders.sh~~</code>		<code>make folderd</code>

	This script will generate the following folder structure, which you'll use to store the files essentially for the creation of the EPUB.		This script will generate the following folder structure, which you'll use to store the files essentially for the creation of the EPUB.
Line 52:		Line 52:
	└── scripts		└── scripts
	</pre>		</pre>


	= 1. Manuscript: .docx =		= 1. Manuscript: .docx =

Andre: /* clone Hybrid Publishing Resources */

2016-05-27T09:14:13Z

clone Hybrid Publishing Resources

← Older revision		Revision as of 09:14, 27 May 2016
Line 28:		Line 28:
	'''Recipe Preparation '''		'''Recipe Preparation '''

	== ~~clone~~ Hybrid Publishing Resources ==		== Download Hybrid Publishing Resources ==
	* '''[https://~~gitlab~~.com/~~DigitalPublishingToolkit/Hybrid~~-~~Publishing-Resources~~/~~repository~~/archive.zip~~?ref=wdka~~ Download the zip ]''' from [https://~~gitlab~~.com/~~DigitalPublishingToolkit/Hybrid~~-~~Publishing-Resources/tree~~/~~wdka~~ Hybrid Publishing Resources code repository] to your computer.		* '''[https://github.com/wdka-publicationSt/HPR/archive/master.zip Download the zip ]''' from [https://github.com/wdka-publicationSt/HPR Hybrid Publishing Resources code repository] to your computer.
	* Move the downloaded .zip to a dedicated folder.		* Move the downloaded .zip to a dedicated folder.
	* Unzip		* Unzip
Line 36:		Line 36:
	-------		-------

	'''Start Cooking'''		'''Start Cooking'''

	== 0. Folder structure ==		== 0. Folder structure ==

Andre at 09:59, 26 May 2016

2016-05-26T09:59:53Z

← Older revision		Revision as of 09:59, 26 May 2016
Line 12:		Line 12:

	And we'll also try to keep a connection between the '''source''' and its '''outcomes'''.		And we'll also try to keep a connection between the '''source''' and its '''outcomes'''.



Line 25:		Line 24:
	* [http://www.gnu.org/software/make/ GNU Make official site ]		* [http://www.gnu.org/software/make/ GNU Make official site ]

			-----

	= Recipe Preparation =		'''Recipe Preparation '''

	== clone Hybrid Publishing Resources ==		== clone Hybrid Publishing Resources ==
Line 34:		Line 34:
	* In terminal change directory <code>cd </code> to the unzip folder		* In terminal change directory <code>cd </code> to the unzip folder

	= Start Cooking =		-------

			'''Start Cooking'''

	== 0. Folder structure ==		== 0. Folder structure ==
Line 120:		Line 122:
	== 4.1.5 make book.epub : An iterative process ==		== 4.1.5 make book.epub : An iterative process ==
	This work is in many way as cyclical process, where 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)		This work is in many way as cyclical process, where 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)



			-----

	= ICML files =		= ICML files =

Andre: /* ICML files */

2016-05-26T09:57:25Z

ICML files

← Older revision		Revision as of 09:57, 26 May 2016
Line 124:		Line 124:
	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.		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.		With ICML it is also possible to update the content and structure of the inDesign projects, by changing 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.'''		'''Note: ''malformatted links in the markdown files'' will create problems when imported into inDesign.'''

Andre: /* 4. make book.epub */

2016-05-26T09:56:17Z

4. make book.epub

← Older revision		Revision as of 09:56, 26 May 2016
Line 84:		Line 84:

	== 4.0 make book.md ==		== 4.0 make book.md ==
	~~This step is essential to the creation of the EPUB. It generates a single Markdown file <code>book.md</code> and save it it inside the <code>md/</code> folder. However, you~~ don't have to perform this step, as the makefile does it for you.		'''You don't have to perform this step, the makefile does it for you.'''

	<code>book.md</code> ~~consists of the content from all the individual Markdow files~~ inside the <code>md/</code> 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~~.		It generates a single Markdown file <code>book.md</code> and save it it inside the <code>md/</code> folder.

	'''~~Note:~~ the Markdown filenames should NOT contain spaces or dots, except for the extension''' <code>.md</code>		<code>book.md</code> consists of the content from all the individual Markdow files inside the <code>md/</code> 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'''.

			'''Markdown filenames should NOT contain spaces or dots, except for the extension''' <code>.md</code>

	~~To generate this single book.md, run: <code>make book.md</code> .~~

	== 4.1 make book.epub (EPUB) ==		== 4.1 make book.epub (EPUB) ==
	~~To obtain~~ the epub file ~~book.epub run~~: <code>make book.epub</code> ~~to start this stage.~~		Produce the epub file: <code>make book.epub</code>


	== 4.1.1 Essential files for EPUB ==		== 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~~.		To produce an EPUB a few files are needed, namely:
			* cover image <code>epub/cover.jpg</code>
			* metadata <code>epub/metadata.xml</code>
			* CSS stylesheet <code>epub/styles.epub.css</code>

	~~These 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~~		These files will strongly influence the EPUB's outcome, and consequently should be edited for each publication.
	* <code>epub/styles.~~epub.css</code> - EPUB css style-sheet '''MUST BE EDITED'''~~
	* <code>epub/cover.jpg</code> - EPUB cover '''MUST BE CHANGED'''

	== 4.1.2 Fonts (optional) for EPUB ==		== 4.1.2 Fonts (optional) for EPUB ==
	<code>lib/</code> is folder for storing custom fonts, that will be used in the EPUB		<code>lib/</code> 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 <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		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> is added to allow for the use of the Ubuntu Mono font. Also include the font on the EPUB style-sheet with <code>@font-face</code> rule

	== 4.1.3 EPUB check ==		== 4.1.3 EPUB check ==
	The health of the created EPUB can be checked with http://validator.idpf.org/		The health of the created EPUB can be checked with http://validator.idpf.org/


	== 4.1.5 make book.epub : An iterative process ==		== 4.1.5 make book.epub : An iterative process ==
	This work is in many way as ~~an iterative~~ process.		This work is in many way as cyclical process, where 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)

	~~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)


	= ICML files =		= ICML files =

Andre: /* clone Hybrid Publishing Resources */

2016-05-26T09:42:39Z

clone Hybrid Publishing Resources

← Older revision		Revision as of 09:42, 26 May 2016
Line 29:		Line 29:

	== clone Hybrid Publishing Resources ==		== clone Hybrid Publishing Resources ==
	* Download the [https://gitlab.com/DigitalPublishingToolkit/Hybrid-Publishing-Resources/tree/wdka Hybrid Publishing Resources code repository] ~~into~~ your computer.		* '''[https://gitlab.com/DigitalPublishingToolkit/Hybrid-Publishing-Resources/repository/archive.zip?ref=wdka Download the zip ]''' from [https://gitlab.com/DigitalPublishingToolkit/Hybrid-Publishing-Resources/tree/wdka Hybrid Publishing Resources code repository] to your computer.
	* Move the downloaded .zip ~~into~~ a dedicated folder.		* Move the downloaded .zip to a dedicated folder.
	* Unzip		* Unzip
	* In terminal change directory <code>cd </code> to the unzip folder		* In terminal change directory <code>cd </code> to the unzip folder


	= Start Cooking =		= Start Cooking =

Andre: /* 2.1 Images in Markdown */

2016-05-26T09:39:42Z

2.1 Images in Markdown

← Older revision		Revision as of 09:39, 26 May 2016
Line 68:		Line 68:

	== 2.1 Images in Markdown ==		== 2.1 Images in Markdown ==
	At this stage you should insert the images onto the ~~essays~~, now in markdown format.		At this stage you should insert the images onto the texts, 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 document''': <code>![My image caption](imgs/myImage.jpg)</code>		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 document''': <code>![My image caption](imgs/myImage.jpg)</code>

Andre: Created page with "= streamlining conversions = This same approach for converting between markups using Pandoc can be automated. Since computers are good at doing repetitive and boring tasks,..."

2016-05-26T09:31:46Z

Created page with "= streamlining conversions = This same approach for converting between markups using Pandoc can be automated. Since computers are good at doing repetitive and boring tasks,..."

New page

= streamlining conversions =
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''' file for inDesign
* an '''EPUB'''

And we'll also try to keep a connection between the '''source''' and its '''outcomes'''.

== Makefile ==
My proposal involves using a Makefile to automate the conversions between markups.

They are like recipe book, with instructions of how to process stuff and generate other stuff from it.

Read more about Makefiles in the context of hybrid publishing:
* blog post [http://networkcultures.org/digitalpublishing/2014/10/01/make-book/ Make Book] by Michael Murtaugh
* [http://lwn.net/Articles/589196/ Report] on the Don Marti's presentation at SCALE
* [http://www.gnu.org/software/make/ GNU Make official site ]

= Recipe Preparation =

== clone Hybrid Publishing Resources ==
* Download the [https://gitlab.com/DigitalPublishingToolkit/Hybrid-Publishing-Resources/tree/wdka Hybrid Publishing Resources code repository] into your computer.
* Move the downloaded .zip into a dedicated folder.
* Unzip
* In terminal change directory <code>cd </code> to the unzip folder

= 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.
<pre>
├── docx
├── epub
├── icml
├── md
│ └── imgs
└── scripts
</pre>

= 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 need to edit the manuscript, handed by the author, using '''paragraph styles''' in MS Word/Libre Office/Open Office

= 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 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''' <code>md/imgs/</code> Then '''place the images on the markdown document''': <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.

= 3. make icmls - 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|ICML files]] which can be imported into inDesign.

Read more on ICML files and inDesign in [[#working_with_ICML_files]] 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 <code>book.md</code> and save it it inside the <code>md/</code> folder. However, you don't have to perform this step, as the makefile does it for you.

<code>book.md</code> consists of the content from all the individual Markdow files inside the <code>md/</code> 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''' <code>.md</code>

To generate this single book.md, run: <code>make book.md</code> .

== 4.1 make book.epub (EPUB) ==
To obtain the epub file book.epub run: <code>make book.epub</code> 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.

These 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'''

== 4.1.2 Fonts (optional) for EPUB ==
<code>lib/</code> 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 <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.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)

= 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.