.. doctest docs/admin/printing.rst
.. _lino.admin.printing:

===================================
Introduction to printing
===================================

.. contents::
  :local:


.. include:: /../docs/shared/include/tested.rst

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

.. currentmodule:: lino.modlib.printing

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
:ref:`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 :class:`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
:doc:`config_dirs`).  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 :attr:`do_print
<Printable.do_print>` action of a printable object:

- Lino **generates** ("builds") the printable document on the server.
  For cached printables (see :class:`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
============ ============ ======================
<BLANKLINE>


Template engines
================

A `template engine <http://en.wikipedia.org/wiki/Template_engine_(web)>`_ 
is responsible for replacing *template commands* by their result.
The template engine determines the syntax for specifying template 
commands when designing templates.

- :doc:`appy_templates`

- :class:`PisaBuildMethod` and :class:`LatexBuildMethod` use 
  `Django's template engine
  <http://docs.djangoproject.com/en/2.2/topics/templates/>`_ whose 
  template commands look for example like 
  ``{% if instance.has_family %}yes{% else %}no{% endif %}``
  or
  ``My name is {{ instance.name }}.``.

- :class:`RtfBuildMethod` uses :term:`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.

   
Weblinks
========

.. glossary::

  Pisa
    http://www.xhtml2pdf.com/
    HTML/CSS to PDF converter written in Python.
    See also :srcref:`/docs/blog/2010/1020`
    
  odtwriter
    http://www.rexx.com/~dkuhlman/odtwriter.html
    http://www.linuxbeacon.com/doku.php?id=articles:odfwriter
  
  pyratemp
    http://www.simple-is-better.org/template/pyratemp.html