How to work with wiki-to-print?

Wiki-to-print is a collaboratively publishing environment in which PDFs can be written, edited and designed by multiple people simultaneously.

Wikis are great for (a-sync) collaborative writing and editing, which is why the MediaWiki software is a part of wiki-to-print. Alongside this, concepts such as transclusion are useful in allowing you to collate a publication from many differently authored pages. Simply put, transclusion is including a document into another one by hypertext reference, rather than copying it. Pages (or parts of them) can be transcluded into another wiki page, in this way:

{{:name of page to be transcluded}}

Transclusion is used in wiki-to-print to make one "unfolded" page that loads all the different pages of the PDF. Transclusion allows you to change the order of the texts quickly and add other elements such as a cover page or colophon. Furthermore, transclusion is useful for collaborative editing. Any changes that editors make to transcluded pages will automatically update wherever they are unfolded.

Wiki-to-print uses the Pdf namespace for these unfolded pages. Once you make a new wiki-to-print environment, a range of pink wiki-to-print buttons are added to the navigation bar, which add features for creating the layout.

Below is a list of the wiki-to-print buttons:

CSS!

Here you can add the CSS styling rules for your layout.

The Talk pages in the Pdf namespace are turned into CSS stylesheets for each particular wiki-to-print environment. So, once you have created a new wiki-to-print environment, an empty CSS stylesheet is made automatically.

Preview HTML

Here you can preview the HTML and CSS of your page.

This can be helpful to do when, for example, something unexpected happened in your layout and you want to figure out what is going on.

Preview PDF

Here you can preview your PDF in a new browser tab.

Your content and the page layout you specified in your CSS are rendered by the JavaScript library Paged.js to look like a PDF. If you are satisfied with this, you can export the PDF from this browser tab simply by pressing ctrl/command + p.

GOLDEN SWEATY TIPS

CSS

• Use pixels in your stylesheet, this will (hopefully) avoid some Paged.js quirks that we have been fighting with, see: Error_log#Disappearing_sentences
• Use a pad to write the CSS and work on it together; you can import the pad using "@import" and the "/export/txt" export function: @import url("https://pad.domainname.ext/mypad/export/txt");
• You can manually force pages to break by creating a class that has the property "page-break-after: always;", and add it to the wiki pages wherever needed
• We often use one div to force extra page breaks:
  and we copy/paste this when we need to add one
• The wiki adds id's to all the headers, which is super nice because it makes it possible to use Paged.js's target counters: https://pagedjs.org/documentation/-cross-references/#target-counter(); See this page for an example where this is used: https://cc.vvvvvvaria.org/wiki/Pdf:APRJA_Minor_Tech
• It depends on the layout, but often image sizes are best specified one-by-one, rather than globally. We often give exact pixel widths in the image element, for example <code>[[File:image.jpeg|thumb|480px|image caption]]</code>
• We don't try to go into micro-typography too much, it drives us crazy :) as it exponentially increases the workload
• Footnotes are rendered by the wiki with a small backlink-arrow, which is a super nice feature to keep in the PDF
• Fonts need to be hosted at the same server or domainname, to avoid cross-origin errors

exporting

• Different browsers (such as Chrome/Chromium, Firefox etc.) render PDFs differently, even if you're using the same version! For final final final versions, proof from PDFs, not from screen!
• Firefox renders images in low quality, the Paged.js developers recommend using Chrome/Chromium
• Your PDF will be saved in RGB, you can convert it to CMYK with Ghostscript. We use OSP's PDFUtils repository
• Zooming in/out in the browser may lead to suddenly disappearing lines; it's recommended to keep it 100 (percent) when working with Paged.js.
• Paged.js previews the PDF as double-page spreads, but the browser will save it as a single page document. You may also notice some slight differences in resolution and crispness of fonts between the browser and your PDF e-reader

docs

• The Paged.js documentation is pretty good: https://pagedjs.org/documentation/, you can find useful examples for using generated page numbers in toc's and other things
• The Coko Foundation's Mattermost has a dedicated Paged.js channel! You can find the makers and other users of Paged.js there, who may help you out in a pickle: https://mattermost.coko.foundation/coko/channels/pagedjs

wiki-to-print

• More than one person editing a wiki page at the same time leads to version conflicts... And one of you loses their edits :|
• It's possible to use the View HTML button to make an HTML page. It's something that changes the scope of wiki-to-"print" into wiki-publishing, which we never tried but think is exciting :)