Debian Codegraph @

doc/2-using.html

raw
1 <html>
2 <body>
3
4 <!-- FOOTER RIGHT "2-$CHAPTERPAGE" -->
5 <div align="justify">
6
7 <h1 align="right"><a name="USING">Chapter 2 - Using HTMLDOC</a></h1>
8
9 <p>This chapter describes the basics of how to use HTMLDOC to convert HTML and
10 Markdown files into PostScript and PDF files.</p>
11
12 <blockquote><b>Note:</b> HTMLDOC currently does not support HTML 4.0 features such as stylesheets or the <code>STYLE</code> element. For more information, please consult <a href="#HTMLREF">Chapter 4 - HTML Reference</a>.</blockquote>
13
14
15 <h2>Using the HTMLDOC GUI</h2>
16
17 <p>After opening the HTMLDOC application, the HTMLDOC window will appear with the <var>Input</var> tab selected. Click on the <var>Web Page</var> radio button to specify that you will be converting a web page file. Then choose a file for conversion by clicking on the <var>Add Files...</var> button.</p>
18
19 <p>Now that you've chosen a file to be converted, click on the <var>Output</var> tab to set the output file and format. Finally, click on the <var>Generate</var> button at the bottom of the HTMLDOC window to convert the HTML file.</p>
20
21 <h3>Generating Books</h3>
22
23 <p>While HTMLDOC can convert web pages into PostScript and PDF files, its real strength is generating EPUB, indexed HTML, PostScript, or PDF books. HTMLDOC uses heading elements to delineate chapters and headings in a book. The <CODE>H1</CODE> element is used for chapters:</p>
24
25 <PRE>
26 &lt;HTML&gt;
27 &lt;HEAD&gt;
28 &lt;TITLE&gt;The Little Computer that Could&lt;/TITLE&gt;
29 &lt;/HEAD&gt;
30 &lt;BODY&gt;
31 &lt;H1&gt;Chapter 1 - The Little Computer is Born&lt;/H1&gt;
32 ...
33 &lt;H1&gt;Chapter 2 - Little Computer's First Task&lt;/H1&gt;
34 ...
35 &lt;/BODY&gt;
36 &lt;/HTML&gt;
37 </PRE>
38
39 <P>Sub-headings are marked using the <CODE>H2</CODE> through <CODE>H6</CODE> elements.</P>
40
41 <!-- NEED 2in -->
42 <blockquote><b>Note:</b> When using book mode, HTMLDOC starts rendering with the first <CODE>H1</CODE> element. Any text, images, tables, and other viewable elements that precede the first <CODE>H1</CODE> element are silently ignored. Because of this, make sure you have an <CODE>H1</CODE> element in your HTML file, otherwise HTMLDOC will not convert anything.</blockquote>
43
44 <p>Start by clicking on the <VAR>Book</VAR> radio button to specify you'll be converting one or more files into a book. Then add one or more HTML or Markdown files by clicking on the <var>Add Files...</var> button.</p>
45
46 <p>HTMLDOC will automatically create a title page for you unless you specify a <var>Title File/Image</var>. When the title file is HTML or Markdown, the contents are formatted to produce title page(s). When the title file is an image, the image is centered on the title page with automatically generate content based on the title and other metadata.</p>
47
48 <p>After providing all of the input files, click on the <var>Output</var> tab to select the output format and file. Finally, click on the <var>Generate</var> button to generate the book.</p>
49
50
51 <h2>Using the HTMLDOC Command</h2>
52
53 <p>To convert a single web page type:
54
55 <pre>
56 <kbd>htmldoc --webpage -f output.pdf filename.html ENTER</kbd>
57 </pre>
58
59 <p><tt>htmldoc</tt> is the name of the software.</p>
60
61 <p>The <tt>--webpage</tt> option specifies unstructured files with page breaks between each file.</p>
62
63 <p>The <tt>-f</tt> option specifies the output file name (<tt>output.pdf</tt>). In this example it is a PDF file.</p>
64
65 <p><tt>Filename.html</tt> is the name of the file that you want to be converted.</p>
66
67 <p>To convert more than one web page with page breaks between each file, list each of the files on the end:
68
69 <pre>
70 <kbd>htmldoc --webpage -f output.pdf file1.html file2.html ENTER</kbd>
71 </pre>
72
73 <p>We've been using HTML files, but you can also use URLs. For example:</p>
74
75 <pre>
76 <kbd>htmldoc --webpage -f output.pdf http://slashdot.org/ ENTER</kbd>
77 </pre>
78
79 <!-- NEED 4in -->
80 <h2>Generating Books</h2>
81
82 <p>Type one of the following commands to generate a book from one or more files:
83
84 <pre>
85 <kbd>htmldoc --book -f output.html file1.html file2.html ENTER</kbd>
86 <kbd>htmldoc --book -f output.pdf file1.html file2.html ENTER</kbd>
87 <kbd>htmldoc --book -f output.ps file1.html file2.html ENTER</kbd>
88 </pre>
89
90 <p>The <tt>--book</tt> option specifies that the input files are structured with headings.</p>
91
92 <p>The <tt>-f</tt> option specifies the output filename.
93
94 <p><tt>File1.html</tt> and <tt>file2.html</tt> are the files you want to convert.</p>
95
96 <p>HTMLDOC will build a table of contents for the book using the heading elements (<code>H1</code>, <code>H2</code>, etc.) in your input files. It will also add a title page using the document <code>TITLE</code> text and other <code>META</code> information you supply in your files. See <A HREF="#HTMLREF">Chapter 4 - HTML Reference</A> for more information on the <code>META</code> variables that are supported.</p>
97
98 <blockquote><b>Note:</b> When using book mode, HTMLDOC starts rendering with the first <code>H1</code> element. Any text, images, tables, and other viewable elements that precede the first <code>H1</code> element are silently ignored. Because of this, make sure you have an <code>H1</code> element in your HTML file, otherwise HTMLDOC will not convert anything.</blockquote>
99
100 <h3>Setting the Title File</h3>
101
102 <p>The <tt>--titlefile</tt> option sets the HTML, Markdown, or image file to use on the title page:</p>
103
104 <pre>
105 <kbd>htmldoc --titlefile filename.bmp ... ENTER</kbd>
106 <kbd>htmldoc --titlefile filename.gif ... ENTER</kbd>
107 <kbd>htmldoc --titlefile filename.jpg ... ENTER</kbd>
108 <kbd>htmldoc --titlefile filename.png ... ENTER</kbd>
109 <kbd>htmldoc --titlefile filename.html ... ENTER</kbd>
110 </pre>
111
112 <p>HTMLDOC supports GIF, JPEG, and PNG images, as well as generic HTML or Markdown text you supply for the title page(s).</p>
113
114
115 <h2><a name='CGI'>Using HTMLDOC on a Web Server</a></h2>
116
117 <p>HTMLDOC can be used in a variety of ways to generate formatted reports on a web server. The most common way is to use HTMLDOC as a CGI program with your web server to provide PDF-formatted output of a web page. Examples are provided for Microsoft IIS and the Apache web servers.</p>
118
119 <p>HTMLDOC can also be called from your own server-side scripts and programs. Examples are provided for PHP and Java.</p>
120
121 <blockquote><b>Warning:</b> Passing information directly from the web browser to HTMLDOC can potentially expose your system to security risks. Always be sure to "sanitize" any input from the web browser so that filenames, URLs, and options passed to HTMLDOC are not acted on by the shell program or other processes. Filenames with spaces must usually be enclosed with quotes.</blockquote>
122
123 <h3>CGI Mode</h3>
124
125 <blockquote><b>Note:</b> CGI mode is only available when HTMLDOC is compiled with
126 HTTP/HTTPS support. The snap and MSI versions of HTMLDOC both include support
127 for CGI mode and HTTP/HTTPS references.</blockquote>
128
129 <p>HTMLDOC supports operation as a CGI program. You can copy or symlink the <var>htmldoc</var> (all but Windows) or <var>htmldoc.exe</var> (Windows) executable to your web server's <var>cgi-bin</var> directory and then use it to produce PDF versions of your web pages.</p>
130
131 <p>The CGI converts a page on your local server to PDF and sends it to the client's web browser. For example, to convert a page called <var>superproducts.html</var> at the following URL:</p>
132
133 <pre>
134 http://servername/superproducts.html
135 </pre>
136
137 <p>and if you installed HTMLDOC in your server's <var>cgi-bin</var> directory, you would direct your clients to the following URL:</p>
138
139 <pre>
140 http://servername<b>/cgi-bin/htmldoc</b>/superproducts.html
141 </pre>
142
143 <p>The boldface portion represents the location of the HTMLDOC executable on the web server. You simply place that path before the page you want to convert.</p>
144
145 <p>Form data using the <code>GET</code> method can be passed at the end of the URL, for example:</p>
146
147 <pre>
148 http://servername/cgi-bin/htmldoc/superproducts.html<b>?name=value</b>
149 </pre>
150
151 <h4>Server-Side Preferences</h4>
152
153 <p>When run as a CGI program, HTMLDOC will try to read a book file to set any preferences for the conversion to PDF. For the <var>superproducts.html</var> file described previously, HTMLDOC will look at the following URLs for a book file:</p>
154
155 <pre>
156 http://servername/superproducts.html.book
157 http://servername/.book
158 http://servername/cgi-bin/.book
159 </pre>
160
161 <p>The first book file that is found will be used.</p>
162
163 <h4>Configuring HTMLDOC with Apache</h4>
164
165 <p>The Apache web server is easily configured to use HTMLDOC. The simplest way is to copy or symlink the <var>htmldoc</var> executable to the configured <var>cgi-bin</var> directory. For example, if your Apache installation is configured to look for CGI programs in the <var>/var/www/cgi-bin</var> directory, the default for Apache on Red Hat Linux, then the command to install HTMLDOC on your web server would be:</p>
166
167 <pre>
168 <kbd>ln -s /usr/bin/htmldoc /var/www/cgi-bin ENTER</kbd>
169 </pre>
170
171 <p>If you are using Apache 2.0.30 or higher, you will also need to enable <tt>PATH_INFO</tt> support by adding the following line to your <var>httpd.conf</var> file:</p>
172
173 <pre>
174 AcceptPathInfo On
175 </pre>
176
177 <p>Apache also allows you to associate CGI programs with a specific extension. If you add the following line to your <var>httpd.conf</var> file:</p>
178
179 <pre>
180 AddHandler cgi-script .cgi
181 </pre>
182
183 <p>and enable CGI execution with the <tt>Options</tt> directive for a directory:</p>
184
185 <pre>
186 Options +ExecCGI
187 </pre>
188
189 <p>then you can copy or symlink the <var>htmldoc</var> executable to an alternate location. For example, if you have a web directory called <var>/var/www/htdocs/products</var>, you can install HTMLDOC in this directory with the following command:</p>
190
191 <pre>
192 <kbd>ln -s /usr/bin/htmldoc /var/www/htdocs/products/htmldoc.cgi ENTER</kbd>
193 </pre>
194
195 <h4>Configuring HTMLDOC with Microsoft IIS</h4>
196
197 <p>The IIS web server is configured to run CGI programs by either modifying the permissions of an existing directory or by creating a new virtual directory that allows for execution of programs. Start by running the <var>Internet Services Manager</var> program:</p>
198
199 <ol>
200
201 <li>Click on <var>Start</var></li>
202
203 <li>Click on <var>Settings</var></li>
204
205 <li>Click on <var>Control Panel</var></li>
206
207 <li>Double-click on <var>Administrative Tools</var></li>
208
209 <li>Double-click on <var>Internet Services Manager</var></li>
210
211 </ol>
212
213 <p>After the <var>Internet Services Manager</var> window appears, perform the following steps to add a virtual folder for HTMLDOC:</p>
214
215 <ol>
216
217 <li>Click on your server in the list to show the default web site service in the list</li>
218
219 <li>Choose <var>New->Virtual Directory</var> from the <var>Action</var> menu</li>
220
221 <li>Click <var>Next</var> when the <var>Virtual Directory Creation Wizard</var> window appears</li>
222
223 <li>Enter the name <tt>htmldoc</tt> in the <var>Alias</var> field and click <var>Next</var></li>
224
225 <li>Enter the HTMLDOC program folder in the <var>Directory</var> field and click <var>Next</var></li>
226
227 <li>Check the <var>Execute (such as ISAPI applications or CGI)</var> box and click <var>Next</var></li>
228
229 <li>Click <var>Finish</var> to dismiss the wizard</li>
230
231 <li>Click on <var>Web Service Extensions</var></li>
232
233 <li>Click <var>Add a new Web Service Extension</var></li>
234
235 <li>Enter the name "HTMLDOC" when the <var>Web Service Extension</var> window appears</li>
236
237 <li>Click <var>Add...</var> and choose the <var>htmldoc.exe</var> file from the program folder, typically <var>C:\Program&nbsp;Files\msweet.org\HTMLDOC</var></li>
238
239 <li>Check the <var>Set extension status to Allowed</var> box</li>
240
241 <li>Click <var>OK</var> to add the extension and dismiss the window</li>
242
243 </ol>
244
245 <p>Finally, double-click the <var>My Computer</var> icon on the desktop or start the <var>Windows Explorer</var>. When the explorer window appears, perform the following steps to provide write access to the Windows temporary folder:</p>
246
247 <ol>
248
249 <li>Open the windows temporary file folder, typically <var>C:\WINDOWS\TEMP</var></li>
250
251 <li>Choose <var>Properties</var> from the <var>File</var> menu</li>
252
253 <li>Click on the <var>Security</var> tab</li>
254
255 <li>Click <var>Add...</var>, enter the username for the web server, typically "SERVER\IUSR_SERVER" where "SERVER" is the name you gave your server, and click <var>OK</var></li>
256
257 <li>Click on the username you just added in the list</li>
258
259 <li>Check the <var>Read</var> and <var>Write</var> permissions</li>
260
261 <li>Click <var>OK</var> to save the changes</li>
262
263 </ol>
264
265 <p>Once configured, the <var>htmldoc.exe</var> program will be available in the web server directory. For example, for a virtual directory called <var>cgi-bin</var>, the PDF converted URL for the <var>superproducts.html</var> page would be as follows:</p>
266
267 <pre>
268 http://servername<b>/cgi-bin/htmldoc.exe</b>/superproducts.html
269 </pre>
270
271 <p>The boldface portion represents the location of the HTMLDOC program on the web server.</p>
272
273 <h3>Using HTMLDOC From Server-Side Scripts and Programs</h3>
274
275 <p>To make this work the CGI script or program must send the appropriate HTTP attributes, the required empty line to signify the beginning of the document, and then execute the HTMLDOC program to generate the HTML, PostScript, or PDF file as needed. Since HTMLDOC looks for CGI environment variables when it is run, you must also set the <tt>HTMLDOC_NOCGI</tt> environment variable to a value of 1 before running HTMLDOC from your CGI script or program.</p>
276
277 <p>Another way to generate PDF files from your reports is to use HTMLDOC as a "portal" application. When used as a portal, HTMLDOC automatically retrieves the named document or report from your server and passes a PDF version to the web browser. See the next sections for more information.</p>
278
279 <!-- NEED 6in -->
280 <h4>Calling HTMLDOC from a Shell Script</h4>
281
282 <p>Shell scripts are probably the easiest to work with, but are normally limited to GET type requests. Here is a script called <var>topdf</var> that acts as a portal, converting the named file to PDF:</p>
283
284 <pre>
285 #!/bin/sh
286 #
287 # Sample "portal" script to convert the named HTML file to PDF on-the-fly.
288 #
289 # Usage: http://www.example.com/path/topdf/path/filename.html
290 #
291
292 #
293 # Tell HTMLDOC not to run in CGI mode...
294 #
295
296 HTMLDOC_NOCGI=1; export HTMLDOC_NOCGI
297
298 #
299 # The "options" variable contains any options you want to pass to HTMLDOC.
300 #
301
302 options='-t pdf --webpage --header ... --footer ..."
303
304 #
305 # Tell the browser to expect a PDF file...
306 #
307
308 echo "Content-Type: application/pdf"
309 echo ""
310
311 #
312 # Run HTMLDOC to generate the PDF file...
313 #
314
315 htmldoc $options http://${SERVER_NAME}:${SERVER_PORT}$PATH_INFO
316 </pre>
317
318 <p>Users of this CGI would reference the URL "http://www.example.com/topdf.cgi/index.html" to generate a PDF file of the site's home page.</p>
319
320 <p>The <var>options</var> variable in the script can be set to use any supported command-line option for HTMLDOC; for a complete list see <a href='#CMDREF'>Chapter 3 - Command-Line Reference</a>.</p>
321
322 <!-- NEED 5in -->
323 <h4>Calling HTMLDOC from Perl</h4>
324
325 <p>Perl scripts offer the ability to generate more complex reports, pull data from databases, etc. The easiest way to interface Perl scripts with HTMLDOC is to write a report to a temporary file and then execute HTMLDOC to generate the PDF file.</p>
326
327 <p>Here is a simple Perl subroutine that can be used to write a PDF report to the HTTP client:</p>
328
329 <pre>
330 sub topdf {
331 # Get the filename argument...
332 my $filename = shift;
333
334 # Make stdout unbuffered...
335 select(STDOUT); $| = 1;
336
337 # Tell HTMLDOC not to run in CGI mode...
338 $ENV{HTMLDOC_NOCGI} = 1;
339
340 # Write the content type to the client...
341 print "Content-Type: application/pdf\n\n";
342
343 # Run HTMLDOC to provide the PDF file to the user...
344 system "htmldoc -t pdf --quiet --webpage $filename";
345 }
346 </pre>
347
348 <h4>Calling HTMLDOC from PHP</h4>
349
350 <p>PHP provides a <code>passthru()</code> function that can be used to run HTMLDOC. This combined with the <code>header()</code> function can be used to provide on-the-fly reports in PDF format.</p>
351
352 <p>Here is a simple PHP function that can be used to convert a HTML report to PDF and send it to the HTTP client:</p>
353
354 <pre>
355 function topdf($filename, $options = "") {
356 # Tell HTMLDOC not to run in CGI mode...
357 putenv("HTMLDOC_NOCGI=1");
358
359 # Write the content type to the client...
360 header("Content-Type: application/pdf");
361 flush();
362
363 # Run HTMLDOC to provide the PDF file to the user...
364 passthru("htmldoc -t pdf --quiet --jpeg --webpage $options " . escapeshellarg($filename));
365 }
366 </pre>
367
368 <p>The function accepts a filename and an optional "options" string for specifying the header, footer, fonts, etc.</p>
369
370 <p>To make a "portal" script, add the following code to complete the example:</p>
371
372 <pre>
373 global $SERVER_NAME;
374 global $SERVER_PORT;
375 global $PATH_INFO;
376 global $QUERY_STRING;
377
378 if ($QUERY_STRING != "") {
379 $url = "http://${SERVER_NAME}:${SERVER_PORT}${PATH_INFO}?${QUERY_STRING}";
380 } else {
381 $url = "http://${SERVER_NAME}:${SERVER_PORT}$PATH_INFO";
382 }
383
384 topdf($url);
385 </pre>
386
387 <!-- NEED 5in -->
388 <h4>Calling HTMLDOC from C</h4>
389
390 <p>C programs offer the best flexibility and easily supports on-the-fly report generation without the need for temporary files.</p>
391
392 <p>Here are some simple C functions that can be used to generate a PDF report to the HTTP client from a temporary file or pipe:</p>
393
394 <pre>
395 #include &lt;stdio.h&gt;
396 #include &lt;stdlib.h&gt;
397
398
399 /* topdf() - convert a HTML file to PDF */
400 FILE *topdf(const char *filename) /* I - HTML file to convert */
401 {
402 char command[1024]; /* Command to execute */
403
404
405 /*
406 * Tell HTMLDOC not to run in CGI mode...
407 */
408
409 putenv("HTMLDOC_NOCGI=1");
410
411 /*
412 * Write the content type to the client...
413 */
414
415 puts("Content-Type: application/pdf\n");
416
417 /*
418 * Run HTMLDOC to provide the PDF file to the user...
419 */
420
421 sprintf(command, "htmldoc --quiet -t pdf --webpage %s", filename);
422
423 return (popen(command, "w"));
424 }
425
426
427 /* topdf2() - pipe HTML output to HTMLDOC for conversion to PDF */
428 FILE *topdf2(void)
429 {
430 /*
431 * Tell HTMLDOC not to run in CGI mode...
432 */
433
434 putenv("HTMLDOC_NOCGI=1");
435
436 /*
437 * Write the content type to the client...
438 */
439
440 puts("Content-Type: application/pdf\n");
441
442 /*
443 * Open a pipe to HTMLDOC...
444 */
445
446 return (popen("htmldoc --quiet -t pdf --webpage -", "w"));
447 }
448 </pre>
449
450 <!-- NEED 5in -->
451 <h4>Calling HTMLDOC from Java</h4>
452
453 <p>Java programs are a portable way to add PDF support to your web server. Here is a class called <var>htmldoc</var> that acts as a portal, converting the named file to PDF. It can also be called by your Java servlets to process an HTML file and send the result to the client in PDF format:</p>
454
455 <pre>
456 class htmldoc
457 {
458 // Convert named file to PDF on stdout...
459 public static int topdf(String filename)// I - Name of file to convert
460 {
461 String command; // Command string
462 Process process; // Process for HTMLDOC
463 Runtime runtime; // Local runtime object
464 java.io.InputStream input; // Output from HTMLDOC
465 byte buffer []; // Buffer for output data
466 int bytes; // Number of bytes
467
468
469 // First tell the client that we will be sending PDF...
470 System.out.print("Content-type: application/pdf\n\n");
471
472 // Construct the command string
473 command = "htmldoc --quiet --jpeg --webpage -t pdf --left 36 " +
474 "--header .t. --footer .1. " + filename;
475
476 // Run the process and wait for it to complete...
477 runtime = Runtime.getRuntime();
478
479 try
480 {
481 // Create a new HTMLDOC process...
482 process = runtime.exec(command);
483
484 // Get stdout from the process and a buffer for the data...
485 input = process.getInputStream();
486 buffer = new byte[8192];
487
488 // Read output from HTMLDOC until we have it all...
489 while ((bytes = input.read(buffer)) > 0)
490 System.out.write(buffer, 0, bytes);
491
492 // Return the exit status from HTMLDOC...
493 return (process.waitFor());
494 }
495 catch (Exception e)
496 {
497 // An error occurred - send it to stderr for the web server...
498 System.err.print(e.toString() + " caught while running:\n\n");
499 System.err.print(" " + command + "\n");
500 return (1);
501 }
502 }
503
504 // Main entry for htmldoc class
505 public static void main(String[] args)// I - Command-line args
506 {
507 String server_name, // SERVER_NAME env var
508 server_port, // SERVER_PORT env var
509 path_info, // PATH_INFO env var
510 query_string, // QUERY_STRING env var
511 filename; // File to convert
512
513
514 if ((server_name = System.getProperty("SERVER_NAME")) != null &amp;&amp;
515 (server_port = System.getProperty("SERVER_PORT")) != null &amp;&amp;
516 (path_info = System.getProperty("PATH_INFO")) != null)
517 {
518 // Construct a URL for the resource specified...
519 filename = "http://" + server_name + ":" + server_port + path_info;
520
521 if ((query_string = System.getProperty("QUERY_STRING")) != null)
522 {
523 filename = filename + "?" + query_string;
524 }
525 }
526 else if (args.length == 1)
527 {
528 // Pull the filename from the command-line...
529 filename = args[0];
530 }
531 else
532 {
533 // Error - no args or env variables!
534 System.err.print("Usage: htmldoc.class filename\n");
535 return;
536 }
537
538 // Convert the file to PDF and send to the web client...
539 topdf(filename);
540 }
541 }
542 </pre>
543
544 </div>
545
546 </body>
547 </html>