File: 2-using.html

package info (click to toggle)
htmldoc 1.9.11-4%2Bdeb11u3
links: PTS
area: main
in suites: bullseye
size: 14,976 kB
sloc: ansic: 70,003; cpp: 24,681; makefile: 362; sh: 149; java: 59; php: 36; python: 13; xml: 10; perl: 7
file content (543 lines) | stat: -rw-r--r-- 21,295 bytes
<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>
&lt;HTML&gt;
&lt;HEAD&gt;
    &lt;TITLE&gt;The Little Computer that Could&lt;/TITLE&gt;
&lt;/HEAD&gt;
&lt;BODY&gt;
&lt;H1&gt;Chapter 1 - The Little Computer is Born&lt;/H1&gt;
...
&lt;H1&gt;Chapter 2 - Little Computer's First Task&lt;/H1&gt;
...
&lt;/BODY&gt;
&lt;/HTML&gt;
</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&nbsp;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 &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;


/* 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 &amp;&amp;
        (server_port = System.getProperty("SERVER_PORT")) != null &amp;&amp;
        (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>