[Savannah-hackers] submission of Error Description and Diagnostic Suite - savannah.gnu.org

[pete]

A package was submitted to savannah.gnu.org
This mail was sent to address@hidden, address@hidden


Pete Rowley <address@hidden> described the package as follows:
License: other
Other License: Due to the nature of the project I wish to use several GNU 
licenses.

The utility will use the GNU Genral Public License V2
The shared library will use the GNU Lesser General Public License
The xml translation documents will either use the GNU Free Documentation 
License or the GNU General Public License - I must confess I am unsure which is 
the best choice
Package: Error Description and Diagnostic Suite
System name: libeddml
Type: GNU

Description:
In 1995 I started work on an error diagnostic utility called Error Buddy for 
the windows platform.  It is still widely distributed ( 
http://www.winsite.com/bin/Info?500000002376 ) and comes with a simple license 
for free use for any purpose, but does not have source code available.

The project that I propose to begin is the result of my experience with Error 
Buddy.  I had hoped that the original project would be successful in getting 
error translation contributions from other developers, but while it appears 
popular for use, I have had little success on the contribution side - largely I 
think due to the requirement that the translation engines be coded as a dll, 
but I am sure the "free" status of the project did not help.  This I plan to 
change by 1) creating a fully free software project, 2) creating a text based 
translation format 3) provide a means to leverage these in other applications.

In a sense, this project could be described as a super-grep of header files - 
this is often the way that developers look up error codes when they are not 
sure of their origin.  This in itself is a useful function, however the goals 
of the project are much larger.

The main goals of the project are:

a) to create a standard xml format for the description of error codes and 
additional information that could be useful for resolution of error conditions, 
including such things as causes with suggested resolutions, notes on the error 
condition, and other useful information

b) to provide a command line utility which allows queries based on error codes 
and to provide information about those error codes using files created in the 
xml format described in a).  The audience being end users, developers, system 
admninistrators and anyone who has a need to know what an error code means and 
what to do about it.

c) to provide a shared library which may be used by applications to take 
advantage of the extended information available about error codes in the xml 
format, and to lessen the burden of presenting and maintaining error condition 
information to end users

d) to promote the use of the library in c), and of course the creation of error 
translation files in format a)

The initial platform is to be GNU/Linux, with other platforms to follow - it is 
intended that this be a widely adopted standard for the description of errors, 
and so supporting as many platforms as is feasible is highly desired.

This project does not currently have source code.  Actually the major work in 
this project is the creation of error translation documents.  I do have an 
initial DTD for the error file format which I call EDDML (Error Description and 
Diagnostic Markup Language) and also a proof of concept translation for LDAP 
(chosen largely because I was a senior software engineer working on the 
Netscape/IPlanet/Sun directory server for 6 years and I know a thing or two 
about the subject).  They follow:

The DTD:

<?xml encoding="UTF-8"?>
<!--
************************************************************
eddml.dtd: Error Description and Diagnostic Markup Language
for marking up error descriptions.
Copyright 2004 Pete Rowley
************************************************************
-->

<!ELEMENT eddml (updates?, support?, link*, errorset+)>
<!ATTLIST eddml
        title CDATA #IMPLIED
        vendor CDATA #IMPLIED
        product CDATA #IMPLIED
        language CDATA "en"
        revision CDATA #IMPLIED
        copyright CDATA #IMPLIED
        authors CDATA #IMPLIED
        contact CDATA #IMPLIED>

