[pdf-devel] Error management

[jemarch]

Since the base layer of the library does not provide a common context
and since the functionality implemented by the several base modules
are relatively independent, we could use a simple error management
schema for the base layer:

- Procedures (functions not returning a single value) should return a
  `pdf_status_t' value (enum defined in `pdf_error.h') that indicates
  success (PDF_NOERROR == 0) or a specific error code (negative value,
  i.e. PDF_E_NOMEM).
  
  Example:

    if (!pdf_stm_close (stm))
    {
      /* Manage error */
    }

- Functions (functions returning a single value) may define an "error
  value" to return if an error has happened. The election of the error
  value depends on the physical and logical range of the function:

  - Functions returning pointers: NULL
  - Functions returning non-zero values: 0
  - ...

  There may be cases where it is not possible (or desirable) to
  provide an error value in the physical range of the function:

     pdf_real_t pdf_real_pow (pdf_real_t base, pdf_real_t exp);

  There may be also cases where a trick is done in order to provide a
  bigger physical range in order to hold error values:

     int pdf_stm_read_char (pdf_stm_t stm);

  The availability of an "error value" (or values) for a specific
  function should be documented in the library reference manual.

The client of the base layer is then expected to manage any error
status returned by a function.

The Object Layer of the library provides a context in which all
operations are made: the object-level document. In that case we could
embed the logic of error contexts inside the object-level documents
and the library would still be reentrant:

     pdf_o_some_operation (pdf_o_doc_t doc, arguments...)
     /* Check for errors in `doc' */

The pdf_error module could then implement the abstractions used inside
pdf_o_docs: a stack of pdf_status_t, etc.

A similar solution could be used for the Document Layer and the Page
Layer using `pdf_d_doc_t' as the context.

Anyway the important issue now is to agree in a suitable schema to be
used in the base layer. We will be able to extend the pdf_error module
in the future if needed.

Any feedback about this?