Re: [pdf-devel] Error management

[jemarch]

    >      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.

   On this layer the lib/error.h API would be suitable ?  (actually with some
   changes like giving the caller the choice to write to 'stderr' or any other
   output buffer, as behdad suggested)

The error module should provide an enumeration with error codes (like
PDF_E_BADDATA) and error descriptions to be used by the modules of the
base layer.

Wrappers for lib/error.h's `error' and `error_at_line' are also
desirable.

   It looks like a good idea :-)

   As a final question, does this mean we will need both APIs (i.e. lib/error.h 
and
   a context-based new one) ?

Yes. We dont need to design the error abstractions needed by the
object level yet. We will be able to design the needed features when
designing the modules of the object layer (I expect to need a stack of
errors among other things, but I am not sure).

   1. Under this schema can we say that errors at the base layer represent 
"serious
      problems" / "incorrigible errors" ?

It depends on the concrete error. There may be fatal errors and mere
warnings. It is not the role of the error module to decide the
critical status of an error: the client of the base layer modules will
decide which error are fatal and which not. For example:

switch (pdf_some_base_layer_function ())
{
  case PDF_E_SOMEERROR:
  {
    /* This error is recoverable. Lets manage it */
    ...
    break;
  }
  case PDF_E_AQUITEBADERROR:
  {
    /* This is a fatal error. Lets manage it */
    ...
    break;
  }
}

See the time module section in the library reference manual
(doc/gnupdf.texi) for several examples of error codes (PDF_E_BADDATA,
etc). 

   2. For what I see the Document *Module* implements the Document Structure
      abstraction (section 3.6 in PDF 1.7 ref). Now I guess the Document 
*Layer* is
      another abstraction we need but is not explicitly defined on PDF 1.7 ref,
      am I right ?

Yes. The document layer provides access to what is called the "COS
level" in the Acrobat SDK. The client of the object layer see a PDF
document as a collection of objects.

-- 
Jose E. Marchesi  <address@hidden>
                  <address@hidden>

GNU Spain         http://es.gnu.org
GNU Project       http://www.gnu.org