From the WikiPublisher

Wikipublisher: FAQ

Wikipublisher offers authors and administrators a range of features for controlling content and appearance of printed output. For additional examples, see Tip of the Week.

Techniques for authors

QHow do I enter text that appears on screen but is hidden in print?

There are 2 markup extensions to support this

Normal text is printed

=>Right-aligned and hidden for printing

=<Left-aligned and hidden for printing

Normal text is printed

QWhy do characters like “curly quotes” show as black diamonds?

Wikipublisher recognises "straight quotes" and automatically smartens then into the correct HTML “curly quote” character entities. However, if you copy and paste text from another program, such as a word processor, and it contains special characters, these may not be displayed correctly in the PDF. If you need to use Unicode characters, ask your administrator to set the template character encoding variable, $XMLEncodingFmt, to ‘utf-8’.

QHow do I insert a page break into printed output?

Page breaks are based on structure. For composing a single wiki page, the reader has the option of specifying that headings of a particular level always start on a new page. By default, single pages are typeset with no breaks. For composing page collections, the reader has the option of specifying that each wiki page starts a new page. By default, search and calendar page collections are typeset with no breaks. Trail pages are typeset with each major section (first level list items) starting a new page.

QHow can I omit one or more trail list items from the typeset output?

The composer takes advantage of the “invisible stop” markup extension (backtick-fullstop). In normal page display, this is simply removed. However, a number of services, including typeset and page table of contents, ignore any text after an invisible stop. If an author starts a list item with an invisible stop, the composer ignores it. As far as PmWiki is concerned, such items are not on the trail. For example:

