source: wkhtmltox/trunk/fuentes/src/pdf/pdfdocparts.cc @ 51

Last change on this file since 51 was 51, checked in by mabarracus, 4 years ago

wip

File size: 16.8 KB
Line 
1// -*- mode: c++; tab-width: 4; indent-tabs-mode: t; eval: (progn (c-set-style "stroustrup") (c-set-offset 'innamespace 0)); -*-
2// vi:set ts=4 sts=4 sw=4 noet :
3//
4// Copyright 2010, 2011 wkhtmltopdf authors
5//
6// This file is part of wkhtmltopdf.
7//
8// wkhtmltopdf is free software: you can redistribute it and/or modify
9// it under the terms of the GNU Lesser General Public License as published by
10// the Free Software Foundation, either version 3 of the License, or
11// (at your option) any later version.
12//
13// wkhtmltopdf is distributed in the hope that it will be useful,
14// but WITHOUT ANY WARRANTY; without even the implied warranty of
15// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16// GNU General Public License for more details.
17//
18// You should have received a copy of the GNU Lesser General Public License
19// along with wkhtmltopdf.  If not, see <http://www.gnu.org/licenses/>.
20
21#include "outputter.hh"
22#include "pdfcommandlineparser.hh"
23#include <QWebFrame>
24
25#define STRINGIZE_(x) #x
26#define STRINGIZE(x) STRINGIZE_(x)
27
28/*!
29  Output name and a short description
30  \param o The outputter to output to
31*/
32void PdfCommandLineParser::outputManName(Outputter * o) const {
33        o->beginSection("Name");
34        o->paragraph("wkhtmltopdf - html to pdf converter");
35        o->endSection();
36}
37
38/*!
39  Output a short synopsis on how to call the command line program
40  \param o The outputter to output to
41*/
42void PdfCommandLineParser::outputSynopsis(Outputter * o) const {
43        o->beginSection("Synopsis");
44        o->verbatim("wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output file>\n");
45        o->endSection();
46
47        o->beginSection("Document objects");
48        o->beginParagraph();
49        o->text("wkhtmltopdf is able to put several objects into the output file, an object is either "
50                        "a single webpage, a cover webpage or a table of content.  The objects are put into "
51                        "the output document in the order they are specified on the command line, options can "
52                        "be specified on a per object basis or in the global options area. Options from the ");
53        o->sectionLink("Global Options");
54        o->text(" section can only be placed in the global options area");
55        o->endParagraph();
56
57        o->paragraph("A page objects puts the content of a singe webpage into the output document.");
58        o->verbatim("(page)? <input url/file name> [PAGE OPTION]...");
59        o->beginParagraph();
60        o->text("Options for the page object can be placed in the global options and the page "
61                        "options areas. The applicable options can be found in the ");
62        o->sectionLink("Page Options");
63        o->text(" and ");
64        o->sectionLink("Headers And Footer Options");
65        o->text(" sections.");
66        o->endParagraph();
67
68        o->paragraph("A cover objects puts the content of a singe webpage into the output document, "
69                                 "the page does not appear in the table of content, and does not have headers and footers.");
70        o->verbatim("cover <input url/file name> [PAGE OPTION]...");
71        o->paragraph("All options that can be specified for a page object can also be specified for a cover.");
72
73        o->paragraph("A table of content object inserts a table of content into the output document.");
74        o->verbatim("toc [TOC OPTION]...");
75        o->beginParagraph();
76        o->text("All options that can be specified for a page object can also be specified for a toc, "
77                        "further more the options from the ");
78        o->sectionLink("TOC Options");
79        o->text(" section can also be applied. The table of content is generated via XSLT which means "
80                        "that it can be styled to look however you want it to look. To get an aide of how to "
81                        "do this you can dump the default xslt document by supplying the --dump-default-toc-xsl, and the outline it works on by supplying --dump-outline, see the ");
82        o->sectionLink("Outline Options");
83        o->text(" section.");
84        o->endParagraph();
85
86        o->endSection();
87}
88
89
90/*!
91  Explain what the program does
92  \param o The outputter to output to
93*/
94void PdfCommandLineParser::outputDescripton(Outputter * o) const {
95        o->beginSection("Description");
96        o->beginParagraph();
97        o->text("Converts one or more HTML pages into a PDF document, ");
98#ifdef __EXTENSIVE_WKHTMLTOPDF_QT_HACK__
99        o->text("using wkhtmltopdf patched qt.");
100#else
101        o->bold("not");
102        o->text(" using wkhtmltopdf patched qt.");
103#endif
104        o->endParagraph();
105        o->endSection();
106}
107
108/*!
109  Add explanation about reduced functionality without patched qt/webkit
110  \param o The outputter to output to
111  \param sure Is the functionality restricted in this wkhtmltopdf
112*/
113void PdfCommandLineParser::outputNotPatched(Outputter * o, bool sure) const {
114        o->beginSection("Reduced Functionality");
115        if (sure)
116                o->paragraph("This version of wkhtmltopdf has been compiled against a version of "
117                                         "QT without the wkhtmltopdf patches. Therefore some features are missing, "
118                                         "if you need these features please use the static version.");
119        else
120                o->paragraph("Some versions of wkhtmltopdf are compiled against a version of QT "
121                                         "without the wkhtmltopdf patches. These versions are missing some features, "
122                                         "you can find out if your version of wkhtmltopdf is one of these by running wkhtmltopdf --version "
123                                         "if your version is against an unpatched QT, you can use the static version to get all functionality.");
124
125        o->paragraph("Currently the list of features only supported with patch QT includes:");
126        o->beginList();
127        o->listItem("Printing more than one HTML document into a PDF file.");
128        o->listItem("Running without an X11 server.");
129        o->listItem("Adding a document outline to the PDF file.");
130        o->listItem("Adding headers and footers to the PDF file.");
131        o->listItem("Generating a table of contents.");
132        o->listItem("Adding links in the generated PDF file.");
133        o->listItem("Printing using the screen media-type.");
134        o->listItem("Disabling the smart shrink feature of webkit.");
135        o->endList();
136        o->endSection();
137}
138
139/*!
140  Explain the page breaking is somewhat broken
141  \param o The outputter to output to
142*/
143void PdfCommandLineParser::outputPageBreakDoc(Outputter * o) const {
144        o->beginSection("Page Breaking");
145        o->paragraph(
146                "The current page breaking algorithm of WebKit leaves much to be desired. "
147                "Basically Webkit will render everything into one long page, and then cut it up "
148                "into pages. This means that if you have two columns of text where one is "
149                "vertically shifted by half a line. Then Webkit will cut a line into to pieces "
150                "display the top half on one page. And the bottom half on another page. "
151                "It will also break image in two and so on.  If you are using the patched version of "
152                "QT you can use the CSS page-break-inside property to remedy this somewhat. "
153                "There is no easy solution to this problem, until this is solved try organizing "
154                "your HTML documents such that it contains many lines on which pages can be cut "
155                "cleanly.");
156        o->endSection();
157}
158
159/*!
160  Output documentation about headers and footers
161  \param o The outputter to output to
162*/
163void PdfCommandLineParser::outputHeaderFooterDoc(Outputter * o) const {
164        o->beginSection("Footers And Headers");
165        o->paragraph("Headers and footers can be added to the document by the --header-* and --footer* "
166                                 "arguments respectfully.  In header and footer text string supplied to e.g. --header-left, "
167                                 "the following variables will be substituted.");
168        o->verbatim(
169" * [page]       Replaced by the number of the pages currently being printed\n"
170" * [frompage]   Replaced by the number of the first page to be printed\n"
171" * [topage]     Replaced by the number of the last page to be printed\n"
172" * [webpage]    Replaced by the URL of the page being printed\n"
173" * [section]    Replaced by the name of the current section\n"
174" * [subsection] Replaced by the name of the current subsection\n"
175" * [date]       Replaced by the current date in system local format\n"
176" * [isodate]    Replaced by the current date in ISO 8601 extended format\n"
177" * [time]       Replaced by the current time in system local format\n"
178" * [title]      Replaced by the title of the of the current page object\n"
179" * [doctitle]   Replaced by the title of the output document\n"
180" * [sitepage]   Replaced by the number of the page in the current site being converted\n"
181" * [sitepages]  Replaced by the number of pages in the current site being converted\n"
182"\n");
183        o->paragraph("As an example specifying --header-right \"Page [page] of [toPage]\", "
184                                 "will result in the text \"Page x of y\" where x is the number of the "
185                                 "current page and y is the number of the last page, to appear in the upper "
186                                 "left corner in the document.");
187        o->paragraph("Headers and footers can also be supplied with HTML documents. As an example one "
188                                 "could specify --header-html header.html, and use the following content in header.html:");
189        o->verbatim(
190"<html><head><script>\n"
191"function subst() {\n"
192"  var vars={};\n"
193"  var x=window.location.search.substring(1).split('&');\n"
194"  for (var i in x) {var z=x[i].split('=',2);vars[z[0]] = unescape(z[1]);}\n"
195"  var x=['frompage','topage','page','webpage','section','subsection','subsubsection'];\n"
196"  for (var i in x) {\n"
197"    var y = document.getElementsByClassName(x[i]);\n"
198"    for (var j=0; j<y.length; ++j) y[j].textContent = vars[x[i]];\n"
199"  }\n"
200"}\n"
201"</script></head><body style=\"border:0; margin: 0;\" onload=\"subst()\">\n"
202"<table style=\"border-bottom: 1px solid black; width: 100%\">\n"
203"  <tr>\n"
204"    <td class=\"section\"></td>\n"
205"    <td style=\"text-align:right\">\n"
206"      Page <span class=\"page\"></span> of <span class=\"topage\"></span>\n"
207"    </td>\n"
208"  </tr>\n"
209"</table>\n"
210"</body></html>\n"
211"\n"
212                );
213        o->paragraph("As can be seen from the example, the arguments are sent to the header/footer "
214                                 "html documents in get fashion.");
215        o->endSection();
216}
217
218void PdfCommandLineParser::outputTableOfContentDoc(Outputter * o) const {
219        o->beginSection("Table Of Content");
220        o->paragraph("A table of content can be added to the document by adding a toc object "
221                                 "to the command line. For example:");
222        o->verbatim("wkhtmltopdf toc http://qt-project.org/doc/qt-4.8/qstring.html qstring.pdf\n");
223        o->paragraph("The table of content is generated based on the H tags in the input "
224                                 "documents. First a XML document is generated, then it is converted to "
225                                 "HTML using XSLT.");
226        o->paragraph("The generated XML document can be viewed by dumping it to a file using "
227                                 "the --dump-outline switch. For example:");
228        o->verbatim("wkhtmltopdf --dump-outline toc.xml http://qt-project.org/doc/qt-4.8/qstring.html qstring.pdf\n");
229        o->paragraph("The XSLT document can be specified using the --xsl-style-sheet switch. "
230                                 "For example:");
231        o->verbatim("wkhtmltopdf toc --xsl-style-sheet my.xsl http://qt-project.org/doc/qt-4.8/qstring.html qstring.pdf\n");
232        o->paragraph("The --dump-default-toc-xsl switch can be used to dump the default "
233                                 "XSLT style sheet to stdout. This is a good start for writing your "
234                                 "own style sheet");
235        o->verbatim("wkhtmltopdf --dump-default-toc-xsl");
236        o->paragraph("The XML document is in the namespace "
237                                 "\"http://wkhtmltopdf.org/outline\" "
238                                 "it has a root node called \"outline\" which contains a number of "
239                                 "\"item\" nodes. An item can contain any number of item. These are the "
240                                 "outline subsections to the section the item represents. A item node "
241                                 "has the following attributes:");
242        o->beginList();
243        o->listItem("\"title\" the name of the section.");
244        o->listItem("\"page\" the page number the section occurs on.");
245        o->listItem("\"link\" a URL that links to the section.");
246        o->listItem("\"backLink\" the name of the anchor the the section will link back to.");
247        o->endList();
248
249        o->paragraph("The remaining TOC options only affect the default style sheet "
250                                 "so they will not work when specifying a custom style sheet.");
251        o->endSection();
252}
253
254/*!
255  Output documentation about outlines
256  \param o The outputter to output to
257*/
258void PdfCommandLineParser::outputOutlineDoc(Outputter * o) const {
259        o->beginSection("Outlines");
260        o->beginParagraph();
261        o->text(
262                "Wkhtmltopdf with patched qt has support for PDF outlines also known as "
263                "book marks, this can be enabled by specifying the --outline switch. "
264                "The outlines are generated based on the <h?> tags, for a in-depth "
265                "description of how this is done see the ");
266        o->sectionLink("Table Of Content");
267        o->text(" section. ");
268        o->endParagraph();
269        o->paragraph(
270                "The outline tree can sometimes be very deep, if the <h?> tags where "
271                "spread to generous in the HTML document.  The --outline-depth switch can "
272                "be used to bound this.");
273        o->endSection();
274}
275
276/*!
277  Output contact information
278  \param o The outputter to output to
279*/
280void PdfCommandLineParser::outputContact(Outputter * o) const {
281        o->beginSection("Contact");
282        o->beginParagraph();
283        o->text("If you experience bugs or want to request new features please visit ");
284        o->link("https://github.com/wkhtmltopdf/wkhtmltopdf/issues");
285        o->endParagraph();
286        o->endSection();
287}
288
289/*!
290  Output beginning of the readme
291  \param o The outputter to output to
292*/
293void PdfCommandLineParser::outputDocStart(Outputter * o) const {
294        o->beginSection("wkhtmltopdf " STRINGIZE(FULL_VERSION) " Manual");
295        o->paragraph("This file documents wkhtmltopdf, a program capable of converting html "
296                                 "documents into PDF documents.");
297        o->endSection();
298}
299
300/*!
301  Output information on how to use read-args-from-stdin
302  \param o The outputter to output to
303*/
304void PdfCommandLineParser::outputArgsFromStdin(Outputter * o) const {
305        o->beginSection("Reading arguments from stdin");
306        o->paragraph("If you need to convert a lot of pages in a batch, and you feel that wkhtmltopdf "
307                                 "is a bit to slow to start up, then you should try --read-args-from-stdin,");
308        o->paragraph("When --read-args-from-stdin each line of input sent to wkhtmltopdf on stdin "
309                                 "will act as a separate invocation of wkhtmltopdf, with the arguments specified "
310                                 "on the given line combined with the arguments given to wkhtmltopdf");
311        o->paragraph("For example one could do the following:");
312        o->verbatim("echo \"http://qt-project.org/doc/qt-4.8/qapplication.html qapplication.pdf\" >> cmds\n"
313                                "echo \"cover google.com http://en.wikipedia.org/wiki/Qt_(software) qt.pdf\" >> cmds\n"
314                                "wkhtmltopdf --read-args-from-stdin --book < cmds\n");
315        o->endSection();
316}
317
318/*!
319  Output information on how to install
320  \param o The outputter to output to
321*/
322void PdfCommandLineParser::outputInstallation(Outputter * o) const {
323        o->beginSection("Installation");
324        o->paragraph(
325                "There are several ways to install wkhtmltopdf.  You can download a "
326                "already compiled binary, or you can compile wkhtmltopdf yourself. "
327                "On windows the easiest way to install wkhtmltopdf is to download "
328                "the latest installer. On Linux you can download the latest static "
329                "binary, however you still need to install some other pieces of "
330                "software, to learn more about this read the static version section "
331                "of the manual.");
332        o->endSection();
333}
334
335/*!
336  Output documentation about page sizes
337  \param o The outputter to output to
338
339*/
340void PdfCommandLineParser::outputPageSizes(Outputter * o) const {
341        o->beginSection("Page sizes");
342        o->beginParagraph();
343        o->text("The default page size of the rendered document is A4, but using this --page-size option"
344                        "this can be changed to almost anything else, such as: A3, Letter and Legal.  "
345                        "For a full list of supported pages sizes please see ");
346        o->link("http://qt-project.org/doc/qt-4.8/qprinter.html#PaperSize-enum");
347        o->text(".");
348        o->endParagraph();
349        o->paragraph("For a more fine grained control over the page size the "
350                                 "--page-height and --page-width options may be used");
351        o->endSection();
352}
353
354/*!
355  Output examples on how to use wkhtmltopdf
356  \param o The outputter to output to
357*/
358void PdfCommandLineParser::outputExamples(Outputter * o) const {
359        o->beginSection("Examples");
360        o->paragraph("This section presents a number of examples of how to invoke wkhtmltopdf.");
361        o->paragraph("To convert a remote HTML file to PDF:");
362        o->verbatim("wkhtmltopdf http://www.google.com google.pdf\n");
363        o->paragraph("To convert a local HTML file to PDF:");
364        o->verbatim("wkhtmltopdf my.html my.pdf\n");
365        o->paragraph("Produce the eler2.pdf sample file:");
366        o->verbatim("wkhtmltopdf -H  http://geekz.co.uk/lovesraymond/archive/eler-highlights-2008 eler2.pdf\n");
367        o->paragraph("Printing a book with a table of content:");
368        o->verbatim("wkhtmltopdf -H cover cover.html toc chapter1.html chapter2.html chapter3.html book.pdf\n");
369        o->endSection();
370}
371
372//  LocalWords:  webkit bool unpatched beginList listItem endList WebKit http
373//  LocalWords:  stroustrup wkhtmltopdf commandlineparser hh QWebFrame param px
374//  LocalWords:  STRINGIZE outputter const beginSection beginParagraph QString
375//  LocalWords:  ifdef endif endParagraph endSection GPLv GPL Truelsen Mário td
376//  LocalWords:  Bouthenot PDF CSS username BNF frompage topage webpage toPage
377//  LocalWords:  html subst unescape subsubsection getElementsByClassName args
378//  LocalWords:  textContent onload readme stdin qapplication pdf cmds google
379//  LocalWords:  todo gcc openssl sudo dep libqt gui xorg wget xvf svn linux ps
380//  LocalWords:  PageSize enum eler glibc xserver xfonts libssl dev wkhtml cd
381//  LocalWords:  nomake opensource xslt
Note: See TracBrowser for help on using the repository browser.