<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
  <header>
    <title>The Barcode XML format</title>
  </header>
  <body>
    <section>
      <title>Introduction</title>
      <p>
        This page describes the XML format used by <strong>Barcode4J</strong> to define barcodes. 
        It also contains notes about the message format supported by each symbology.
      </p>
    </section>
    <section>
      <title>General structure</title>
      <p>
        The general structure of the Barcode XML format looks like this:
      </p>
      <source>&#60;barcode message="123456789"&#62;
    &#60;{type}&#62;
      {barcode-specific configuration}
    &#60;/{type}&#62;
&#60;/barcode&#62;</source>
      <p>
        Replace <strong>{type}</strong> with the name of the barcode type, ex. "ean13" or "code39". You can also use the 
        fully qualified classname of the implementing class, ex. "org.krysalis.barcode4j.impl.Code39". If 
        you use a name it will be resolved internally using the <code>BarcodeClassResolver</code> interface.
      </p>
      <section>
        <title>General structure in XSLT Stylesheet</title>
        <p>
          When implementing with <link href="xalan-ext.html">Usage with Xalan-J</link>, <link href="saxon-ext.html">Usage with SAXON</link>, or <link href="fop-ext.html">Usage with FOP</link>, the general structure of the Barcode XML format changes slightly, to include the barcode namespace. For example, when using Barcode 4J with FOP, it looks like this:
        </p>
	  <source>&#60;barcode:barcode
    xmlns:barcode="http://barcode4j.krysalis.org/ns"
    message="123456789"&#62;
  &#60;barcode:{type}&#62;
    {barcode-specific configuration}
  &#60;/barcode:{type}&#62;
&#60;/barcode:barcode&#62;</source>
      </section>
      <p>
        The barcode-specific configuration is a set of elements and attributes defined by the barcode implementation
        itself. Please see further down for specifics. But here's an example:
      </p>
      <source>&#60;barcode&#62;
  &#60;intl2of5&#62;
    &#60;height&#62;10mm&#60;/height&#62;
    &#60;wide-factor&#62;2.5&#60;/wide-factor&#62;
  &#60;/intl2of5&#62;
