<apidoc:module name="PDFConvert" category="Document Conversion" lib="xdmp" xmlns:apidoc="http://marklogic.com/xdmp/apidoc"><apidoc:summary access="public">
  <p xmlns="http://www.w3.org/1999/xhtml">Includes the PDF convert functions using the Iceni technology.</p>
</apidoc:summary><apidoc:function name="pdf-convert" type="builtin" lib="xdmp" category="Document Conversion" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Converts a PDF file to XHTML. Returns several nodes,
  including a parts node, the converted document xml node, and any 
  other document parts (for example, css files and images).  The first 
  node is the parts node, which contains a manefest of all of the parts 
  generated as result of the conversion.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="doc" type="node()" optional="false">
  PDF document to convert to HTML, as a binary node().
  </apidoc:param>
      <apidoc:param name="filename" type="xs:string" optional="false">
    The root for the name of the converted files and directories. If the
    specified filename includes an extension, then the extension is appended
    to the root with an underscore. The directory for other parts of the
    conversion (images, for example) has the string "_parts" appended to the
    root. For example, if you specify a filename of "myFile.pdf", the
    generated names will be "myFile_pdf.xhtml" for the xml node and
    "myFile_pdf_parts" for the directory containing the any other parts
    generated by the conversion (images, css files, and so on).   
  </apidoc:param>
      <apidoc:param name="options" type="node()?" optional="true">
    Options element for this conversion.  The options element must be in the
    <code xmlns="http://www.w3.org/1999/xhtml">xdmp:pdf-convert</code> namespace. The default value is (). In 
    addition to the options shown below, you can specify <code xmlns="http://www.w3.org/1999/xhtml">xdmp:tidy</code>
    options by entering the tidy option elements in the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:tidy</code> 
    namespace.
    <p xmlns="http://www.w3.org/1999/xhtml">Options include:</p>
    <blockquote xmlns="http://www.w3.org/1999/xhtml"><dl>
    <dt><p>&lt;tidy&gt;</p></dt>
    <dd>Default value: <code>true</code> <br/><br/>
    Specify <code>true</code> to run tidy on the document and 
    <code>false</code> not to run tidy. If you run tidy, you can also 
    specify any <a href="xdmp:tidy">xdmp:tidy options</a>. Any tidy option 
    elements must be in the <code>xdmp:tidy</code> namespace.</dd>
    <dt><p>&lt;config&gt;</p></dt>
    <dd>The configuration file for the conversion. You can specify an
    absolute path or a relative path. The relative path is relative
    to the <code>&lt;install_dir&gt;/Converters/cvtpdf</code> directory.
    The default configuration file is named <code>PDFtoHTML.cfg</code>;
    it produces a single reflowed XHTML document with CSS styling. Setting
    this parameter may override the remaining options.</dd> 
    <dt><p>&lt;page-by-page&gt;</p></dt>
    <dd>Default value: <code>false</code><br/><br/>
    Specify <code>true</code> to select a different default configuration
    file that produces one XHTML document per page with absolute positioning.
    The default paged configuration file is named 
    <code>PDFtoXHTML_pages.cfg</code> 
    If a specific configuration file is selected with the <code>config</code> 
    option, the <code>page-by-page</code> option has no effect.
    </dd>
    <dt><p>&lt;page-start-id&gt;</p></dt>
    <dd>Default value: <code>0</code><br/><br/>
    The index of the first page to convert. Page indices start at zero.
    </dd>
    <dt><p>&lt;page-end-id&gt;</p></dt>
    <dd>Default value: <code>-1</code><br/><br/>
    The index of the last page to convert. Page indices start at zero.
    The default is -1, meaning to convert through the last page of the 
    document.   
    </dd>
    <dt><p>&lt;synth-bookmarks&gt;</p></dt>
    <dd>Default value: <code>true</code><br/><br/>
    Enable/disable converter's internal font-based TOC inferences.
    </dd>
    <dt><p>&lt;image-output&gt;</p></dt>
    <dd>Default value: <code>true</code><br/><br/>
    Enable/disable extraction and conversion of images.
    </dd>
    <dt><p>&lt;text-output&gt;</p></dt>
    <dd>Default value: <code>true</code><br/><br/>
    Enable/disable extraction of text.
    </dd>
    <dt><p>&lt;zones&gt;</p></dt>
    <dd>Default value: <code>false</code><br/><br/>
    Enable/disable zone controls. Using <code>true</code> produces better
    results when the PDF is annotated; using <code>false</code> produces 
    better results in non-annotated tables.
    </dd>
    <dt><p>&lt;ignore-text&gt;</p></dt>
    <dd>Default value: <code>true</code><br/><br/>
    Enable/disable extraction of text from images. Documents consisting of
    scanned pages can only have text extracted if this parameter is set to 
    <code>true</code>; however, diagrams with embedded text labels may
    be less palatable. For page-by-page conversion, the problem with reflowing
    of text and graphical elements within a diagram giving poor results is
    not such a problem, and the value of <code>false</code> will probably
    be the better choice.
    </dd>
    <dt><p>&lt;remove-overprint&gt;</p></dt>
    <dd>Default value: <code>false</code><br/><br/>
    Enable/disable removal of text overlays. Setting this parameter to 
    <code>true</code> can sometimes clean up messy results stemming from
    reflowing of text that was not visible in the original PDF because it
    was covered by something else.
    </dd>
    <dt><p>&lt;illustrations&gt;</p></dt>
    <dd>Default value: <code>true</code><br/><br/>
    Enable/disable extraction of illustrations. Setting this parameter to 
    <code>false</code> can sometimes clean up messy results stemming from
    minor and unnecessary graphical ornaments. 
    </dd>
    <dt><p>&lt;image-quality&gt;</p></dt>
    <dd>Default value: <code>75</code><br/><br/>
    Determines the quality of extracted and converted images: smaller values
    mean smaller image sizes (in bytes) but lossier rendering. The maximum is
    100.
    </dd>
    <dt><p>&lt;page-start&gt;</p></dt>
    <dd>Default value: <code></code><br/><br/>
    Boilerplate text inserted at the start of every page. Any XML markup
    must be escaped. For example: <code>&amp;lt;p&gt;PAGE START&amp;lt/p&gt;</code>
    </dd>
    <dt><p>&lt;page-end&gt;</p></dt>
    <dd>Default value: <code></code><br/><br/>
    Boilerplate text inserted at the end of every page. XML markup must be
    escaped.
    </dd>
    <dt><p>&lt;document-start&gt;</p></dt>
    <dd>Default value: <code></code><br/><br/>
    Boilerplate text inserted at the start of every document. XML markup
    must be escaped.
    </dd>
    <dt><p>&lt;document-end&gt;</p></dt>
    <dd>Default value: <code></code><br/><br/>
    Boilerplate text inserted at the end of every document. XML markup must
    be escaped.
    </dd>
    <dt><p>&lt;password&gt;</p></dt>
    <dd>Default value: <code></code><br/><br/>
    The password required to open a password-protected PDF.
    </dd>
    <dt><p>Sample Options Node:</p></dt>
    <dd>The following is a sample options node which specifies that tidy is
    used to clean the generated html, specifies to use the tidy "clean" option,
    and specifies a particular configuration file to use for the conversion:
    <pre xml:space="preserve">
