Appy

Because of the performance problems one may encounter with the pod function, yet another solution has been imagined, consisting in repeating a whole document.

From the section about statements, you know that a POD statement applies to a specific part of the document. In order to fulfill our need to repeat a whole document, a part named doc has been added, that represents it.

Let's use the same example as the one used to illustrate the pod function. Suppose you are a successful company, generating and sending a lot of invoices to its clients. From your accounting system, you need to generate one PDF per invoice, or also, sometimes, PDF files containing a bunch of invoices, ie, all invoices for a given period or client. All such PDF files can be produced using a single template, using a « do doc » statement, provided you pass the appropriate context to it.

Here is what such a template would look like.

I was so inspired when creating it. When you need to produce a single invoice from this template, define, in context variable invoices, a list containing this unique invoice.

class Invoice:
    def __init__(self, number):
        self.number = number
invoices = [Invoice('001')]

With this context, rendering the hereabove template produces this result.

When you need to produce a PDF containing a bunch of invoices, write down your most insightful invoice query, like in the following example.

class Invoice:
    def __init__(self, number):
        self.number = number
invoices = [Invoice('001'), Invoice('002'), Invoice('003')]

The result would then be this one.

Unreadable, indeed, but mentally readable, though.

The second statement in the hereabove template uses some concepts borrowed from other pages:

• the loop variable is discussed in the page named The « for » statement;
• the from clause is discussed here;
• function pageBreak is part of the default POD context and allows to insert a paragraph associated with a page break.

Must I use the pod function or the « do doc » statement ?

1. If you need to repeat a single document many times, like in the hereabove example, you should prefer using the « do doc » statement. It will be a lot more performant than using the pod function. 
2. If you have to include several different sub-documents into a main document, that may also have global parts being independent of any sub-document, then use the pod function.
3. If you are in case (1), but you need some preliminary page explaining what the next pages are all about, you can still use the « do doc » statement. Set the preliminary page in a section, and conditionnally include it with a statement like: do section if loop.invoice.first.