&#60;/barcode&#62;</source>
      <note>
      	In the examples below, the sample code <code>&#60;height&#62;{length}&#60;/height&#62;</code> would be changed to
		<code>&#60;height&#62;10mm&#60;/height&#62;</code> (replacing everything between the "{" and "}"
		<strong>including the "{" and "}" marks</strong>), as is shown in the example code fragment below.
      </note>
    </section>
    <section>
      <title>Datatypes</title>
      <p>
        The values for the configuration elements are of various datatypes:
      </p>
      <ul>
        <li id="boolean">{boolean}: The values <code>true</code>|<code>yes</code>|<code>on</code> or <code>false</code>|<code>no</code>|<code>off</code>.</li>
        <li id="string">{string}: A simple unicode string of text like "<code>Hello123</code>".</li>
        <li id="char">{char}: A unicode character.</li>
        <li id="number">{number}: A number such as "2.43" or "5".</li>
        <li id="unit">{unit}: length unit, one of <code>mm</code>, <code>cm</code>, or <code>pt</code>.
          <ul>
            <li>The default unit is normally "mm" (Millimeters) but is implementation-dependent.</li>
            <li>A special unit supported in certain places is "mw" (module width). This is used in 
              certain 1D barcode to specify values like "10 times the module width", ex. for the quiet zone.
            </li>
          </ul>
        </li>
        <li id="length">{length}: A length in the form "{<link href="#number">number</link>}[[ ]{<link href="#unit">unit</link>}]". Examples: <code>1.2mm</code>, <code>5.0</code>, <code>3</code>, or <code>10mw</code>.</li>
        <li id="checksum-mode">{checksum-mode}: The checksum mode determines the behaviour for checksums. Possible values (not 
        	all values are supported by all barcode formats):
          <ul>
            <li>add: the checksum is automatically added to the message.</li>
            <li>check: the checksum is checked while rendering the barcode.</li>
            <li>ignore: no checksum processing is done.</li>
            <li>auto: Enables the barcode type's default behaviour.</li>
          </ul>
        </li>
        <li id="human-readable-placement">{human-readable-placement}: This enumeration determines the placement of the human-readable part 
        	of a barcode. Possible values:
          <ul>
            <li>bottom: the message is placed at the bottom of the symbol.</li>
            <li>top: the message is placed at the top of the symbol.</li>
            <li>none: no human-readable part is generated.</li>
          </ul>
        </li>
        <li id="baseline-alignment">{baseline-alignment}: This enumeration determines the alignment of the lines of barcodes such as
         POSTNET.
          <ul>
            <li>bottom: Short and long lines are aligned at the bottom.</li>
            <li>top: Short and long lines are aligned at the top.</li>
          </ul>
        </li>
        <li id="font-name">{font-name}: As the name says, a font name used in outputting <code>&#60;font-name/&#62;</code>. Note that not all fonts are available for all output formats.</li>
        <li id="shape">{shape}: This enumeration determines the choice of symbol settings for 
          DataMatrix barcodes.
          <ul>
            <li>force-none: Both square and rectangular symbols are allowed.</li>
            <li>force-square: Force the use of square symbols.</li>
            <li>force-rectangle: Force the use of rectangular symbols.</li>
          </ul>
        </li>
        <li id="dimension">
          {dimension}: Specifies a dimension (in pixels/units) in x- and y-direction.
          Example: "12x8" defines a size of 12 units horizontally and 8 units vertically. If
          you specify just one number, it is used for both directions,
          i.e. "12" is the same as "12x12".
        </li>
      </ul>
      <p>
        Datatypes below are often given in the format "{<link href="#length">length</link>:15mm}". The value after the datatype indicates 
        the default value.
      </p>
      <note>
      	If the datatype specifies a default value (as in <code>{length:15mm}</code> above), this means that the whole element is optional. In this case, the default <code>15mm</code> would be applied.
      </note>
    </section>
    <section>
      <title>Barcode XML Format: Abbreviated version</title>
      <p>
        The Barcode XML format can be "abbreviated" (thereby accepting all default values) as in this Code 39 example:
      </p>
      <source>&#60;barcode message="123456789"&#62;
  &#60;<link href="symbol-code39.html">code39</link>/&#62;
&#60;/barcode&#62;</source>
      <p>
        In this case, the defaults are assumed, and the result is effectively:
      </p>
      <source>&#60;barcode message="<link href="#string">123456789</link>"&#62;
  &#60;<link href="symbol-code39.html">code39</link>&#62;
    &#60;height&#62;<link href="#length">15mm</link>&#60;/height&#62;
    &#60;module-width&#62;<link href="#length">0.19mm</link>&#60;/module-width&#62;
    &#60;wide-factor&#62;<link href="#number">2.5</link>&#60;/wide-factor&#62;
    &#60;interchar-gap-width&#62;<link href="#length">1mw</link>&#60;/interchar-gap-width&#62;
    &#60;quiet-zone enabled="<link href="#boolean">true</link>"&#62;<link href="#length">10mw</link>&#60;/quiet-zone&#62;
    &#60;checksum&#62;<link href="#checksum-mode">auto</link>&#60;/checksum&#62;
    &#60;human-readable&#62;
      &#60;placement&#62;<link href="#human-readable-placement">bottom</link>&#60;/placement&#62;
      &#60;font-name&#62;<link href="#font-name">Helvetica</link>&#60;/font-name&#62;
      &#60;font-size&#62;<link href="#length">8pt</link>&#60;/font-size&#62;
      &#60;pattern&#62;<link href="#string">{string}</link>&#60;/pattern&#62; &#60;!-- see <link href="#pattern">below</link> for details --&#62;
      &#60;display-start-stop&#62;<link href="#boolean">false</link>&#60;/display-start-stop&#62;
      &#60;display-checksum&#62;<link href="#boolean">false</link>&#60;/display-checksum&#62;
    &#60;/human-readable&#62;
  &#60;/<link href="symbol-code39.html">code39</link>&#62;
