How to document a summer academy - Revision history

JBG at 08:05, 17 December 2015

2015-12-17T08:05:00Z

← Older revision		Revision as of 10:05, 17 December 2015
Line 192:		Line 192:

	'''Step 3''' Type into your terminal the following Pandoc command: <br>		'''Step 3''' Type into your terminal the following Pandoc command: <br>
	pandoc --template handd-book.template handd-book.wiki -o handd-book.pdf --toc -M fontsize=12pt -M author='Hackers \& Designers' -M title='About Bugs, Bots and Bytes' --latex-engine xelatex -M mainfont='Helvetica' -M papersize='a5paper' -V links-as-notes		pandoc --template handd-book.template handd-book.wiki -o handd-book.pdf --toc \
			-M fontsize=12pt -M author='Hackers \& Designers' -M title='About Bugs, Bots and Bytes' \
			--latex-engine xelatex -M mainfont='Helvetica' -M papersize='a5paper' -V links-as-notes

	Missing latex dependencies can be installed with:		Missing latex dependencies can be installed with:

JBG at 08:04, 17 December 2015

2015-12-17T08:04:07Z

Show changes

Hd-onions: /* Publishing in print */

2015-12-16T13:14:10Z

Publishing in print

← Older revision		Revision as of 15:14, 16 December 2015
Line 159:		Line 159:

	'''From CSS and HTML to print with Prince.'''		'''From CSS and HTML to print with Prince.'''

	After you prepared your HTML and CSS for the website, and the layout for the book is set with CSS, Prince or another API can be used for translating the HTML language to a PDF.		After you prepared your HTML and CSS for the website, and the layout for the book is set with CSS, Prince or another API can be used for translating the HTML language to a PDF.

	You can download a free trial of Prince and install it with Terminal. The Terminal runs Prince and uses it to translate the website into a pdf. Prince is not an open source program.		You can download a free trial of Prince and install it with Terminal. The Terminal runs Prince and uses it to translate the website into a pdf. Prince is not an open source program.


	'''Wiki to print'''		'''Wiki to print'''

Hd-onions at 13:11, 16 December 2015

2015-12-16T13:11:23Z

← Older revision		Revision as of 15:11, 16 December 2015
Line 228:		Line 228:


	[[File:workflow~~-documentation~~.jpg\|500px\|Diagram: How this publication came into being]]		[[File:documentation-workflow.jpg\|500px\|Diagram: How this publication came into being]]

	===Dos and Don'ts===		===Dos and Don'ts===

Hd-onions: /* Publishing in print */

2015-12-16T12:53:03Z

Publishing in print

← Older revision		Revision as of 14:53, 16 December 2015
Line 161:		Line 161:
	After you prepared your HTML and CSS for the website, and the layout for the book is set with CSS, Prince or another API can be used for translating the HTML language to a PDF.		After you prepared your HTML and CSS for the website, and the layout for the book is set with CSS, Prince or another API can be used for translating the HTML language to a PDF.

	~~'''Prince'''~~		You can download a free trial of Prince and install it with Terminal. The Terminal runs Prince and uses it to translate the website into a pdf. Prince is not an open source program.

	You can download a free trial of ~~the ‘Prince’ application~~ and install it with ~~‘Terminal’~~. The Terminal runs ~~‘Prince’~~ and uses it to translate the website into a pdf. Prince is not an open source program.

Hd-onions: /* Publishing in print */

2015-12-16T12:51:52Z

Publishing in print

