<?xml version="1.0" encoding="US-ASCII"?>
<!-- $Id: lire.dtd,v 1.12 2002/07/16 20:48:25 flacoste Exp $ -->

<!--

Copyright (C) 2000-2001 Stichting LogReport Foundation LogReport@LogReport.org
 
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
     
You should have received a copy of the GNU General Public License
along with this program (see COPYING); if not, check with
http://www.gnu.org/copyleft/gpl.html or write to the Free Software 
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.

-->

<!--                    
    Document Type Definition for the XML Lire Report Markup Language 
    as generated by lr_dlf2xml(1)

    Please use the following formal public identifier to identify it:

    "-//LogReport.ORG//DTD Lire Report Markup Language V1.0//EN"

    This DTD defines a grammar that is used by reports generated
    by Lire.

    NameSpace:

    Elements of this DTD are defined in the namespace
    http://www.logreport.org/LRML/

    The official URL for this DTD is 
    http://www.logreport.org/LRML/1.0/lire.dtd

    XML documents should reference this DTD by using

    DOCTYPE PUBLIC
   "-//LogReport.ORG//DTD Lire Report Markup Language V1.0//EN"
   "http://www.logreport.org/LRML/1.0/lire.dtd"
                                                                   -->

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

<!-- 
    Include needed modules
                                                                   -->
<!ENTITY % lire-types.mod PUBLIC
    "-//LogReport.ORG//ENTITIES Lire Data Types V1.0//EN"
    "lire-types.mod">
%lire-types.mod;

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

<!--                    Parameter entities which defines qualified
                        names of the elements                      -->
<!ENTITY % LIRE.report          "%LIRE.pfx;report"                   >
<!ENTITY % LIRE.section         "%LIRE.pfx;section"                  >
<!ENTITY % LIRE.subreport       "%LIRE.pfx;subreport"                >
<!ENTITY % LIRE.missing-subreport "%LIRE.pfx;missing-subreport"      >
<!ENTITY % LIRE.table           "%LIRE.pfx;table"                    >
<!ENTITY % LIRE.entry           "%LIRE.pfx;entry"                    >
<!ENTITY % LIRE.group           "%LIRE.pfx;group"                    >
<!ENTITY % LIRE.name            "%LIRE.pfx;name"                     >
<!ENTITY % LIRE.value           "%LIRE.pfx;value"                    >
<!ENTITY % LIRE.image           "%LIRE.pfx;image"                    >
<!ENTITY % LIRE.file            "%LIRE.pfx;file"                     >
<!ENTITY % LIRE.date            "%LIRE.pfx;date"                     >
<!ENTITY % LIRE.timespan        "%LIRE.pfx;timespan"                 >
<!ENTITY % LIRE.hostname        "%LIRE.pfx;hostname"                 >

<!-- ========================= Parameter entities ================ -->

<!--                    Meta-information content mix               -->
<!ENTITY % meta-infos.mix
                       "%LIRE.title;?, %LIRE.date;?, %LIRE.timespan;?, 
                        %LIRE.hostname;?, %LIRE.description;?"       >

<!-- ========================= Top level element ================= -->
<!--
    The top-level element of LogReport's report is "report".

    A report starts with the report's meta-informations: 
    title, timespan, hostname and description.

    The report's actual data is contained in one or more subreports.

    Attributes of report:

        version:    The version of the DTD to which this report 
                    complies. Only version 1.0 is defined.
        superservice: If set contains the superservice used by all 
                      subreports.

                                                                   -->
<!ELEMENT %LIRE.report;      (%meta-infos.mix;, (%LIRE.section;)+)   >
<!ATTLIST %LIRE.report; 
             version         %number.type;                 #REQUIRED
             superservice    %superservice.type;           #IMPLIED
             %LIRE.xmlns.attr;                                       >


<!-- ================== Meta-informations elements =============== -->

<!--
    The date element contains the date on which the report or
    subreport was generated. 

    The content of this element should be the timestamp in a format
    suitable for display.

    Attributes of timespan:

        time:       The date in epoch time.
                                                                   -->