&#60;/barcode&#62;</source>
    </section>
    <section id="pattern">
      <title> Human-readable message pattern </title>
      <p>
        General 1D symbologies have no inner structure. That's why they are used where custom 
        messages should be encoded - most often some very big numbers with a lot of digits.
        These are very hard to read if there is no grouping. Or you can have a date and time 
        encoded as contiguous set of digits. In order to make it easy for people to read complicated 
        long messages a pattern is required. There is a facility to add custom patterns to a 
        human-readable message. However, it only applies to Interleaves 2 of 5, Code 39, 
        Code 128 and Codabar. Other symbologies either have no human-readable part or require
        special formatting of the message (like UPC/EAN).
      </p>
      <source>
&#60;human-readable&#62;
  &#60;pattern&#62;<link href="#string">{string}</link>&#60;/pattern&#62;
&#60;/human-readable&#62;</source>
      <p>
        In the pattern the underscore "_" is used as placeholder for the next message character. 
        The other characters within the pattern are inserted between the message symbols. The 
        backslash "\" is escape symbol. Combination of '\?' will include '?' in the 
        human-readable message, where '?' can be any character including underscore '_' and 
        backslash '\'. '#' can be used to skip (delete) a character from the original message.
      </p>
      <p>
        <strong>Examples:</strong>
      </p>
      <table>
       <tr>
         <td><strong>Barcode message</strong></td>
         <td><br/><code>1234567890</code><br/>&#160;</td>
         <td><br/><code>01012001103854</code><br/>&#160;</td>
         <td><br/><code>1234567890</code><br/>&#160;</td>
         <td><br/><code>2008-11-28</code><br/>&#160;</td>
       </tr>
       <tr>
         <td><strong>Human-readable pattern</strong></td>
         <td><br/><code>____ ____ __</code><br/>&#160;</td>
         <td><br/><code>__/__/____ __:__:__ UTC</code><br/>&#160;</td>
         <td><br/><code>____\\___\____</code><br/>&#160;</td>
         <td><br/><code>____#/__#/__</code><br/>&#160;</td>
       </tr>
       <tr>
         <td><strong>Human-readable message</strong></td>
         <td><br/><code>1234 5678 90</code><br/>&#160;</td>
         <td><br/><code>01/01/2001 10:38:54 UTC</code><br/>&#160;</td>
         <td><br/><code>1234\567_890</code><br/>&#160;</td>
         <td><br/><code>2008/11/28</code><br/>&#160;</td>
       </tr>
      </table>
    </section>
    <section id="supported">
      <title>Configuration details for all supported symbologies</title>
      <ul>
        <li>General 1D symbologies:
          <ul>
            <li><link href="symbol-interleaved2of5.html">Interleaved 2 of 5</link></li>
            <li><link href="symbol-codabar.html">Codabar</link></li>
            <li><link href="symbol-code39.html">Code 39</link></li>
            <li><link href="symbol-code128.html">Code 128</link></li>
          </ul>
        </li>
        <li>UPC/EAN group:
          <ul>
            <li><link href="symbol-upc-a.html">UPC-A</link></li>
            <li><link href="symbol-upc-e.html">UPC-E</link></li>
            <li><link href="symbol-ean-13.html">EAN-13</link></li>
            <li><link href="symbol-ean-8.html">EAN-8</link></li>
            <li><link href="symbol-ean-128.html">EAN-128</link></li>
          </ul>
        </li>
        <li>Postal symbologies:
          <ul>
            <li><link href="symbol-postnet.html">POSTNET</link></li>
            <li><link href="symbol-royal-mail-cbc.html">Royal Mail Customer Barcode (4-State)</link></li>
            <li><link href="symbol-usps4cb.html">USPS Intelligent Mail (4-State Customer Barcode)</link></li>
          </ul>
        </li>
        <li>2D symbologies:
          <ul>
            <li><link href="symbol-pdf417.html">PDF417</link></li>
            <li><link href="symbol-datamatrix.html">DataMatrix</link></li>
          </ul>
        </li>
      </ul>
    </section>
  </body>
</document>