← Older revision		Revision as of 14:51, 16 December 2015
Line 141:		Line 141:
	===Publishing in print===		===Publishing in print===
	'''Web to print: HTML to print with CSS and print preview'''		'''Web to print: HTML to print with CSS and print preview'''

	One way to publish a print publication from an online environment is printing a webpage by using CSS. A user can just click ‘Print Page’, a pop-up print preview will appear and the custom CSS will translate the webpage and media to a printable print publication divided in pages.		One way to publish a print publication from an online environment is printing a webpage by using CSS. A user can just click ‘Print Page’, a pop-up print preview will appear and the custom CSS will translate the webpage and media to a printable print publication divided in pages.
	The design is also made with code/text, which means that you can use text editors such as EtherPad to collaborate on content with several people at the same time. The negative side on using this set-up is that you if you decide to not use a single page website you will have to print each article separate and later bind it into a book. This way no table of contents will be created or there will be no option to apply different lay outing for indexes, special chapters, or glossaries.		The design is also made with code/text, which means that you can use text editors such as EtherPad to collaborate on content with several people at the same time. The negative side on using this set-up is that you if you decide to not use a single page website you will have to print each article separate and later bind it into a book. This way no table of contents will be created or there will be no option to apply different lay outing for indexes, special chapters, or glossaries.

	'''Differences between CSS for the web and CSS for print '''		'''Differences between CSS for the web and CSS for print '''

	You also have to consider the differences between a webpage and a printed publication. What will happen with image galleries, sliders, menu’s and the like? If your webpage has a slideshow with ten images at the top, that’s not going to translate well to paper. The most basic level of interaction on the web is a link. This too becomes problematic. On your computer, you can simply click a link to see where it goes, on paper this functionality is lost so you need a good way to take all those inline links and show the reader where they lead.		You also have to consider the differences between a webpage and a printed publication. What will happen with image galleries, sliders, menu’s and the like? If your webpage has a slideshow with ten images at the top, that’s not going to translate well to paper. The most basic level of interaction on the web is a link. This too becomes problematic. On your computer, you can simply click a link to see where it goes, on paper this functionality is lost so you need a good way to take all those inline links and show the reader where they lead.

Line 151:		Line 153:

	'''Print preview'''		'''Print preview'''

	If you want to print your website a print preview window appears. The back-end code in the browser needs to do heavy lifting to support all the requests coming from the front-end.		If you want to print your website a print preview window appears. The back-end code in the browser needs to do heavy lifting to support all the requests coming from the front-end.

Line 159:		Line 162:

	'''Prince'''		'''Prince'''

	You can download a free trial of the ‘Prince’ application and install it with ‘Terminal’. The Terminal runs ‘Prince’ and uses it to translate the website into a pdf. Prince is not an open source program.		You can download a free trial of the ‘Prince’ application and install it with ‘Terminal’. The Terminal runs ‘Prince’ and uses it to translate the website into a pdf. Prince is not an open source program.

Line 165:		Line 169:

	'''Collection and the Offline Content Generator'''		'''Collection and the Offline Content Generator'''

	After doing some research we found out that WikiMedia had already developed an open source plug-in, called Collections created by The Wiki Publisher Project. The extension makes it possible to select pages to create pdf’s or compile books. The user can create different chapters and arrange articles. Then the compiled pages are send to the OCG (Offline Content Generator). The OCG invokes a /Bundler to spider the articles and fetch all images, stylesheets, etc required to render them. One of several /Backends are then invoked to convert the bundle into a PDF, ZIM file, or other appropriate output format. This conversion to a pdf happens on wiki servers. We wanted to use this open source plug-in and adjust the code to fit our needs. (eg layout, page size, content table,…)		After doing some research we found out that WikiMedia had already developed an open source plug-in, called Collections created by The Wiki Publisher Project. The extension makes it possible to select pages to create pdf’s or compile books. The user can create different chapters and arrange articles. Then the compiled pages are send to the OCG (Offline Content Generator). The OCG invokes a /Bundler to spider the articles and fetch all images, stylesheets, etc required to render them. One of several /Backends are then invoked to convert the bundle into a PDF, ZIM file, or other appropriate output format. This conversion to a pdf happens on wiki servers. We wanted to use this open source plug-in and adjust the code to fit our needs. (eg layout, page size, content table,…)

