XNAL usage guidelines

Extended information and usage examples for DITA bookmap metadata elements associated with OASIS xNAL Standard (extensible Name and Address Language).

DITA bookmaps use a set of elements associated with a subset of the [[OASIS extensible Name and Address Language (xNAL)]] specification (Version 2) to denote name and address information related to persons and organizations.

While the elements share element names, and the expectation is that content written using this type of metadata should be straightforward to transform, the element name pairs do not share content models. The difference in content models reflects the different purposes of the two standards. The purpose of the name and address elements in DITA is to identify persons or organizations associated with the creation of a document; the purpose of the name and address elements in xNAL is to support customer resource management.

The examples shown after the table provide sample tagging methods for name and address information, using the DITA elements associated with xNAL.

[edit] DITA elements associated with xNAL elements

The set of bookmap elements associated with elements from the [[OASIS extensible Name and Address Language (xNAL)]] standard are listed in the table below.

[edit] Example 1: Tagging personal information in DITA

This example shows a way to tag the following personal name and description.

Mr. Ram V. Kumar Jr. Chief Technologist MSI Business Solutions

<authorinformation>
  <personinfo>

    <namedetails>
      <personname>
        <honorific>Mr.</honorific>
        <firstname>Ram</firstname>
        <middlename>V.</middlename>

        <lastname>Kumar</lastname>
        <generationidentifier>Jr.</generationidentifier>
        <otherinfo>Chief Technologist</otherinfo>
      </personname>

    </namedetails>
  </personinfo>
  <organizationinfo>
    <namedetails>
      <organizationnamedetails>
        <organizationname>MSI Business Solutions</organizationname>

      </organizationnamedetails>
    </namedetails>
  </organizationinfo>
</authorinformation>

[edit] Example 2: Tagging address information in DITA

This example shows a way to tag the following address.

23 Archer St. Chatsworth NSW 2067 Australia

<addressdetails>
  <thoroughfare>123 Archer St.</thoroughfare>

  <locality>
    <localityname>Chatsworth</localityname>
    <postalcode>2067</ppostalcode>
  </locality>
  <administrativearea>NSW</administrativearea>

  <country>Australia</country>
</addressdetails>

[edit] Example 3: Tagging complex name and address information in DITA

This example shows two ways to tag a fairly complex collection of personal, organizational, and address information.

Mr. Samuel L. Johnson Jr.

Chief Technologist c/o XYZ Corporation 52 New Main St. Carrboro, NC 27510 USA email: johnson@example.com phone: 919-555-7987

This method tags all the organizational information as associated with the identified person.

<personinfo>

   <namedetails>
      <personname>
          <firstname>Samuel</firstname>
          <middlename>L.</middlename>
          <lastname>Johnson</lastname>

          <generationidentifier>Jr.</generationidentifier>
          <otherinfo>Chief Technologist</otherinfo>
          <otherinfo>c/o XYZ Corporation </otherinfo>
      </personname>

   </namedetails>
   <addressdetails>
      <thoroughfare>52 New Main St.</thoroughfare>
      <locality>
         <localityname>Carrboro</localityname>

         <postalcode>27510</postalcode>
      </locality>
      <administrativearea>NC</administrativearea>
      <country>USA</country>

   </addressdetails>
   <contactnumbers>
      <contactnumber>919-555-7987</contactnumber>
   </contactnumbers>
   <emailaddresses>

      <emailaddress>johnson@example.com</emailaddress>
   </emailaddresses>
</personinfo>  

The following method separates the person and organization information. It might be used if it were necessary to associate address information with organizations rather than persons.

<authorinformation>

  <personinfo>
    <namedetails>
      <personname>
        <firstname>Samuel</firstname>
        <middlename>L.</middlename>

        <lastname>Johnson</lastname>
        <generationidentifier>Jr.</generationidentifier>
        <otherinfo>Chief Technologist</otherinfo>
      </personname>

    </namedetails>
    <contactnumbers>
      <contactnumber>919-555-7987</contactnumber>
    </contactnumbers>
    <emailaddresses>

      <emailaddress>johnson@example.com</emailaddress>
    </emailaddresses>
  </personinfo>  
  <organizationinfo>
    <namedetails>
      <organizationnamedetails>

        <organizationname>XYZ Corporation</organizationname>
        <otherinfo>c/o </otherinfo>
      </organizationnamedetails>
    </namedetails>
    <addressdetails>

      <thoroughfare>52 New Main St.</thoroughfare>
      <locality>
         <localityname>Carrboro</localityname>
         <postalcode>27510</postalcode>

      </locality>
      <administrativearea>NC</administrativearea>
      <country>USA</country>
    </addressdetails>
  </organizationinfo>

</authorinformation>

TOC: Language Specification 1.1
Parent topic: xNAL domain elements
Next topic: authorinformation