<!ELEMENT %LIRE.date;    (#PCDATA)                                   >
<!ATTLIST %LIRE.date;
             time        %number.type;                      #REQUIRED>

<!--
    The timespan element contains the starting and ending date
    which delimits the period of the report or subreport.

    The content of this element should be formatted for display
    purpose. The starting and ending time of the timespan can be read
    in epoch time in the attributes.
    
    Attributes of timespan:

        start:      The start time of the timespan in epoch time.
        end:        The end time of the timespan in epoch time.
                                                                   -->
<!ELEMENT %LIRE.timespan;    (#PCDATA)                               >
<!ATTLIST %LIRE.timespan;
             start         %number.type;                    #REQUIRED
             end           %number.type;                    #REQUIRED>

<!--
    The hostname element contains the hostname for which the report
    or subreport was generated.

    It doesn't have any attributes.
                                                                   -->
<!ELEMENT %LIRE.hostname;    (#PCDATA)                               >

<!-- ================== Data elements ============================ -->

<!--
    The section element group common subreports together. The
    section's description will usually contains informations about the
    filters that were applied in this section.

    It contains a title, a description if some global filters were
    applied and the section's subrepoirts.

    This element doesn't have any attribute.
                                                                   -->
                      
<!ELEMENT %LIRE.section;      (%LIRE.title;, (%LIRE.description;)?, 
                               (%LIRE.subreport;)*)                  >

<!--
    The subreport element contains data for a certain report.

    It can contains meta-information elements, it they are different
    from the one of the report.

    Example of subreport for the email superservice are :

        * Message delay by relay in seconds.
        * Per hour traffic summary.
        * Top 10 messages delivery.
        * etc.

    The data is contains in a table element.

    If a chart was generated for the table data, its information
    are contained in an image element.

    Attributes of subreport:

        superservice: the name of the superservice from which the
                      report's data comes from : i.e. email, www, dns, 
                      etc.
        type:         This is the name of the report specification 
                      that was used to generated this subreport.
        flags:        A space delimited list of flags. The only currently
                      defined flags is 'merged' to signal that the
                      this subreport comes from merged data.
                                                                   -->
                      
<!ELEMENT %LIRE.subreport;    (%meta-infos.mix;, %LIRE.table;, 
                               (%LIRE.image;)?)                      >
<!ATTLIST %LIRE.subreport;
             superservice   %superservice.type;             #REQUIRED
             type           CDATA                           #REQUIRED
             flags          NMTOKENS                        #IMPLIED >

<!--
    The subreport element contains data for a certain report.

    It can contains meta-information elements, it they are different
    from the one of the report.

    Example of subreport for the email superservice are :

        * Message delay by relay in seconds.
        * Per hour traffic summary.
        * Top 10 messages delivery.
        * etc.

    The data is contains in a table element.

    If a chart was generated for the table data, its information
    are contained in an image element.

    Attributes of subreport:

        superservice: the name of the superservice from which the
                      report's data comes from : i.e. email, www, dns, 
                      etc.
        type:         This is the name of the report specification 
                      that was used to generated this subreport.
        reason:       A reason why this subreport is missing.
                                                                   -->
                      
<!ELEMENT %LIRE.missing-subreport; (EMPTY)                           >
<!ATTLIST %LIRE.missing-subreport;
             superservice   %superservice.type;            #REQUIRED
             reason         CDATA                          #IMPLIED
             type           CDATA                          #REQUIRED >

<!--
    The table element group the data of the subreport.

    A table element can contains the subreport data directly or
    the data can be subdivided in group.

    An example of a subreport which would contains directly the
    data would be "messages per to-domain, top-10". This would contains
    ten entries, one for each to-domain.

    An example of a subreport which would contains data in group would
    be "deliveries to users, per to-domain, top 30, top 5 users". It 
    would contain 30 groups (one per to-domain) and each group would
    contain 5 entries (one per user).

    Group can be nested to arbitrary depth (but logic don't recommend 
    to nest too much).

    FIXME: Shouldn't we have meta-infos attributes to describe
           the type of the name and value elements used ? Example:
           string, number, money, time, seconds, bytes, etc.
        
    Attributes of table:
        
        charttype:    being the type of chart which can be generated 
                      from the data is this table
        show:         the number of entry to display. By default all
                      entries should be displayed.
                                                                   -->
<!ELEMENT %LIRE.table;        ((%LIRE.entry;)*)                      >
<!ATTLIST %LIRE.table;
             charttype    (%chart.type;)                    #IMPLIED
             show         %int.type;                        #IMPLIED >

<!--
    Entry contains the atomic data from the report. It is similar
    to a key-value pair.

    The name elements contains the "key" portion of the pair:
    the user name, the email, the browser type, the url, the time,
    etc.)

    The value element contains usually the numeric portion of the
    pair: message count, bytes transferred, average delay, etc.

    The entry element has no attributes.
                                                                   -->
<!ELEMENT %LIRE.entry;        ((%LIRE.name;)+, (%LIRE.value;)*, 
                               (%LIRE.group;)*)                      >

<!--
    The name elements contains the discrete part of the entry in a
    format suitable for display.

    Attributes of name:
        
        value:      When the displayed format is different from the DLF
                    representation, this attribute contains the DLF
                    representation.
        range:      In some cases (like in report generated by the 
                    timegroup, timeslot or rangegroup specification),
                    this attribute will contains the range's length
                    from the starting value which is in the 'value' 
                    attribute.
                                                                   -->
<!ELEMENT %LIRE.name;         (#PCDATA)                              >
<!ATTLIST %LIRE.name;
             value            CDATA                         #IMPLIED
             range            %number.type;                 #IMPLIED >

<!--
    The value element contains the continuous numeric portion 
    of the data pair.

    Attributes of value:
        
        value:    contains the value in numeric format. This is used
                  when the value was scaled (1k, 5M, etc.)
        total:    for average value, this contains the total used to 
                  compute the average.
        n:        for average value, this contains the n value that was 
                  used to compute the average.
                                                                   -->
<!ELEMENT %LIRE.value;        (#PCDATA)                              >
<!ATTLIST %LIRE.value;
             value       %number.type;                      #IMPLIED 
             total       %number.type;                      #IMPLIED 
             n           %number.type;                      #IMPLIED >
<!--
    Group element can be used to subdivide logically a report. It's
    used for aggregate reports like message per user per domain.

    Groups can be nested more than once, but too much nesting augments
    information clutter and isn't useful for the user.

    Attributes of group:

        show:         the number of entry to display. By default all
                      entries should be displayed.
                                                                   -->
<!ELEMENT %LIRE.group;        (%LIRE.entry;)+                        >
<!ATTLIST %LIRE.group;
             show         %int.type;                        #IMPLIED >

<!-- ================== Chart elements =========================== -->
<!--
    The image element contains information about a chart which
    was generated from the table data of the subreport.

    It can contains a title which should be displayed for the chart.
    
    The name of the generated file is contained in the file element.

    The image element doesn't have any attributes.
                                                                   -->
<!ELEMENT %LIRE.image;        ((%LIRE.title;)?, %LIRE.file;)         >

<!--
    The file element contains the name of the file which contains
    the chart's image.

    Attributes of file:
        format:   Contains the file type.
                                                                   -->
<!ELEMENT %LIRE.file;         (#PCDATA)                              >
<!ATTLIST %LIRE.file; 
             format       CDATA                            #REQUIRED >