Line 170:		Line 175:

	'''Offline content generator the package:'''		'''Offline content generator the package:'''

	* Service		* Service
	* Bundler: This tool grabs all the dependencies for a given set of articles and creates a directory or zip file.		* Bundler: This tool grabs all the dependencies for a given set of articles and creates a directory or zip file.
	* Latexer		* Latexer

	'''Latex''' is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation. LaTeX is available as free language.		'''Latex'''

			Latex is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation. LaTeX is available as free language.
	* Several extensions are available for LaTex called: ‘packages’ or ‘styles’ (better image placement, implementation of mathematic formula,...)		* Several extensions are available for LaTex called: ‘packages’ or ‘styles’ (better image placement, implementation of mathematic formula,...)
	* Create a text file in LaTex mark-up, which LaTex reads to produce the final document.		* Create a text file in LaTex mark-up, which LaTex reads to produce the final document.
Line 185:		Line 193:

	'''Bookshelf'''		'''Bookshelf'''

	This WikiMedia plug-in allows previous compiled books to be added to the bookshelf. The bookshelves can be used to print previously published editions of a publication by other users. This way we can compile one 'official' documentation book and let other people print it.		This WikiMedia plug-in allows previous compiled books to be added to the bookshelf. The bookshelves can be used to print previously published editions of a publication by other users. This way we can compile one 'official' documentation book and let other people print it.

	'''Pandoc'''		'''Pandoc'''

	This program converts files from one mark-up language to another. In this case, we used it convert the WikiMedia mark-up to HTML for our website, and to LaTex mark-up for the print publication.		This program converts files from one mark-up language to another. In this case, we used it convert the WikiMedia mark-up to HTML for our website, and to LaTex mark-up for the print publication.

	'''Mark-up'''		'''Mark-up'''

	A mark-up language is a notation used to annotate a document’s content to give information regarding the structure of the text or instructions for how it is to be displayed.		A mark-up language is a notation used to annotate a document’s content to give information regarding the structure of the text or instructions for how it is to be displayed.

Hd-onions: /* Publishing in print */

2015-12-16T12:50:18Z

Publishing in print

← Older revision		Revision as of 14:50, 16 December 2015
Line 174:		Line 174:
	* Latexer		* Latexer

	'''Latex'''		'''Latex''' is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation. LaTeX is available as free language.
	~~LaTex~~ is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation. LaTeX is available as free language.
	* Several extensions are available for LaTex called: ‘packages’ or ‘styles’ (better image placement, implementation of mathematic formula,...)		* Several extensions are available for LaTex called: ‘packages’ or ‘styles’ (better image placement, implementation of mathematic formula,...)
	* Create a text file in LaTex mark-up, which LaTex reads to produce the final document.		* Create a text file in LaTex mark-up, which LaTex reads to produce the final document.

Hd-onions: /* Publishing in print */

2015-12-16T12:48:40Z

Publishing in print

← Older revision		Revision as of 14:48, 16 December 2015
Line 141:		Line 141:
	===Publishing in print===		===Publishing in print===
	'''Web to print: HTML to print with CSS and print preview'''		'''Web to print: HTML to print with CSS and print preview'''

	One way to publish a print publication from an online environment is printing a webpage by using CSS. A user can just click ‘Print Page’, a pop-up print preview will appear and the custom CSS will translate the webpage and media to a printable print publication divided in pages.		One way to publish a print publication from an online environment is printing a webpage by using CSS. A user can just click ‘Print Page’, a pop-up print preview will appear and the custom CSS will translate the webpage and media to a printable print publication divided in pages.
	The design is also made with code/text, which means that you can use text editors such as EtherPad to collaborate on content with several people at the same time. The negative side on using this set-up is that you if you decide to not use a single page website you will have to print each article separate and later bind it into a book. This way no table of contents will be created or there will be no option to apply different lay outing for indexes, special chapters, or glossaries.		The design is also made with code/text, which means that you can use text editors such as EtherPad to collaborate on content with several people at the same time. The negative side on using this set-up is that you if you decide to not use a single page website you will have to print each article separate and later bind it into a book. This way no table of contents will be created or there will be no option to apply different lay outing for indexes, special chapters, or glossaries.

	'''Differences between CSS for the web and CSS for print '''		'''Differences between CSS for the web and CSS for print '''

	You also have to consider the differences between a webpage and a printed publication. What will happen with image galleries, sliders, menu’s and the like? If your webpage has a slideshow with ten images at the top, that’s not going to translate well to paper. The most basic level of interaction on the web is a link. This too becomes problematic. On your computer, you can simply click a link to see where it goes, on paper this functionality is lost so you need a good way to take all those inline links and show the reader where they lead.		You also have to consider the differences between a webpage and a printed publication. What will happen with image galleries, sliders, menu’s and the like? If your webpage has a slideshow with ten images at the top, that’s not going to translate well to paper. The most basic level of interaction on the web is a link. This too becomes problematic. On your computer, you can simply click a link to see where it goes, on paper this functionality is lost so you need a good way to take all those inline links and show the reader where they lead.