&lt;options xmlns="xdmp:pdf-convert"
         xmlns:tidy="xdmp:tidy"&gt;
  &lt;tidy&gt;true&lt;/tidy&gt;
  &lt;tidy:clean&gt;yes&lt;/tidy:clean&gt;
  &lt;config&gt;c:\myConfigFile.cfg&lt;/config&gt;
&lt;/options&gt;
</pre></dd>
    </dl>
    </blockquote>
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>node()*</apidoc:return>
    <apidoc:usage>
  The convert functions return several nodes.  The first node is a manifest
  containing the various parts of the conversion. Typically there will be
  an xml part, a css part, and some image parts.  Each part is returned as
  a separate node in the order shown in the manifest. 
  <p xmlns="http://www.w3.org/1999/xhtml">Therefore, given the following manifest: </p>
  <pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
&lt;parts&gt;
  &lt;part&gt;myFile_pdf.xhtml&lt;/part&gt;
  &lt;part&gt;myFile_pdf_parts/conv.css&lt;/part&gt;
  &lt;part&gt;myFile_pdf_parts/toc.xml&lt;/part&gt;
&lt;/parts&gt;
</pre>
  <p xmlns="http://www.w3.org/1999/xhtml">the first node of the returned query is the manifest, the second is the 
  "myFile_pdf.xhtml" node, the third is the "myFile_pdf_parts/conv.css" node, 
  and the fourth is the myFile_pdf_parts/toc.xml node.</p>
  
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
let $results := xdmp:pdf-convert( 
                         xdmp:document-get("myFile.pdf"),
                         "myFile.pdf" ),
    $manifest := $results[1]
return 
$results[2 to last()]

=&gt; all of the converted nodes
</pre></apidoc:example>
  </apidoc:function></apidoc:module>