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