Line 153:		Line 151:

	'''Print preview'''		'''Print preview'''

	If you want to print your website a print preview window appears. The back-end code in the browser needs to do heavy lifting to support all the requests coming from the front-end.		If you want to print your website a print preview window appears. The back-end code in the browser needs to do heavy lifting to support all the requests coming from the front-end.

	The majority of the work in the back-end involves restructuring the HTML to support preview. Once all the platforms are brought in line, the printing pipeline needs to be broken up into two pieces: PDF generation and printing. The user has to select a printer before a print render is generated for a preview. When printing, the renderer generates printing metadata one page at a time, so it can generate them while the PrintJobWorker in the browser process sends them to the printer at the same time.		The majority of the work in the back-end involves restructuring the HTML to support preview. Once all the platforms are brought in line, the printing pipeline needs to be broken up into two pieces: PDF generation and printing. The user has to select a printer before a print render is generated for a preview. When printing, the renderer generates printing metadata one page at a time, so it can generate them while the PrintJobWorker in the browser process sends them to the printer at the same time.


	'''From CSS and HTML to print with Prince.'''		'''From CSS and HTML to print with Prince.'''

	After you prepared your HTML and CSS for the website, and the layout for the book is set with CSS, Prince or another API can be used for translating the HTML language to a PDF.		After you prepared your HTML and CSS for the website, and the layout for the book is set with CSS, Prince or another API can be used for translating the HTML language to a PDF.

	'''Prince'''		'''Prince'''

	You can download a free trial of the ‘Prince’ application and install it with ‘Terminal’. The Terminal runs ‘Prince’ and uses it to translate the website into a pdf. Prince is not an open source program.		You can download a free trial of the ‘Prince’ application and install it with ‘Terminal’. The Terminal runs ‘Prince’ and uses it to translate the website into a pdf. Prince is not an open source program.

Line 171:		Line 165:

	'''Collection and the Offline Content Generator'''		'''Collection and the Offline Content Generator'''

	After doing some research we found out that WikiMedia had already developed an open source plug-in, called Collections created by The Wiki Publisher Project. The extension makes it possible to select pages to create pdf’s or compile books. The user can create different chapters and arrange articles. Then the compiled pages are send to the OCG (Offline Content Generator). The OCG invokes a /Bundler to spider the articles and fetch all images, stylesheets, etc required to render them. One of several /Backends are then invoked to convert the bundle into a PDF, ZIM file, or other appropriate output format. This conversion to a pdf happens on wiki servers. We wanted to use this open source plug-in and adjust the code to fit our needs. (eg layout, page size, content table,…)		After doing some research we found out that WikiMedia had already developed an open source plug-in, called Collections created by The Wiki Publisher Project. The extension makes it possible to select pages to create pdf’s or compile books. The user can create different chapters and arrange articles. Then the compiled pages are send to the OCG (Offline Content Generator). The OCG invokes a /Bundler to spider the articles and fetch all images, stylesheets, etc required to render them. One of several /Backends are then invoked to convert the bundle into a PDF, ZIM file, or other appropriate output format. This conversion to a pdf happens on wiki servers. We wanted to use this open source plug-in and adjust the code to fit our needs. (eg layout, page size, content table,…)

Line 177:		Line 170:

	'''Offline content generator the package:'''		'''Offline content generator the package:'''

	* Service		* Service
	* Bundler: This tool grabs all the dependencies for a given set of articles and creates a directory or zip file.		* Bundler: This tool grabs all the dependencies for a given set of articles and creates a directory or zip file.
