Re: [pdf-devel] Object layer API

[gerel]

 > Date: Fri, 06 Feb 2009 00:49:36 +0100
 > From: address@hidden
 > 
 > Please take a look and send your comments to discuss: it is capital to
 > come with a useful and complete API for the object layer.

Of course, some comments follow.

 > Note that:
 > 
 > [...]
 >
 > 3) It is not clear to me where to put the pdf creation functions
 >    (currently pdf_obj_new_array, etc). Since every object is
 >    associated with a document, it may be advisable to move the
 >    function names to pdf_obj_doc_new_array, etc...

Well, we have two alternatives to model this relation in the API,

        1. Create a PDF object already associated to a document.
        2. Create a PDF object alone and then associate it to some document.

Right now the API follows 1. I believe we should follow 2, and still have the
current PDF object API procedures but as 'helpers', and with the prefix
'pdf_obj_doc_' in them instead.

So, to add a new real we would do:
##
pdf_obj_doc_new_real (doc, value);
###

with the following definition:
##
pdf_obj_doc_new_real (doc, value)
{
  pdf_obj_doc_add (doc, pdf_obj_real_new (value));
}
###

This way we have modeled the relation and defined a clear scope for each module
implementation (object and document), and yet have the helper
pdf_obj_doc_new_real() that seems so obvious to be there.

 > 6) I am still working in the first draft of the internal architecture
 >    of the layer. Don't assume that the pdf_obj_doc_t type will be
 >    implemented in a different module than the pdf_obj_t type, for
 >    instance.

Well, my previous comment is an argument in favour of splitting those types
implementation, if that helps.
BTW, by internal architecture draft do you mean this:
http://www.gnupdf.org/manuals/gnupdf-arch.html/The-object-layer.html ?

Some other notes.
I would rename procedures that end with 'put', i.e. 'pdf_xxx_xxx_put', to
'pdf_xxx_xxx_set'.
Regarding objects collections, can some object collection be referenced with
some ID within a PDF document ? (e.g. an indirect reference). I tried to find
out with the PDF reference but nothing.
Anyways, if they can't, I suggest to move the API description to the "Object
documents" section, as I see it, they're an attribute of the document.

BTW, I read 'strong reference' in the object layer section but couldn't find any
mention to them in the PDF reference. Any help ?

regards,
-gerel