Debian Codegraph @

podofo/tools/podofoimpose/README.html

raw
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml">
4
5 <head>
6 <title>PodofoImpose - some words</title>
7 <meta name="AUTHOR" content="Pierre Marchand"/>
8 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
9 <style type="text/css">
10 body{
11 width:360pt;
12 margin:auto;
13 font-family:sans-serif;
14 font-size:11.2pt;
15 }
16 .section{
17 /* background-color:#ddd; */
18 border-left:1pt solid #333;
19 padding-left:12pt;
20
21 }
22 .code-abs{
23 font-family:mono;
24 font-weight:bold;
25 font-size:9pt;
26 background-color:#eee;
27 color:#222;
28 }
29 .command{
30 font-family:monospace;
31 font-size:9pt;
32 background-color:#222;
33 color:#eee;
34 padding:6pt;
35 }
36 .file{
37 border:1pt dotted black;
38 width:90%;
39 margin:12pt auto;
40 }
41 .file .name{
42 text-align:right;
43 font-family:monospace;
44 font-weight:bold;
45 font-size:8pt;
46 background-color:#eee;
47 }
48 .file .content{
49 margin:0;
50 padding:0;
51 border:0;
52 white-space:pre;
53 }
54 </style>
55 </head>
56 <body>
57 <h2>PodofoImpose</h2>
58 <div id="intro">PodofoImpose is a utility program which aims to provide a rather simple way to impose PDF documents. Originally written for my own use, it ended up in PoDoFo release as a show-case (don’t rely too much on it).
59 </div>
60
61 <h3>Plan (built-in)</h3>
62 <div class="section"><!-- Plan own -->
63 PodofoImpose is driven by a PLAN file. This file describes how pages from a source PDF document have to be relayout into a target document. We’ll describe how this file must be formatted.
64 <h4>Records</h4>
65 <div>
66 Most of the PLAN file is composed of record lines of the form:
67 <div class="code-abs">
68 source page; target page; rotation; horizontal translation; vertical translation;
69 </div>
70 Each element of the record can be a numeric value, a constant or an expression involving both numerics and constants.
71 </div>
72 <h4>Constants</h4>
73 <div>
74 Constants can be declared everywhere in the PLAN file except in loops. They are 8 bits char strings (except "=") with a leading "$" character which makes them easy to identify. Their value is always interpreted as a float through std::atof. You can "overload" a constant value by redeclaring it. They are declared in this form:
75 <div class="code-abs">
76 $MyConstant = 123.456
77 </div>
78 Note that a PLAN file is valid only if it contains 2 required constants which are "$PageWidth" and "$PageHeight", giving target document dimensions. Now support the "$ScaleFactor" constant -- means that the declared scale factor will be added to the current transformation matrix for each placed page. Constants declarations can hold expressions:
79 <div class="code-abs">
80 $MyConstant = $AnotherConst * .5;
81 </div>
82 Source document pages count is provided as "$PageCount".
83 Source first page geometry is provided as "$SourceWidth" and "$SourceHeight", reflecting geometry given by the MediaBox.
84 </div>
85 <h4>Expressions</h4>
86 <div>
87 An expression is a set of basic mathematic operations +, -, *,/ and % (operands of modulo will be first rounded). As a convenience, we added the | as "max(a,b)" it’s mainly there to allow user to prevent division by 0.
88 <div class="code-abs">
89 $ValueA / ( $ValueB | 0.000001 )
90 </div>
91 Operations are executed from left to right without taking care of any kind of precedance. You can use parenthesis to enclose operations that need to be computed separately. Example:
92 <div class="code-abs">
93 123.456 * ( $ConstantA - ( $ConstantB / 3.14 ) )
94 </div>
95 </div>
96 <h4>Loops</h4>
97 <div>
98 Loops allow users to programmatically generate records. While the concept itself is familiar to programmers I can imagine that regular users would feel not so easy with it. So let me introduce a simple example to explain the thing.
99 </div>
100 <div>
101 Let say we have a source document, A4 format, which has 1000 pages and we just want to position each page of the first half of the document on the center of an A3 plate.
102 <div class="file">
103 <div class="name">A4onA3.plan</div>
104 <div class="content">$PageWidth=842.6
105 $PageHeight=1195.2
106 ## SourceWidth &#38; SourceHeight
107 $sw=597.6
108 $sh=842.4
109 $page=1
110 &#60;$PageCount/2[$page+1]
111 $page; $page; 0; ($PageWidth-$sw)/2; ($PageHeight-$sh)/2;
112 &#62;
113 </div>
114 </div>
115 The loop is what’s enclosed by "&#60;" and "&#62;"characters, the second just indicates the end of the loop. The first first indicates how many iterations (loops) have to be performed &#8212; 500 here. Then comes the interesting part, constants which appear in parenthesis will be incremented by the value following the "+" (can be a minus one, in that case don’t turn the "+" into a "-", just prefix the value with "-" as in [$foo+-1.23]), which means in this example that at each iteration, $page will see its value increased by 1.
116 </div>
117 <div>
118 Constants (which finally turn into variables ;-)) must be declared before the loop. Many constants can be put in loop declaration, separate them with semicolons.
119 </div>
120 <div>
121 <!-- No, loops can’t be nested! -->
122 There is an experimental support of nested loops.
123 </div>
124 <h4>Running</h4>
125 <div>
126 Once you’ve wrote the PLAN file you can run the program:
127 <div class="command">
128 podofoimpose source.pdf target.pdf plan.plan
129 </div>
130 Note the source can be either a PDF file or a text file which is a listing of PDF files. In this case, listed files will be first merged in order.
131 </div>
132 </div> <!-- Plan -->
133 <h3>Plan (Lua)</h3>
134 <div class="section"><!-- lua plan -->
135 PoDoFoImpose now supports Lua scripted plan files. Note that, mainly for security reasons, only the following modules are loaded: base, table, string, math. If you need more, just add luaopen_* calls to LuaMachina::LuaMachina().
136 <h4>Format</h4>
137 <div>
138 Records are pushed with:
139 <div class="command">
140 PushRecord(source page, target page, rotation, x, y);
141 </div>
142 As for regular plan files, there are a couple of provided information through global variables, specifically: "SourceWidth", "SourceHeight", "PageCount". You need to set "PageWidth" and "PageHeight". You may alter the global scale factor (from source to target) by setting "Scale".
143 </div>
144 <h4>Running</h4>
145 <div>
146 There is no format detection mechanism, so you need to append "lua" keyword to podofoimpose invocation when you want it to process a Lua script.
147 </div>
148
149 </div> <!-- lua plan -->
150
151 <h3>Examples</h3>
152 <div class="section"><!-- Examples -->
153 <div>
154 For Lua scripts, some samples can be found in directory tools/podofoimpose/plans/lua of PoDoFo sources tree.
155 </div>
156 <h5>Add a stamp to a document</h5>
157 Shame on me, don’t even have a real stamp at my "office". So I tried something and it worked! Say you have that official one page A4 doc, named official.pdf, on which you want to add a nice stamp. You have your stamp in the file stamp.pdf. You first have to create two files:
158 <div class="file">
159 <div class="name">
160 pdf.list
161 </div>
162 <div class="content">official.pdf
163 stamp.pdf</div>
164 </div>
165 <div class="file">
166 <div class="name">stamponator.plan</div>
167 <div class="content">$PageWidth=597.6
168 $PageHeight=842.4
169 # original page is left unchanged;
170 1; 1; 0; 0; 0;
171 # positioning stamp is up to you!
172 2; 1; 0; 350; 100;</div>
173 </div>
174 Now you can run:
175 <div class="command">podofoimpose pdf.list stamped-official.pdf stamponator.plan</div>
176
177 <h5>Make a tiled poster</h5>
178 <div>
179 Printing a large graphic onto a set of little paper sheets can be handful. Doing it automatically is even better! <!--You can find files used in this example here: <a href="poster.pdf">poster.pdf</a>,
180 <a href="poster_mask.pdf">poster_mask.pdf</a>,
181 <a href="poster.plan">poster.plan</a> and
182 <a href="poster.list">poster.list</a>. Here constants are a bit abbreviated in order to fit in the frame.-->
183 Latest changes allow us to provide you with a quasi all-automatic solution. The only thing that you would want to change (apart from debugging) is the output paper size (here ISO-A4, "Europe oblige !").
184 <div class="file">
185 <div class="name">poster.plan</div>
186 <div class="content">
187 ##POSTER printed on tiled A4 paper sheets.
188 # destination (A4)
189 $PageWidth = 597.6
190 $PageHeight = 842.4
191
192 $sW = $SourceWidth
193 $sH = $SourceHeight
194
195 # with a little trick to get integers
196 $rows = (($sH / $PageHeight) + 1) % (2 * (($sH / $PageHeight)+1))
197 $cols = (($sW / $PageWidth) + 1) % (2 * (($sW / $PageWidth )+1))
198
199 $hbox = ($sW / ($cols | 1))
200 $vbox = ($sH/ ($rows | 1))
201 $hm = ($PageWidth - $hbox ) / 2
202 $vm = ($PageHeight - $vbox ) / 2
203
204 $R = 1
205 $C = 1
206 &#60;$rows[$R+1]
207 &#60;$cols[$C+1]
208 1; (($R - 1)*$cols) + $C; 0; $hm - (($C -1) * $hbox); $vm - (($R-1) * $vbox);
209 &#62;
210 &#62;
211
212 </div>
213 </div>
214 </div>
215 <div class="command">podofoimpose poster.pdf poster_tiled.pdf poster.plan </div>
216 <div>Etc.</div>
217 </div><!-- Examples -->
218 </body>
219 </html>