• View
• Edit
• History
• Print

Typesetting Engine

 

The audience for this page is new Wikipublisher users. To turn Web pages into print documents, we have to do several things:

1. establish a structural hierarchy of sections, subsections, sub-subsections, and so on
2. apply a document class suitable for the desired output, such as letters, articles, reports, or books
3. define audience-specific settings, such as paper size and whether to print single- or double-sided
4. create navigation aids such as a table of contents and page cross-references
5. re-purpose Web constructs such as links, image alt text, and tool tips

To see what Wikipublisher does, readers may wish to typeset this page, print it on a duplex printer from a PDF viewer, and study it alongside the Web page.

     

PDF settings (show)

• toc: on (generate a table of contents for an article or book chapter)
• autonumber: 2 (depth of numbered sections)

Establish a structural hierarchy

Lists

The basic building blocks are lists and headings. To assemble several pages into a single document, make a list of page names (i.e. a Wiki Trail):

• Section A Page
  • Subsection 1 Page
  • Subsection 2 Page
• Section B Page

… and so on. The hierarchy of the list determines the hierarchy of the document. The engine automatically detects any gaps in the hierarchy and inserts place-holders. For example, if the list starts with a subsection (**), it inserts a dummy section. The author needs to fix these by hand. You can also mix text and page names in the list:

• Section A heading text
  • Subsection 1 Page
  • Subsection 2 Page
• Section B heading text

Headings

Within each page, the engine slots each heading into the overall hierarchy. For example, the first heading on Section A Page becomes a subsection, the first heading on Subsection 1 Page becomes a sub-subsection. It treats heading depths as relative elements. That is, authors can use any combination of heading levels and it will work out where these fit in the hierarchy. The first heading on Section A Page might be <h2> while the first heading on Section B Page might be <h3>; both headings become subsections. Lower level headings become lower level hierarchy elements, up to 3 levels of heading on a page.

If you use headings to break up your list of page names, these are treated as section markers and first level list items become subsections. When expanding and typesetting such a trail page, it builds one level of heading into the hierarchy only.

Apply a document class

To tell the engine which document class to use when typesetting a page, we use a typeset directive. These are listed in typesetting directives.

The first 3 directives expand page trails into their constituent parts; the last 2 apply to single pages. The (:typeset-trail:) directive uses the same “article” document class as (:typeset-page:). For more information on the special letter markup, see Write a Letter.

Define audience-specific settings

Wikipublisher installs a number of template pages in the Site group, which control the default layout of printed pages and page collections. For example, the Print Template defines metadata values to control the layout for articles. In addition, authors and readers can:

• create template pages in the current group to over-ride the site-wide metadata settings
• over-ride the template settings with options on the typeset directive; for example, this page’s directive includes “toc=on” to generate a table of contents
• press an options button to over-ride the defaults when requesting a print version

See also Publish Template, Book Template, Include Template, Letter Template. For a list of available typesetting options, see Wikipublisher Options.

Create navigation aids

The engine automatically inserts standard printed page layout elements, such as running headers and footers. For duplex printing, these are mirrored on odd and even pages. Internal links from one part of the document to another gain page numbers (page cross-references). Figures are automatically numbered; tables are numbered only if the table has a caption. The engine uses the figure or table number in any references; for example, typesetting directives.

Authors can control whether headings are numbered, and the depth of numbering in the hierarchy, using the autonumber option setting. A heading always stays on the same page as the paragraph following. Authors can request a table of contents, a list of figures, and a list of tables. The engine also supports indexes, but this feature is not yet implemented.

Re-purpose Web constructs

Authors generally don’t have to think about this. If you focus on the structure and meaning of the content, it will just work. The print presentation of all markup is configurable; if necessary, your site administrator can change the default settings to address site-specific requirements. Pages are laid out for optimal readability and comprehension — they are also rather beautiful, although this is a secondary consideration!

When printed, the PDF of this document should be centred on the paper, with equal left and right margins. The bottom margin is 3 mm deeper than the top. Hold a page up to the light; the recto and verso text should line up exactly. On A4 paper, the line length should be 125 mm and the distance between top and bottom rules 240 mm. In some PDF viewers, the text may be offset horizontally or vertically, and the text area may be shrunk. If so, you may need to adjust the viewer’s print settings. The fix depends on the viewer; for example in Acrobat Reader, make sure page scaling is set to “None”.