User:Whiteknight/New Book Guide/Print and PDF Versions

Whiteknight's Book Guide

Print Versions

A print version has a singular purpose: to be printed. A printable version is typically not intended to be read in the web browser, but instead to be printed onto actual paper. For that reason, many of the templates that are used on print versions look lousy on the web browser, but look great when printed. Wikis present duality: On the internet they are very flexible, dynamic, and easy to edit. However, without some special effort, they tend to produce books which look lousy when printed. Printable versions of the book are very valuable to ensure it can reach the largest possible audience, but require special care to minimize author effort and maximize aesthetics.

A printable version which is difficult to update and maintain will fall back from the bleeding edge of the most recent version of the book. The result is a printable version which never reflects the most recent fixes and additions, and therefore is an anchor to prevent the book from growing. Also if you create a boring and repetitive task, such as having to make all edits twice (once for the wiki and once for the printable version), authors are going to be less likely to do both and may be less likely to do either. What's needed is a way to automatically fold all changes made on the wiki into the printable version with a minimum of repetitive effort from the authors and editors. A little bit of work upfront preparing things like navigation templates, print versions, and collections can help to automate this process and keep all versions of the book aligned.

Navigation Templates

Navigation templates often use colors and HTML/CSS formatting that doesn't always translate well to a printed medium. If your book has large navigation templates, it might be worthwhile to make them "disappear" in the printed version. This can be accomplished in one of several ways:

Use class="noprint" in the template to prevent it from being printed
- Pros: Doesn't print, can be used on any page (so individual chapters can be printed without the navigation template).
- Cons: Appears on the printable version, so it can cause worry. Even though it appears on the screen, it doesnt get sent to the printer, decreasing the relationship between "what you see" and "what you get". Also, may still appear in a PDF generated using the collections extension (more testing is needed to confirm this).
Use parser functions to make the template invisible on the printable version page
- Pros: Don't appear on the printable version pages at all.
- Cons: Can be difficult to program them correctly. Templates will still appear on individual chapters, which means if you print an individual chapter you will see the templates. Templates generated in this way are also not portable between books, or even between multiple print editions in the same book.
Use Category:Exclude in print

Pros: Won't appear in PDFs or publish-on-demand books generated through the collections extension.
Cons: Will appear in normal print versions, and PDF versions generated by hand.

Use printable template substitutions
Pros: Allows templates to be formatted differently on-wiki and in generated collections.
Cons: Doesn't have any effect in normal printable versions, or hand-generated PDF versions.

In reality, no single solution above is useful in all cases, and a combination of them is typically needed. It's important to keep print versions, PDF versions, and collections in mind when creating your new book because these are the most common vectors through which readers will be exposed to your book once it is written.

Cover Pages

A cover page is certainly optional, but it adds a certain professional look to a book that is hard to beat. Besides the printable and PDF versions, the cover page might never be seen at all on Wikibooks, so authors tend to view it as "out of sight, out of mind".

Some publishers may prefer a "cover image", which will be dependent on the form factor used by the publisher. Since we only use PediaPress right now for print-on-demand publishing, and since they don't currently allow custom cover art, this point is basically moot. However, if a PDF of a book is taken to a different publisher, different rules and capabilities may apply. For printable versions and PDFs creating a cover page using HTML and wikitext is usually sufficient and easy to do once and forget about. For other applications such as publishing, different rules and requirements might be made that can't be easily done on the wiki.

Licensing

In printed versions it is of paramount importance to include a copy of the GFDL. This can be accomplished by adding this template to the beginning of the book (right after the cover page):

{{GFDL}}

And adding this to the end of the book:

= GNU Free Documentation License =
{{:GFDL}}

Failure to take these easy steps could cause large problems, not only for you as an author, but for the entire Wikibooks project. Notice that the GFDL is automatically included in a collection.

Creating a Print Version

Creating a print version can be a difficult task. However, several Wikibooks users have created automated print version creator tools. These tools frequently require either the use of custom User JavaScripts or the use of external programs (most of the external programs for the purpose are written in Perl).

