• View
• Edit
• History
• Print

Technical Matters

 

This technical appendix documents ways of adding structure to a Wikipublisher book.

1.  Chapter sections

Wiki heading markup (one or more ! marks at the start of a line) is translated into sectioning commands. Wikipublisher is able to nest 3 levels of page heading. In a book where the trail page is a single level list of chapters, the heading levels correspond to sections, subsections and subsubsections. If the trail page is a nested list of chapters and sections, heading levels on the section pages correspond to subsections, subsubsections and paragraphs.

Within a wiki page, authors can make a cross-reference to a related section using a heading label and section reference. For example, Sec(floatingDivs) produces Floating and other divs — a reference to the heading labelled [[#floatingDivs]]. In the PDF, references become clickable links.

2.  Tabular material

Wiki table markup (one or more lines starting with ||) produces a table. Column widths are determined automatically, based on the width of the paper and the contents of individual cells. If the first row of the table uses table heading markup (cells marked as ||!heading text), Wikipublisher recognises this as a “head row” and inserts a rule between this row and the following row. If the last table row uses heading or emphasis markup (cells marked as ||''emphasis''), Wikipublisher recognises this as a “foot row” and inserts a rule between this row and the previous row. Tables with captions are automatically numbered.

By using a class attribute in the table definition row, authors can direct Wikipublisher to give a table special treatment. Supported table classes lists the recognised classes. Authors can make a cross-reference to a table using a table id and table reference. The table id is of the form id=tableID"Alternate caption text" in the table definition row and the reference is of the form Tab(tableID). The alternate caption text is used in the list of tables. In the absence of a table caption, the alternate text is also used as the table caption. By default, table cross-references include an “on page” reference. The `Tab(tableID) variant suppresses the page reference.

3.  Figures

When working with images, authors need to consider the following matters:

• use of vector or high resolution bitmap images
• placement of figure captions relative to the image
• subfigures (2 or more images forming part of the same figure)
• wrapping text around images
• images as part of marginal notes

Wikipublisher recognises links to files with the extensions png, gif and jpg as images. To use a high resolution image, an author creates a link of the form [[lo-res-image-1 -> hi-res-image-2]]. In the PDF, Wikipublisher will use image-2. In this way, an author can use a low resolution image-1 to ensure the web page loads quickly, while substituting the high resolution image-2 in the printed book. In some cases, authors may prefer to use a bitmap image for the web, but substitute a vector image in the PDF. To do this, an author creates a link of the form [[image-n.png -> image-n.pdf]]. Apart from having different extensions, the file names must be identical. If the file names are different, Wikipublisher will interpret the markup as a link to a regular PDF file.

A 16^th century printing office

In the absence of an explicit caption, Wikipublisher uses an image’s alt text as the figure caption. By default, the caption prints below the image. However, if the author applies the %rfloat% or %lfloat% class to the image, Wikipublisher interprets this as “side caption” markup and prints the caption on the outside of the image (i.e., to the right of the image on recto pages and to the left on verso pages). An author can apply side captions to all images by using the imagesize=sidecaps argument in the typeset-book directive. Sixteenth century printer illustrates a figure with a side caption.

If the author applies the same float class to two consecutive images (i.e., side-by-side floating images with no intervening text), Wikipublisher treats these as “subfigures”. Subfigure markup example illustrates markup for a 3 part subfigure, with individual image captions, plus an overall figure caption. First style and Second style refer to individual sub-figures and illustrate this.

%lfloat height=187px%Attach:sample0.png"sample 0" \
%lfloat height=187px%Attach:sample1.png"sample 1" \
%lfloat height=187px%Attach:sample2.png"sample 2" %% Suspendisse potenti

Fifteenth century alphabets

The %rframe% and %lframe% image classes by default produce the same output as the lfloat and rfloat classes. However, an author can also use these to wrap text around an image. To activate this option, an author adds wrapfloat=on to the typeset-book directive. The lframe class positions the image at the inside margin; the rframe class positions the image at the outside margin, extending across the space for marginal notes. Wrapped images work best if surrounded by running prose and the option is best used when the book is substantially complete. In particular, placing wrapped images should avoid:

• lists
• section headings
• page breaks

Finally, an author can include a captionless image as a marginal note using the {=Attach:image.ext=} markup. For example, some authors of technical manuals use small graphics to denote tips, warnings, and other repeating elements. Wikipublisher will automatically shrink wide images to fit the margin width.

If the image has an id attribute and alt text, an author can use Fig(imageID) to reference the figure. By default, this includes an “on page” reference. The `Fig(imageID) variant suppresses the page reference.

4.  Floating and other divs

By adding id=divisionID"Caption text" to the (:div:) directive, the markup block can be made to “float”. Authors can then reference the floating div using Div(divisionID) markup. Alternatively, an author can separate a div from its surrounding text without floating it, using either class=frame or class=block. The following example uses the “block” class.

An author can control the background colour of a div class=frame using the bgcolor attribute. For a div class=block, authors can use the blockcolor setting on the typeset-book directive to set the background for all divs of that class. Suitable colours include Apricot, SpringGreen and Goldenrod. The default background is a light blue.

5.  Special characters

Markup for special characters lists ways to include HTML character entities using markup.

← Shape Shifting | Book Guide | Customisation →