Introduction to printing

A tested document

This is a tested document. The following instructions are used for initialization:

>>> from lino import startup
>>> startup('lino_book.projects.min9.settings.doctests')
>>> from lino.api.shell import *
>>> from lino.api.doctest import *

In a web application, printing means to produce a printable document and then show it in the client's browser.

A printable document is a file generated by Lino and delivered to the end-user who will view it in their browser (or some external application if their browser is configured accordingly) and eventually print them out on their printer.

Printable documents are typically either in .pdf format (for read-only files) or one of .odt, .doc or .rtf (for editable files).

Sites which offer editable printables to their users might also use DavLink so that the users don't need to save these files on their client machines.

End-users see a printable document by invoking the Print button on a printable database object (see also the Printable model mixin).

Lino applications can decide to use printable documents in other ways than showing them to your browser, e.g. attach them to an email, or send them directly from the application server to a printer in a local area network.

Lino comes with a selection of ready-to-use mechanisms for generating printable documents using different types of templates.

A print template is a file that serves as master document for building a printable document. Lino processes the template using a given build method, inserting data from the database and producing the printable document as a new file stored in a cache directory.

Print templates are part of your site configuration (see Introduction to config directories). The easiest way to edit and manage your templates is to make your server's local configuration directory accessible to your desktop computer and to use some file manager of your choice.

The print action

Here is what happens when a user invokes the do_print action of a printable object:

  • Lino generates ("builds") the printable document on the server. For cached printables (see CachedPrintable), Lino may skip this step if that document had been generated earlier.

  • Lino delivers the document to the user.

Build methods

Lino comes with a series of "build methods". You can imagine a build method as a kind of "driver" who generates ("builds") printable documents from a template.

>>> rt.show(printing.BuildMethods)
============ ============ ======================
 value        name         text
------------ ------------ ----------------------
 appydoc      appydoc      AppyDocBuildMethod
 appyodt      appyodt      AppyOdtBuildMethod
 appypdf      appypdf      AppyPdfBuildMethod
 appyrtf      appyrtf      AppyRtfBuildMethod
 latex        latex        LatexBuildMethod
 rtf          rtf          RtfBuildMethod
 weasy2html   weasy2html   WeasyHtmlBuildMethod
 weasy2pdf    weasy2pdf    WeasyPdfBuildMethod
 xml          xml          XmlBuildMethod
============ ============ ======================

Template engines

A template engine is responsible for replacing template commands by their result. The template engine determines the syntax for specifying template commands when designing templates.

  • Using Appy POD templates

  • PisaBuildMethod and LatexBuildMethod use Django's template engine whose template commands look for example like {% if instance.has_family %}yes{% else %}no{% endif %} or My name is {{ instance.name }}..

  • RtfBuildMethod uses pyratemp as template engine whose template commands looks like @!instance.name!@. We cannot use Django's template engine because both use curly braces as command delimiters.

    This build method has a flaw: I did not find a way to "protect" the template commands in your RTF files from being formatted by Word.

Markup versus WYSIWYG

There are two fundamentally different categories of templates: WYSIWYG (.odt, .rtf) or Markup (.html, .tex).

Template collections that use some markup language are usually less redundant because you can design your collection intelligently by using template inheritance.

On the other hand, maintaining a collection of markup templates requires a relatively skilled person because the maintainer must know two "languages": the template engine's syntax and the markup syntax.

WYSIWYG templates (LibreOffice or Microsoft Word) increase the probability that an end-user is able to maintain the template collection because there's only on language to learn (the template engine's syntax)

Post-processing

Some print methods need post-processing: the result of parsing must be run through another software in order to turn into a usable format. Post-processing creates dependencies to other software and has of course influence on runtime performance.