If you would like to use a custom User JavaScript for the purpose, I have written a tool for the creation of print versions:

Print Version Gadget (Version 3.05)
Warning: This gadget is deprecated and is no longer maintained. Use the Visual Book Designer instead.
If you would like to create a print version for a book, type the name of the page that contains the TOC of your book here and click Load to load the page. Click Show to display a textbox where you can enter the text manually. Click Convert to convert the text to a printable version.

You must install User:Whiteknight/printversion.js to interact with this element. Installation instructions located at User:Whiteknight/Print Version Gadget

Note: You won't be able to see this tool until you install the custom javascripts. Instructions to installing the javascripts are located at User:Whiteknight/Javascripts

PDF Versions

There are three different schools of thought to the creation of a PDF version:

Direct conversion of the printable version into a PDF, typically though some sort of PDF creation software.
Translation of the text and the formatting to LaTeX, and then creation of a PDF.
The use of an automatic translator program, to convert Wiki syntax directly to a PDF, or to LaTeX and then to PDF.

The first approach relies on the MediaWiki software to convert the Wiki to HTML, and then the converter program to create the PDF. There are many free options to perform this conversion, and many professional software packages as well. It is important to remember that if you are using a "Print to PDF" converter, that you modify your print options to remove unnecessary page headers and other artifacts.

The second approach is the most time-consuming and also the most difficult to keep up to date. However, the benefit to this is that the book has available both a LaTeX version and a PDF version, which can be downloaded independently. This can be the most difficult option, especially if the authors of the book are not familiar with LaTeX formatting.

The third option is to use some sort of automatic converter program to convert the Wiki syntax into an appropriate form. The problem with this option, while it could conceptually be the easiest to use, is that no suitable converter software programs have been created for this purpose. There are programs in the works, of course, and dedicated volunteers are always working to improve these packages.

A PDF version is the easiest version for a person to download and read. PDF versions can be read offline, and unlike a web browser, PDF versions are typically WYSIWYG, which means that the formatting does not magically change when you print it. As a caveat, remember that PDFs are static files that are not amenable to easy editing. Also, if the PDF is generated by hand and not through the collections extension, it can be hard to update or reproduce.

Collections

Collections are easy to make, often by directly copying the TOC of the book and making a few minor formatting changes. Like a printable version, collections use pages on the wiki directly and are therefore kept up to date with all changes made to pages in the book. Collections can be used to create PDF versions of the book, but also for print-on-demand publishing from PediaPress. Automated tools such as my Visual Book Designer gadget can be used to create collections automatically from an outline or an existing book TOC. This feature is under active development still, so there are some bugs and limitations with it.

Because Collections stay updated with the most recent changes on the wiki (like print versions) and can be easily downloaded and distributed (like PDF versions), and because they have the added benefit of print-on-demand publishing, they are probably going to become the primary method of organizing and printing books in the future. Because the interface isn't quite as polished as I would like, and because it's not obvious enough how to get a PDF from a book to a new user, I'm not ready to say that print versions and PDF files need to be phased out yet, but it's definitely going to happen eventually.

Creating Collections

Collections can be created in two different ways:

Go to every page that you want in the collection and click the "Add wiki page" link on the left-hand side of the page. Repeat this for all pages in the book. Once you have added all the pages to the collection that you want, go to Special:Collection to save it, convert it to PDF or ODT, or purchase a Print-on-demand copy from PediaPress.
Create a wiki page using a particular syntax. This syntax is similar in some regards to how TOCs are created, but it's probably too simplistic to serve as a TOC by itself.

Luckily, my Visual Book Designer is already equipped to create Collections pages from an outline or from an existing book TOC. Load the book into the gadget (click File -> Load TOC to get an existing book), and then click File -> Save (as personal collection) or File -> Save (as community collection) to create the collection page.

Loading Collections

To load an existing collection, go to the collection page and click the "Load collection" link on the left side bar. If you already have an active collection, you will be given the option to overwrite your collection with the saved collection, or to append one to the other.