Line 183:		Line 175:

	'''Latex'''		'''Latex'''

	LaTex is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation. LaTeX is available as free language.		LaTex is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation. LaTeX is available as free language.
	* Several extensions are available for LaTex called: ‘packages’ or ‘styles’ (better image placement, implementation of mathematic formula,...)		* Several extensions are available for LaTex called: ‘packages’ or ‘styles’ (better image placement, implementation of mathematic formula,...)
Line 195:		Line 186:

	'''Bookshelf'''		'''Bookshelf'''

	This WikiMedia plug-in allows previous compiled books to be added to the bookshelf. The bookshelves can be used to print previously published editions of a publication by other users. This way we can compile one 'official' documentation book and let other people print it.		This WikiMedia plug-in allows previous compiled books to be added to the bookshelf. The bookshelves can be used to print previously published editions of a publication by other users. This way we can compile one 'official' documentation book and let other people print it.

	'''Pandoc'''		'''Pandoc'''

	This program converts files from one mark-up language to another. In this case, we used it convert the WikiMedia mark-up to HTML for our website, and to LaTex mark-up for the print publication.		This program converts files from one mark-up language to another. In this case, we used it convert the WikiMedia mark-up to HTML for our website, and to LaTex mark-up for the print publication.

	'''Mark-up'''		'''Mark-up'''

	A mark-up language is a notation used to annotate a document’s content to give information regarding the structure of the text or instructions for how it is to be displayed.		A mark-up language is a notation used to annotate a document’s content to give information regarding the structure of the text or instructions for how it is to be displayed.

Hd-onions: /* Publishing online */

2015-12-16T12:47:43Z

Publishing online

← Older revision		Revision as of 14:47, 16 December 2015
Line 125:		Line 125:

	The wiki content is published on the Hackers & Designers website in real-time. Meaning every time the website is loaded or pages are requested the web browser queries the MediaWiki back-end using the MediaWiki provided API, along with installed wiki semantic extensions and their APIs, through a Javascript client-side web application (AngularJS).		The wiki content is published on the Hackers & Designers website in real-time. Meaning every time the website is loaded or pages are requested the web browser queries the MediaWiki back-end using the MediaWiki provided API, along with installed wiki semantic extensions and their APIs, through a Javascript client-side web application (AngularJS).


	'''Example API Requests'''		'''Example API Requests'''
Line 138:		Line 137:
	curl 'http://wiki.hackersanddesigners.nl/mediawiki/api.php?action=query&titles=File:Chicken-and-Potato-Soup.png&prop=imageinfo&&iiprop=url&format=json'		curl 'http://wiki.hackersanddesigners.nl/mediawiki/api.php?action=query&titles=File:Chicken-and-Potato-Soup.png&prop=imageinfo&&iiprop=url&format=json'

			'''The code is available on [https://github.com/hackersanddesigners/handd-web github.com/hackersanddesigners/handd-web].'''
	The code is available on [https://github.com/hackersanddesigners/handd-web github.com/hackersanddesigners/handd-web].

	===Publishing in print===		===Publishing in print===

Hd-onions: /* Editorial considerations */

2015-12-16T12:42:57Z

Editorial considerations

← Older revision		Revision as of 14:42, 16 December 2015
Line 68:		Line 68:

	'''Current set-up'''		'''Current set-up'''

	{\| class="wikitable" border="2"		{\| class="wikitable" border="2"
	\|-		\|-
Line 84:		Line 83:

	'''Editorial course'''		'''Editorial course'''

	* collecting & sorting		* collecting & sorting
	* prepping (i.e. retouching or re-taking foto's)		* prepping (i.e. retouching or re-taking foto's)
Line 95:		Line 93:

	'''Translation wiki to website'''		'''Translation wiki to website'''

	{\| class="wikitable" border="1"		{\| class="wikitable" border="1"
	\|-		\|-
Line 111:		Line 108:

	'''Translation wiki to print'''		'''Translation wiki to print'''

	{\| class="wikitable" border="1"		{\| class="wikitable" border="1"
	\|-		\|-