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

<apidoc:function name="clean" type="xhtml" lib="xhtml" 
	category="XHTML Conversion" bucket="CPF Functions">
  <apidoc:summary>
  Clean up the XHTML: pruning empty spans, consolidating adjacent spans, etc.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="node()?">
    The source XHTML.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> node()? </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace xhtml = "http://marklogic.com/cpf/xhtml" 
		  at "/MarkLogic/conversion/xhtml.xqy";

  xhtml:clean(fn:doc("my.xhtml"))
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="restructure" type="xhtml" lib="xhtml" 
	category="XHTML Conversion" bucket="CPF Functions">
  <apidoc:summary>
  Turn an XHTML with flat structure into one with div structure based on
  the header elements. 
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="node()?">
    The source XHTML.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> node()? </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  declare default element namespace "http://www.w3.org/1999/xhtml";

  import module namespace xhtml = "http://marklogic.com/cpf/xhtml" 
		  at "/MarkLogic/conversion/xhtml.xqy";

  let $unstructured :=
     <html>
       <head><title>Example</title></head>
       <body>
          <h1>First section</h1>
          <p>First paragraph.</p>
          <p>Second paragraph.</p>
          <h2>Subheader</h2>
          <p>Sub paragraph.</p>
          <h1>Second section</h1>
          <p>Last paragraph.</p>
       </body>
     </html>
  return xhtml:restructure( $unstructured )

  Returns:
    <html>
      <head><title>Example</title></head>
      <body>
         <div class="mlsection1">
           <h1>First section</h1>
           <p>First paragraph.</p>
           <p>Second paragraph.</p>
           <div class="mlsection2">
             <h2>Subheader</h2>
             <p>Sub paragraph.</p>
           </div>
         </div>
         <div class="mlsection1">
           <h1>Second section</h1>
           <p>Last paragraph.</p>
         </div>
      </body>
    </html>
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="add-lists" type="xhtml" lib="xhtml" 
	category="XHTML Conversion" bucket="CPF Functions">
  <apidoc:summary>
  Infer numbered or bulleted lists and insert appropriate markup.
  Restructuring first is highly recommended to improve both
  accuracy and performance. This function also assumes that indentation
  styling is already present on the paragraphs in the original input.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="node()?">
    The source XHTML.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> node()? </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  declare default element namespace "http://www.w3.org/1999/xhtml";

  import module namespace xhtml = "http://marklogic.com/cpf/xhtml" 
		  at "/MarkLogic/conversion/xhtml.xqy";

  let $raw :=
     <html>
       <head><title>Example</title></head>
       <body>
          <div class="mlsection1">
            <h1>Section header</h1>
            <p>1. First paragraph.</p>
            <p>2. Second paragraph.</p>
            <p>a. Sub-topic 1.</p>
            <p>b. Sub-topic 1.</p>
            <p>3. Third paragraph</p>
            <div class="mlsection2">
              <h2>Subheader</h2>
              <p>1. Sub paragraph.</p>
            </div>
          </div>
       </body>
     </html>
  return xhtml:add-lists( $raw )

  Returns:
     <html>
       <head><title>Example</title></head>
       <body>
          <div class="mlsection1">
            <h1>Section header</h1>
            <ol style="list-style-type: none; margin-left: 0pt">
              <li>1. First paragraph.</li>
              <li>2. Second paragraph.</li>
              <ol style="list-style-type: none; margin-left: 0pt">
                <li>a. Sub-topic 1.</li>
                <li>b. Sub-topic 1.</li>
              </ol>
              <li>3. Third paragraph</li>
            </ol>
            <div class="mlsection2">
              <h2>Subheader</h2>
              <p>1. Sub paragraph.</p>
            </div>
          </div>
       </body>
     </html>
  ]]></pre>
  </apidoc:example>
</apidoc:function>
</apidoc:module>
