Chapter 8. The Lire Report Configuration Specification Markup Language
Prev | Part III. Developer's Reference | Next

## Chapter 8. The Lire Report Configuration Specification Markup Language

## The Lire Report Configuration Specification Markup Language

Document Type Definition for the Lire Report Configuration Specification Markup Language.

This DTD defines a grammar that is used to specify the configuration parameters used by the Lire framework. Besides the framework parameters, this DTD can be used by extensions writers to register their parameters with the framework. The configuration specifications are usually stored in ``prefix`/share/lire/config-spec`.

Currently, Lire's configuration namespace is flat, which means that two different specification documents cannot define parameters of the same names.

Elements of this DTD uses the http://www.logreport.org/LRCSML/ namespace that is usually mapped to the `lrcsml` prefix.

The latest version of that DTD is 1.1 and its public identifier is -//LogReport.ORG//DTD Lire Report Specification Markup Language V1.1//EN™. Its canonical system identifier is http://www.logreport.org/LRCSML/1.1/lrcsml.dtd.

    <!--
                                                                       -->

    <!--                    Namespace prefix for validation using the
                            DTD                                        -->
    <!ENTITY % LRCSML.xmlns.pfx    "lrcsml"                                >
    <!ENTITY % LRCSML.pfx          "%LRCSML.xmlns.pfx;:"                   >
    <!ENTITY % LRCSML.xmlns.attr.name "xmlns:%LRCSML.xmlns.pfx;"           >
    <!ENTITY % LRCSML.xmlns.attr
      "%LRCSML.xmlns.attr.name; CDATA #FIXED 'http://www.logreport.org/LRCSML/'">

    <!ENTITY % LRCML.xmlns.pfx    "lrcml"                                 >
    <!ENTITY % LRCML.pfx          "%LRCML.xmlns.pfx;:"                    >
    <!ENTITY % LRCML.xmlns.attr.name "xmlns:%LRCML.xmlns.pfx;">
    <!ENTITY % LRCML.xmlns.attr
      "%LRCML.xmlns.attr.name; CDATA #FIXED 'http://www.logreport.org/LRCML/'">

    <!-- For the modules which we are including                         -->
    <!ENTITY % LIRE.pfx           "%LRCSML.pfx;"                          >

This DTD uses the common lire-desc.mod module which is used to include a subset of DocBook in description and text elements.

    <!ENTITY % lire-desc.mod PUBLIC
        "-//LogReport.ORG//ELEMENTS Lire Description Elements V2.0//EN"
        "lire-desc.mod">
    %lire-desc.mod;