`.* a list item with an invisible stop at the beginning
  • a list item with an invisible stop at the beginning

QWhy are there a lot of blank pages in the output and how do I prevent these?

The composer is configured to typeset page collections for double-sided printing. This means major headings start on odd numbered (right-hand) pages. If the previous content page is also an odd numbered page, the typesetting engine inserts a blank page automatically. A reader can over-ride this by selecting duplex off on the options form. A writer can put (:typeset duplex=off:) on a trail page. An administrator can configure the Site Templates. The ideal solution is to use a printer that supports duplex printing.

QHow do I keep text and floating images together?

The composer “floats” images to the top of the next page if they don’t fit and normally the text following the image will flow back above it. This can sometimes separate an image from its associated text. If a writer ends the paragraph immediately following an image with a line break ([[<<]]), Wikipublisher will keep the image and paragraph together. This is particularly useful when used in combination with %lfloat% or %rfloat% style markup. Remember to use image alt text on all images — these are used either as captions (if none is provided) or as the entry in the generated list of figures.

QHow do I substitute a hi-res image for a lo-res one?

Often we use a low resolution image on the web so that it loads more quickly, but in print we want to use a higher resolution one so that it looks better on paper. if you write [[lo.res.img -> hi.res.img]], Wikipublisher uses the hi.res.img. On the other hand, if you write [[hi.res.img | lo.res.img]], Wikipublisher uses the lo.res.img. This behaviour is controlled through the $SubstituteHiResImg array.

QHow do I make a table longer than one page?

The default handling of Simple Tables that don’t fit at the current location is to “float” them to the top of the next page. However, if the table is more than one page long, the content will overflow into the page footer. The solution is to add ||class=long to the table definition. This does the following:

  1. the table no longer “floats”
  2. if the first row is all headings (||!Head 1 ||!Head 2 ||!Head 3 || for example), this becomes a running table header
  3. at the bottom of each page there is a Continued on next page table footer

Advanced tables will automatically split across pages, on a row boundary.

QHow do I reference a table or figure number?

If a table or figure has a caption, Wikipublisher automatically gives it a number. An author often wishes to write “As figure 3 shows …” without having to know what number to use. The solution is to use an id attribute.

For tables:

  1. add id=uniqueID"summary text" to the table attributes (the ||name=value … line)
  2. the table must have a caption (||!caption text!|| markup)
  3. make a reference to the table with TAB(uniqueID) markup
  4. the TAB markup turns into a link to the table; the pdf adds the generated table number

For figures:

  1. add %block id=uniqueID%path.to.image"alt text" to the image line (if you use a block stlye such as center, lfloat or rfloat, omit the “block”)
  2. the figure must have either alt text or a caption (preferably both)
  3. make a reference to the figure with FIG(uniqueID) markup
  4. the FIG markup turns into a link to the figure; the pdf adds the generated figure number

Techniques for administrators

QWill I be able to install the wikipublisher server locally?

The server-side composition software has a number of external dependencies: LATEX, ImageMagick [1], and an xslt processor. Installing the Wikipublisher PmWiki script library is simple; installing the server-side software is less so. Now the beta version is more stable and approaching release 1.0, it is available to interested parties, under an open source licence.

QWikipublisher overrides my chosen skin. What has happened?

Wikipublisher sets a default skin — a version of the standard PmWiki skin modified to support the full set of Wikipublisher options. It is probably best to test a new Wikipublisher install using this skin. Once everything is working correctly, an administrator can restore the preferred skin by setting $Skin = ‘yourskin’; in the local/config.php file after the line that includes the Wikipublisher extensions. If the skin you expect doesn’t load, it is probably because config.php is setting the skin before it loads the Wikipublisher library.

The second possible problem is that “instead of seeing my logo graphic on every page, I see the text of the path of the logo graphic”. This is because the latexpmwiki template supports both text and graphic logos. To fix the problem, wrap <img src=‘ … ‘ /> around the logo path defined in local/config.php, or use a text logo.

QMy wiki requires a username and password to access. What should I do?

Several sites are using the userauth2 [2] recipe with silent IP permissions granting. It is said to work like a charm. Pages protected by passwords just work, with no special action required.

QHow can we remove the document footer from the pdf?

The latexprint and latexpublish skins insert some standard text at the end of the document, including the url of the page, the last modified (single pages) or publication (collections) date, and the text of Site.Page Print Footer (single pages) or Site.Print Footer (collections). These work like any other PmWiki Skins, except that they use wikibook print XML instead of HTML. The document footer text is wrapped in the <colophon> tag. Suppose you create new templates called mylatexprint and mylatexpublish, remove the colophon, and rename the latexprint.php and latexpublish.php scripts to match the skin names. Now we have to tell PmWiki to use mylatexprint (single pages) or mylatexpublish (collections). The wikipublisher script sets $ActionSkin[$action] to ‘latex’.$action. So we have to add the following to local/config.php after the line that loads the wikipublisher library:

   if ($format==‘pdf’) $ActionSkin[$action] = ‘my’.$ActionSkin[$action];

QI press Typeset and a pdf comes back. How is that done?

The PmWiki engine takes wiki markup and normally produces xhtml output, suitable for viewing through a web browser. The Wikipublisher library gives PmWiki an alternate set of markup translation rules, which cause it to produce output to the print-oriented Wikibook DTD. The xml is then passed through an xslt processor to transform it into LATEX [3] markup. Pdflatex composes this into a pdf file.

QDoes the wikipublisher server keep copies of my data?

No. Any temporary files are purged at the end of each typesetting request. Wikipublisher does not keep the email addresses of those who ask for pdf files to be emailed. The server keeps the standard activity log files. Administrators responsible for sensitive data may choose to run their own version of the pdf server software.

QCan I use wikipublisher with other web content management systems apart from PmWiki?

Certainly. The typesetting engine composes print-oriented xml into a pdf file. Any content management system able to be taught how to output print xml instead of xhtml can be used. PmWiki happens to provide a particularly easy to use way of creating print xml from wiki markup.

User Guide

Copyright © 2005–2017 the Wikipublisher wiki and its authors

Links

  1. www.imagemagick.org
  2. www.pmwiki.org/wiki/Cookbook/UserAuth2
  3. www.tug.org

Retrieved from http://www.wikipublisher.org/wiki/Wikipublisher/FAQ

Page last modified on 21 February 2008 at 08:39 PM