<apidoc:module name="PDFModule" category="PDF Conversion" bucket="CPF Functions" 
  xmlns:apidoc="http://marklogic.com/xdmp/apidoc"
  xmlns="http://www.w3.org/1999/xhtml" lib="pdf"
>
<apidoc:summary access="public">
<p>The PDF module is part of the conversion processing pipeline.
These functions are used to manipulate XHTML derived by converting 
PDF documents, as part of conversion processing.
</p>
<p>To use the PDF module as part of your own XQuery module, include the
following line in your XQuery prolog:
</p>
<p><code>import module namespace pdf = "http://marklogic.com/cpf/pdf"
         at "/MarkLogic/conversion/pdf.xqy";</code></p>
<p>You will need to ensure that the PDF module is loaded into the same modules
database as the importing module.</p>
<p>The library namespace prefix <code>pdf</code> is <em>not</em> predefined in
the server.</p>
</apidoc:summary>

<apidoc:function name="clean" type="pdf" lib="pdf" 
	category="PDF Conversion" bucket="CPF Functions">
  <apidoc:summary>
  Clean up any conversion artifacts or other infelicities. 
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="node()?">
    The XHTML produced by conversion of a PDF document.
    </apidoc:param>
    <apidoc:param name="toc" type="element()?">
    The TOC produced by conversion of a PDF document.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> node()? </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace pdf = "http://marklogic.com/cpf/pdf" 
		  at "/MarkLogic/conversion/pdf.xqy";

  pdf:clean(fn:doc("my_pdf.xhtml"), pdf:get-toc("my_pdf.xhtml"))
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="get-toc" type="pdf" lib="pdf" 
	category="PDF Conversion" bucket="CPF Functions">
  <apidoc:summary>
  Fetch the linked TOC, if any.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="uri" type="xs:string">
    The URI of the converted PDF document.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element()? </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace pdf = "http://marklogic.com/cpf/pdf" 
		  at "/MarkLogic/conversion/pdf.xqy";

  pdf:get-toc("my_pdf.xhtml")
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="make-toc" type="pdf" lib="pdf" 
	category="PDF Conversion" bucket="CPF Functions">
  <apidoc:summary>
  Clean and normalize the TOC produced by raw conversion.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="toc" type="element()?">
    The raw TOC element.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element()? </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace pdf = "http://marklogic.com/cpf/pdf" 
		  at "/MarkLogic/conversion/pdf.xqy";

  let $results := 
     xdmp:pdf-convert( xdmp:get("/myfiles/myfile.pdf"), "myfile.pdf" )
  let $manifest := $results[1]
  let $toc := 
      for $doc at $index in $results[2 to last()]
      let $name := string($manifest/*[$index])
      where fn:matches( $name, "toc.xml" )
      return $doc
  return pdf:make-toc( $toc )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="insert-toc-headers" type="pdf" lib="pdf" 
	category="PDF Conversion" bucket="CPF Functions">
  <apidoc:summary>
  Locate TOC anchors and make them properly refer to headers at the appropriate
  level. Returned the transformed document.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="node()?">
    The cleaned XHTML produced by PDF conversion.
    </apidoc:param>
    <apidoc:param name="toc" type="element()?">
    The normalized TOC.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> node()? </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace pdf = "http://marklogic.com/cpf/pdf" 
		  at "/MarkLogic/conversion/pdf.xqy";

  xdmp:document-insert( "myfile.xhtml", 
         pdf:insert-toc-headers( doc("myfile.xhtml"), 
                                 pdf:get-toc("myfile.xhtml") )
  )
  ]]></pre>
  </apidoc:example>
</apidoc:function>
</apidoc:module>
