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" -->
<div align="justify">
<h1 align="right"><a name="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 <a href="#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 <A HREF="#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 BMP, GIF, JPEG, and PNG images, as well as generic HTML or Markdown text you supply for the title page(s).</p>
<h2><a name='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 <a href='#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>
|