<apidoc:module name="EnityEnrichModule" category="Entity Enrichment" bucket="XQuery Library Modules" 
  xmlns:apidoc="http://marklogic.com/xdmp/apidoc"
  xmlns="http://www.w3.org/1999/xhtml" lib="entity">
  <apidoc:summary access="public">
    <p>The entity enrichment function module is installed as the following 
		  file:</p>
    <ul><li><code><em>install_dir</em>/Modules/MarkLogic/entity.xqy</code></li></ul>
    <p>where <code><em>install_dir</em></code> is the directory in which 
	    MarkLogic Server is installed.</p>
    <p>To use the <code>entity.xqy</code> module in your own XQuery modules, 
    include the following line in your XQuery prolog:</p>
    <p><code>import module namespace entity="http://marklogic.com/entity" 
		    at "/MarkLogic/entity.xqy"</code></p>
    <p>The entity enrichment functions are used to add markup to XML for
	    people, places, and other entities.</p>
      </apidoc:summary>
<apidoc:function name="enrich" type="entity" lib="entity" 
                 category="Entity Enrichment" bucket="XQuery Library Modules">
  <apidoc:summary>
	  Returns the entity-enriched XML for the given XML node.  The entities
	  conform to the MarkLogic-recommended entity markup.  If  
	  a text node that is being enriched has a parent element with a
	  schema definition that does not allow element children, then that
	  text node is not enriched (for example, <code>style</code> elements
	  in an xhtml document).

  </apidoc:summary>
    <apidoc:params>
	  <apidoc:param name="node" type="node()">The XML node to be enriched.
	  </apidoc:param>
  </apidoc:params>
  <apidoc:usage>
	  <p>The elements that are returned are in the
		  <code>http://marklogic.com/entity</code> namespace,
		  bound to the prefix <code>e</code>.  The names and 
		  descriptions of the marked-up elements are as follows:</p>
	  <dl>
		 <dt><code>e:credit-card-number</code></dt>
		 <dd>A number representing a credit card number. </dd>
		 <dt><code>e:coordinate</code></dt>
		 <dd>Latitude and longitude coordinates. </dd>
		 <dt> <code>e:date</code></dt>
		 <dd>Date-related. </dd>
		 <dt> <code>e:distance</code></dt>
		 <dd>A distance. </dd>
		 <dt> <code>e:email</code></dt>
		 <dd>Identifies an email address. </dd>
		 <dt> <code>e:gpe</code></dt>
		 <dd>Geo-political entity. Differs from location because 
			 it has a person-made aspect to it (for example,
			 California is a GPE because its boundaries were 
			 defined by a government). </dd>
		 <dt> <code>e:facility</code></dt>
		 <dd>A place used as a facility. </dd>
		 <dt> <code>e:id</code></dt>
		 <dd>A number identifying a social security number or other 
			 ID number. </dd>
		 <dt> <code>e:location</code></dt>
		 <dd>A geographic location (Mount Everest, for example). </dd>
		 <dt> <code>e:money</code></dt>
		 <dd>Identifies currency (dollars, euros, and so on). </dd>
		 <dt> <code>e:nationality</code></dt>
		 <dd>The nationality of someone or something (for example,
			 American). </dd>
		 <dt> <code>e:number</code></dt>
		 <dd>A number. </dd>
		 <dt> <code>e:organization</code></dt>
		 <dd>An organization. </dd>
		 <dt> <code>e:person</code></dt>
		 <dd>A person. </dd>
		 <dt> <code>e:phone-number</code></dt>
		 <dd>A number identifying a telephone number. </dd>
		 <dt> <code>e:religion</code></dt>
		 <dd>A religion. </dd>
		 <dt> <code>e:title</code></dt>
		 <dd>A title or honorific. </dd>
		 <dt> <code>e:url</code></dt>
		 <dd>A URL on the world wide web. </dd>
		 <dt> <code>e:utm</code></dt>
		 <dd>A point in the Universal Transverse Mercator (UTM)
			 coordinate system. </dd>
		 <dt> <code>e:time</code></dt>
		 <dd>Time-related. </dd>
	 </dl>
  </apidoc:usage>

  <apidoc:return>node()</apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
xquery version "1.0-ml";

import module namespace entity="http://marklogic.com/entity" 
    at "/MarkLogic/entity.xqy";

let $myxml := <node>George Washington never visited Norway.</node>
return
entity:enrich($myxml)

=> <node xmlns:e="http://marklogic.com/entity">
	<e:person>George Washington</e:person> never visited 
	<e:gpe>Norway</e:gpe>.
   </node>
   ]]></pre></apidoc:example>

  <apidoc:example><pre xml:space="preserve"><![CDATA[
xquery version "1.0-ml";

import module namespace entity="http://marklogic.com/entity" 
    at "/MarkLogic/entity.xqy";

let $myxhtml := 
  <p xmlns="http://www.w3.org/1999/xhtml">George 
   Washington never visited 
   <style>Norway</style>.
  </p>
return
entity:enrich($myxhtml)
(: 
   The text inside the style tag is not enriched because
   the xhtml schema does not allow element children
   inside style tags.
:)

=>
<p xmlns="http://www.w3.org/1999/xhtml">
   <e:person xmlns:e="http://marklogic.com/entity">George 
   Washington</e:person> never visited 
  <style>Norway</style>.
</p>
		  ]]></pre></apidoc:example>
  </apidoc:function>
</apidoc:module>