<!ELEMENT link (#PCDATA)>
<!ATTLIST link
        xmlns:xlink CDATA #FIXED "http://www.w3.org/1999/xlink";
        xlink:type CDATA #FIXED "simple"
        xlink:href CDATA #REQUIRED
        id         ID #IMPLIED>

<!ELEMENT updates (link)>

<!ELEMENT support (link)>

<!ELEMENT errorset (about?, support?, subset*, cause*, note*, error*)>
<!ATTLIST errorset
        name CDATA #REQUIRED
        version CDATA #IMPLIED
        authority CDATA #IMPLIED
        authoritiveDocuments CDATA #IMPLIED>

<!ELEMENT about (link)>

<!ELEMENT subset (deprecate*)>
<!ATTLIST subset
        name CDATA #REQUIRED
        version CDATA #IMPLIED>

<!ELEMENT deprecate EMPTY>
<!ATTLIST deprecate
        code CDATA #REQUIRED>

<!ELEMENT error ((cause | symbol | note | seealso)*, support?)>
<!ATTLIST error
        code CDATA #REQUIRED
        id   ID #IMPLIED
        severity CDATA "error"
        description CDATA #REQUIRED>

<!ELEMENT cause (description, suggestion*)>
<!ATTLIST cause
        title CDATA "Possible Cause"
        id    ID #IMPLIED>

<!ELEMENT description (#PCDATA)>

<!ELEMENT suggestion (#PCDATA)>
<!ATTLIST suggestion
        title CDATA "Possible Solution">
        
<!ELEMENT symbol (#PCDATA)>
<!ATTLIST symbol
        language CDATA #IMPLIED>

<!ELEMENT note (#PCDATA)>
<!ATTLIST note
        title CDATA "Note"
        id    ID #IMPLIED
        ref   IDREF #IMPLIED>

<!ELEMENT seealso (#PCDATA)>
<!ATTLIST seealso
        ref IDREFS #REQUIRED>

<!-- end of DTD -->


An example LDAP translation using the above DTD (partially completed):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eddml SYSTEM "file:///home/rowley/projects/eddml/doc/eddml.dtd">

<eddml
        title = "example LDAP translation"
   revision = "1"
   copyright = "Copyright 2004 The Free Software Foundation"
        authors = "Pete Rowley"
   contact = "address@hidden"
>
   <updates>
      <link xlink:href="http://www.openrowley.com/eddml/ldap.xml";>
         The latest version of these LDAP error descriptions
      </link>
   </updates>
        
   <errorset 
                name="LDAP" 
                version="2" 
                authority="Internet Engineering Task Force"
      authoritiveDocuments="RFC 1777, RFC 1823, 
draft-ietf-ldapext-ldap-c-api-05.txt (expired)">
      
      <error code="0" severity="success" description="success">
         <note> your work is done, it worked!</note> 
         <symbol language="C">LDAP_SUCCESS</symbol>
      </error>
      
      <error code="1" description="operations error">
         <symbol language="C">LDAP_OPERATIONS_ERROR</symbol>
     </error>
     
      <error code="2" description="protocol error">
         <note>This error should rarely if ever be encountered by client 
applications that do not dabble in the protocol layer</note>
         <symbol language="C">LDAP_PROTOCOL_ERROR</symbol>
      </error>
      
      <error code="3" description="time limit exceeded">
         <symbol language="C">LDAP_TIMELIMIT_EXCEEDED</symbol>
      </error>
      
      <error code="4" description="size limit exceeded">
         <symbol language="C">LDAP_SIZELIMIT_EXCEEDED</symbol>
      </error>
      
      <error code="5" severity="return code" description="compare false">
         <symbol language="C">LDAP_COMPARE_FALSE</symbol>
         <note id="N5">Not a true error, this is the result of a compare 
operation</note>
      </error>
      
      <error code="6" severity="return code" description="compare true">
         <symbol language="C">LDAP_COMPARE_TRUE</symbol>
         <note ref="N5"/>
      </error>
      
      <error code="7" description="authentication method not supported">
         <symbol language="C">LDAP_STRONG_AUTH_NOT_SUPPORTED</symbol>
      </error>
      
      <error code="8" description="strong authentication required">
         <symbol language="C">LDAP_STRONG_AUTH_REQUIRED</symbol>
      </error>
      
      <error code="16" description="no such attribute">
         <symbol language="C">LDAP_NO_SUCH_ATTRIBUTE</symbol>
      </error>
      
      <error code="17" description="undefined attribute type">
         <symbol language="C">LDAP_UNDEFINED_TYPE</symbol>
      </error>
      
      <error code="18" description="inappropriate matching">
         <symbol language="C">LDAP_INNAPROPRIATE_MATCHING</symbol>
      </error>
      
      <error code="19" description="constraint violation">
         <symbol language="C">LDAP_CONSTRAINT_VIOLATION</symbol>
      </error>
      
      <error code="20" description="attribute or value exists">
         <symbol language="C">LDAP_TYPE_OR_VALUE_EXISTS</symbol>
      </error>
      
      <error code="21" description="invalid attribute syntax">
         <symbol language="C">LDAP_INVALID_SYNTAX</symbol>
      </error>
      
      <error code="32" description="no such object">
         <symbol language="C">LDAP_NO_SUCH_OBJECT</symbol>
      </error>
      
      <error code="33" description="alias problem">
         <symbol language="C">LDAP_ALIAS_PROBLEM </symbol>
      </error>
      
      <error code="34" description="invalid DN syntax">
         <symbol language="C">LDAP_INVALID_DN_SYNTAX</symbol>         
      </error>
      
      <error code="35" description="is leaf">
         <symbol language="C">LDAP_IS_LEAF</symbol>
      </error>
      
      <error code="36" description="alias dereferencing problem">
         <symbol language="C">LDAP_ALIAS_DEREF_PROBLEM</symbol>
      </error>
      
      <error code="48" description="inappropriate authentication">
         <symbol language="C">LDAP_INAPPROPRIATE_AUTH</symbol>
      </error>
      
      <error code="49" description="invalid credentials">
         <symbol language="C">LDAP_INVALID_CREDENTIALS</symbol>
      </error>
      
      <error code="50" description="insufficient access rights">
         <symbol language="C">LDAP_INSUFFICIENT_ACCESS</symbol>
      </error>
      
      <error code="51" description="busy">
         <symbol language="C">LDAP_BUSY</symbol>
      </error>
      
      <error code="52" description="unavailable">
         <symbol language="C">LDAP_UNAVAILABLE</symbol>
      </error>
      
      <error code="53" description="unwilling to perform">
         <symbol language="C">LDAP_UNWILLING_TO_PERFORM</symbol>
      </error>
      
      <error code="54" description="loop detect">
         <symbol language="C">LDAP_LOOP_DETECT</symbol>
      </error>
      
      <error code="64" description="naming violation">
          <symbol language="C">LDAP_NAMING_VIOLATION</symbol>
     </error>
     
      <error code="65" description="objectclass violation">
         <symbol language="C">LDAP_OBJECT_CLASS_VIOLATION</symbol>
      </error>
      
      <error code="66" description="not allowed on non-leaf">
         <symbol language="C">LDAP_NOT_ALLOWED_ON_NONLEAF</symbol>
      </error>
      
      <error code="67" description="not allowed on RDN">
         <symbol language="C">LDAP_NOT_ALLOWED_ON_RDN</symbol>
      </error>
      
      <error code="68" description="entry already exists">
         <symbol language="C">LDAP_ALREADY_EXISTS</symbol>
      </error>
      
      <error code="69" description="objectclass modifications prohibited">
         <symbol language="C">LDAP_NO_OBJECT_MODS</symbol>
      </error>
      
      <error code="80" description="other">
         <symbol language="C">LDAP_OTHER</symbol>
      </error>
   </errorset>

   <errorset
      name="LDAP C API"
      version="2"
                authority="Internet Engineering Task Force"
      authoritiveDocuments="RFC 1823, draft-ietf-ldapext-ldap-c-api-05.txt 
(expired)">

      <subset name="LDAP" version="2"/>
      
      <note title="Category" id="NCAPI">client side errors</note>
     
      <error code="0x46" description="results too large">
         <symbol language="C">LDAP_RESULTS_TOO_LARGE</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x51" description="server down">
         <symbol language="C">LDAP_SERVER_DOWN</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x52" description="local error">
         <symbol language="C">LDAP_LOCAL_ERROR</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x53" description="encoding error">
         <symbol language="C">LDAP_ENCODING_ERROR</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x54" description="decoding error">
         <symbol language="C">LDAP_DECODING_ERROR</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x55" description="time out">
         <symbol language="C">LDAP_TIMEOUT</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x56" description="authentication type unknown">
         <symbol language="C">LDAP_AUTH_UNKNOWN</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x57" description="filter error">
         <symbol language="C">LDAP_FILTER_ERROR</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x58" description="operation cancelled">
         <symbol language="C">LDAP_USER_CANCELLED</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x59" description="parameter error">
         <symbol language="C">LDAP_PARAM_ERROR</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x5a" severity="fatal" description="no memory">
         <symbol language="C">LDAP_NO_MEMORY</symbol>
         <note ref="NCAPI"/>
      </error> 
    </errorset>
   
   <errorset 
                name="LDAP" 
                version="3" 
                authority="Internet Engineering Task Force"
      authoritiveDocuments="RFC 2251, draft-ietf-ldapext-ldap-c-api-05.txt 
(expired)">
      
      <subset name="LDAP" version="2">
         <deprecate code="35"/>
      </subset>
      
      <error code="10" description="referral">
         <symbol language="C">LDAP_REFERRAL</symbol>
      </error>
      
      <error code="11" description="admin limit exceeded">
         <symbol language="C">LDAP_ADMINLIMIT_EXCEEDED</symbol>
      </error>
      
      <error code="12" description="unavailable critical extension">
         <symbol language="C">LDAP_UNAVAILABLE_CRITICAL_EXTENSION</symbol>
      </error>
      
      <error code="13" description="confidentiality required">
         <symbol language="C">LDAP_CONFIDENTIALITY_REQUIRED</symbol>
      </error>
      
      <error code="14" description="sasl bind in progress">
         <symbol language="C">LDAP_SASL_BIND_IN_PROGRESS</symbol>
      </error>
      
      <error code="71" description="affects multiple directory service agents">
         <symbol language="C">LDAP_AFFECTS_MULTIPLE_DSAS</symbol>
      </error>
        </errorset>
   
   <errorset
      name="LDAP C API"
      version="3"
                authority="Internet Engineering Task Force"
      authoritiveDocuments="draft-ietf-ldapext-ldap-c-api-05.txt (expired)">

      <subset name="LDAP C API" version="2"/>
      <subset name="LDAP" version="3"/>

      <error code="0x5b" description="connect error">
         <symbol language="C">LDAP_CONNECT_ERROR</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x5c" description="not supported">
         <symbol language="C">LDAP_NOT_SUPPORTED</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x5d" description="control not found">
         <symbol language="C">LDAP_CONTROL_NOT_FOUND</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x5e" description="no results returned">
         <symbol language="C">LDAP_NO_RESULTS_RETURNED</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x5f" description="more results to return">
         <symbol language="C">LDAP_MORE_RESULTS_TO_RETURN</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x60" description="client loop">
         <symbol language="C">LDAP_CLIENT_LOOP</symbol>
         <note ref="NCAPI"/>
      </error>
      
      <error code="0x61" description="referral limit exceeded">
         <symbol language="C">LDAP_REFERRAL_LIMIT_EXCEEDED</symbol>
         <note ref="NCAPI"/>
         <cause>
            <description>the number of referrals chased has exceeded the 
maximum the client library can dereference</description>
            <suggestion>turn off referral chasing in the client library and 
manually code the referral chasing</suggestion>
            <suggestion>reduce the number of referrals returned by the 
directory server(s), this may require a review of the deployment 
topology</suggestion>
         </cause>
      </error>
   </errorset>
</eddml>


Other Software Required:
libxml2


Other Comments:



_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/