Each configuration specification is a XML document which has one `config-spec` as its root element.

    <!ENTITY % LRCSML.config-spec     "%LRCSML.pfx;config-spec"              >
    <!ENTITY % LRCSML.summary         "%LRCSML.pfx;summary"                  >
    <!ENTITY % LRCSML.boolean         "%LRCSML.pfx;boolean"                  >
    <!ENTITY % LRCSML.integer         "%LRCSML.pfx;integer"                  >
    <!ENTITY % LRCSML.string          "%LRCSML.pfx;string"                   >
    <!ENTITY % LRCSML.dlf-schema      "%LRCSML.pfx;dlf-schema"               >
    <!ENTITY % LRCSML.dlf-streams     "%LRCSML.pfx;dlf-streams"              >
    <!ENTITY % LRCSML.dlf-converter   "%LRCSML.pfx;dlf-converter"            >
    <!ENTITY % LRCSML.command         "%LRCSML.pfx;command"                  >
    <!ENTITY % LRCSML.file            "%LRCSML.pfx;file"                     >
    <!ENTITY % LRCSML.executable      "%LRCSML.pfx;executable"               >
    <!ENTITY % LRCSML.directory       "%LRCSML.pfx;directory"                >
    <!ENTITY % LRCSML.select          "%LRCSML.pfx;select"                   >
    <!ENTITY % LRCSML.option          "%LRCSML.pfx;option"                   >
    <!ENTITY % LRCSML.list            "%LRCSML.pfx;list"                     >
    <!ENTITY % LRCSML.object          "%LRCSML.pfx;object"                   >
    <!ENTITY % LRCSML.output-format   "%LRCSML.pfx;output-format"            >
    <!ENTITY % LRCSML.plugin          "%LRCSML.pfx;plugin"                   >
    <!ENTITY % LRCSML.record          "%LRCSML.pfx;record"                   >
    <!ENTITY % LRCSML.reference       "%LRCSML.pfx;reference"                >
    <!ENTITY % LRCSML.report-config   "%LRCSML.pfx;report-config"            >

    <!ENTITY % LRCML.param            "%LRCML.pfx;param"                     >

    <!ENTITY % LRCSML.summary         "%LRCSML.pfx;summary"                  >
    <!ENTITY % types-spec           "%LRCSML.boolean;|%LRCSML.integer;|
                                     %LRCSML.string;|%LRCSML.dlf-schema;|
                                     %LRCSML.dlf-converter;|%LRCSML.dlf-streams;|
                                     %LRCSML.command;|%LRCSML.file;|
                                     %LRCSML.executable;|%LRCSML.directory;|
                                     %LRCSML.select;|%LRCSML.list;|%LRCSML.object;|
                                     %LRCSML.output-format;|
                                     %LRCSML.plugin;|%LRCSML.record;|%LRCSML.reference;
                                     |%LRCSML.report-config;
                                    ">
    <!ENTITY % common.mix           "(%LRCSML.summary;)?,(%LIRE.description;)?">
    <!ENTITY % default              "(%LRCML.param;)?"                  >
    <!ENTITY % common.mix.default   "(%common.mix;, %default;)"         >

    <!ELEMENT %LRCML.param; (#PCDATA|%LRCML.param;)*                       >
    <!ATTLIST %LRCML.param;
                 name      NMTOKEN                             #REQUIRED
                 value     CDATA                               #IMPLIED >

### `config-spec` element

Root element of a configuration specification document. It contains a list of parameter specifications..

This element doesn't have any attributes.

    <!ELEMENT %LRCSML.config-spec; ((%types-spec;)+)                       >
    <!ATTLIST %LRCSML.config-spec;
                 %LRCSML.xmlns.attr;
                 %LRCML.xmlns.attr;                                         >

### `summary` element

This element is used for a short one description of the parameter's purpose. Use the `description` element for longer help text.

This element doesn't have any attribute.

    <!ELEMENT %LRCSML.summary;    (#PCDATA)                                >

### Parameter Specifiations Elements

#### Common Attributes

These attributes are common to all parameters specification elements:

name

  Contains the name of the parameter to which this specification apply.

required

  Determines if a valid value is required to make the container validates. Defaults to true.

section

  This attribute can be used to set a menu section which can be used by configuration frontends to group parameters together.

summary

  This attribute is equivalent to the `summary` element.

obsolete

  This attribute can be used to mark a parameter as obsolete. Obsolete parameters will be removed from the specification in a future Lire release.

    <!ENTITY % common.attr "
            name     NMTOKEN                                   #REQUIRED
            required NMTOKEN                                   '1'
            section  CDATA                                     #IMPLIED
            summary  CDATA                                     #IMPLIED
            obsolete NMTOKEN                                   '0'">

#### `boolean` element

This element is used to define a boolean parameter which can takes a `yes` or `no` value.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.boolean; (%common.mix.default;)                    >
    <!ATTLIST %LRCSML.boolean;
     %common.attr;
                                                                         >

#### `integer` element

This element is used to define an integer parameter.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.integer; (%common.mix.default;)                    >
    <!ATTLIST %LRCSML.integer;
     %common.attr;
                                                                         >

#### `string` element

This element is used to define an string parameter. These parameters can contains any value.

This can have a `valid-re` attribute which specify a regular expression that the value must match.

    <!ELEMENT %LRCSML.string; (%common.mix.default;)                    >
    <!ATTLIST %LRCSML.string;
     %common.attr;
     valid-re CDATA                                         #IMPLIED
                                                                         >

#### `dlf-converter` element

This element is used to select a registered DlfConverter.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.dlf-converter; (%common.mix.default;)              >
    <!ATTLIST %LRCSML.dlf-converter;
     %common.attr;
                                                                         >

#### `dlf-schema` element

This element is used to select an available DlfSchema.

If this element has the `superservices` set, only superservices can be selected.

    <!ELEMENT %LRCSML.dlf-schema; (%common.mix.default;)                 >
    <!ATTLIST %LRCSML.dlf-schema;
     %common.attr;
     superservices NMTOKEN                                            '0'
                                                                         >

#### `dlf-streams` element

This element is used to configure Lire::DlfStream in Lire::DlfStore.

This element has no attribute.

    <!ELEMENT %LRCSML.dlf-streams; (%common.mix.default;)                >
    <!ATTLIST %LRCSML.dlf-streams;
     %common.attr;
                                                                         >

#### `command` element

This element is used to define a command parameter. To be accepted as valid the parameter's value must point to an executable file or an executable file with the specified value must exist in a directory of the PATH environment variable.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.command; (%common.mix.default;)                    >
    <!ATTLIST %LRCSML.command;
     %common.attr;
                                                                         >

#### `file` element

This element is used to define a file parameter. To be accepted as valid, the parameter's value must point to an existing file.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.file; (%common.mix.default;)                       >
    <!ATTLIST %LRCSML.file;
     %common.attr;
                                                                         >

#### `directory` element

This element is used to define a directory parameter. To be accepted as valid, the parameter's value must point to an existing directory.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.directory; (%common.mix.default;)                  >
    <!ATTLIST %LRCSML.directory;
     %common.attr;
                                                                         >

#### `executable` element

This element is used to define an executable parameter. To be accepted as valid, the parameter's value must point to an existing executable file.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.executable; (%common.mix.default;)                 >
    <!ATTLIST %LRCSML.executable;
     %common.attr;
                                                                         >

#### `select` element

This element is used to define a parameter for which the value is selected among a set of options. The allowed set of options is specified using `option` elements.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.select;     (%common.mix;,(%LRCSML.option;)+, %default;) >
    <!ATTLIST %LRCSML.select;
     %common.attr;
                                                                         >

#### `option` element

This element is used to define the valid values for a `select` parameter.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.option;     (%common.mix;)                           >
    <!ATTLIST %LRCSML.option;
     %common.attr;
                                                                         >

#### `list` element

This element is used to define a parameter that can contains an ordered set of values. The type of values which can be contained is specified using other parameters elements. Any number of parameters of the type specified by the children elements can be contained by the defined parameter.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.list;       (%common.mix;,(%types-spec;)+,%default;) >
    <!ATTLIST %LRCSML.list;
     %common.attr;
                                                                         >

#### `object` element

This element is used to define a parameter that will instantiate an object. The object will be instantiated by calling the "new_from_config()" class method defined in the package specified by the element's `class` attribute. The constructor will receive the hash instantiated from the parameter's components as parameter.

The `label` attribute can be used to specify the contained element that should be used to represent this object in lists.

    <!ELEMENT %LRCSML.object;       (%common.mix;,(%types-spec;)+,%default;) >
    <!ATTLIST %LRCSML.object;
     %common.attr;
            class    NMTOKEN                                    #REQUIRED
            label    NMTOKEN                                    #IMPLIED
                                                                         >

#### `output-format` element

This element is used to select an available OutputFormat.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.output-format; (%common.mix.default;)              >
    <!ATTLIST %LRCSML.output-format;
     %common.attr;
                                                                         >

#### `record` element

This element is used to define a parameter that holds record-like data.

The `label` attribute can be used to specify the contained element that should be used to represent this record in lists.

    <!ELEMENT %LRCSML.record;       (%common.mix;,(%types-spec;)+, %default;) >
    <!ATTLIST %LRCSML.record;
     %common.attr;
            label    NMTOKEN                                    #IMPLIED
                                                                         >

#### `record` element

This element is used to define a parameter that holds record-like data.

The `label` attribute can be used to specify the contained element that should be used to represent this record in lists.

    <!ELEMENT %LRCSML.record;       (%common.mix;,(%types-spec;)+,%default;) >
    <!ATTLIST %LRCSML.record;
     %common.attr;
            label    NMTOKEN                                    #IMPLIED
                                                                         >

#### `reference` element

This element is used to select from an index. The index in which the available values is taken is specified in the `index` attribute.

    <!ELEMENT %LRCSML.reference; (%common.mix.default;)                   >
    <!ATTLIST %LRCSML.reference;
     %common.attr;
     index  CDATA                                             #REQUIRED
                                                                         >

#### `report-config` element

This element is used to configure a report configuration.

This element doesn't have any attribute. Each superservice can define a default report configuration using this element with a name of ``superservice`_default`.

    <!ELEMENT %LRCSML.report-config; (%common.mix.default;)              >
    <!ATTLIST %LRCSML.report-config;
     %common.attr;
                                                                         >

#### `plugin` element

This element is used to define a parameter for which the value is selected among a set of options. The allowed set of options is specified using `option` elements. The element will also contain additional parameters based on the selected value. The available paramaters should be defined in a `record` or similar specification named ``name`_properties`. For example, the additional parameters when the `option_1` option is selected will be found in the specification named `option_1_properties`.

This element doesn't have any specific attributes.

    <!ELEMENT %LRCSML.plugin;     (%common.mix;,(%LRCSML.option;)+, %default;) >
    <!ATTLIST %LRCSML.plugin;
     %common.attr;
                                                                         >

Prev | Up | Next
Chapter 7. Common Textual Elements to All XML Formats | Home | Chapter 9. The Lire Report Configuration Markup Language