[cairo] Clickable links in PDF? Metadata?

[David Kastrup]

Adrian Johnson <ajohnson at redneon.com> writes:

> On 04/07/15 02:07, David Kastrup wrote:
>> 
>> I'm currently taking a look at the suitability of using Cairo for the
>> rendering purposes of GNU LilyPond <URL:http://www.lilypond.org>.
>> Hardly surprising, print output is pretty much a priority.
>> 
>> There are a few loose ends for which I see nothing in the
>> documentation.  With regard to PDF production, I cannot find the
>> following two items:
>> 
>> a) clickable links
>
> There have been several requests for this in the past.
>
>> b) document metadata
>
> And this too.
>
>> c) interfacing with the PDF production
>
> I'm not sure what this means.

It means peace, prosperity, and happiness.  So Cairo should have it.
I'll elaborate below.

>> Even if it seems like overkill to render every item with a clickable
>> link in a surface of its own.
>> 
>> There is also stuff like "attaching files" to a PDF (not as
>> important).  It may be that this works with the MIME data extensions
>> already.
>> 
>> Any further information about this stuff?  Present state, plans,
>> problems, possible interfaces/APIs, timelines, openness to
>> third-party contributions?
>
> The main issue with adding support for non graphical PDF features is
> that there is a lot of stuff in section 12, 13, and 14 of ISO32000. How
> much of it should we support?

I think the principal premise for the overall design should be not
having to support anything at all.  Instead, Cairo should get out of the
way for those who do want to write code supporting them.

I have only scratched the surface of Cairo documentation here.  The way
it looks to me is like Cairo surfaces are basically where drawing
operations are "captured".  And a backend defines how to create
surfaces, and how to convert them to a target device which, in the case
of PDF, is basically a written stream.  But what is really missing, and
that is not really the job of Cairo, is how to arrange the pieces into a
coherent whole, in this case one or more PDF documents, with fonts,
metadata, attached files, switchable layers, whatever.

For GUIs, this is basically a "canvas".  Now I think most of what is
needed is to be able to attach opaque user data to surfaces or
smaller-grained Cairo objects, and to not just write out data
"anonymously" but rather, when wanting to write a file, tell the
application "ok, now I am starting to write subsurface xxx" so that the
application may look at the attached user data and squeeze in
instructions for writing a link, or attaching layer information or
whatever.

In case that the Cairo backend is keeping track of file positions and
object numbers for PDF and resource data, this way of writing out
additional information must be accountable to the backend bookkeeping.
In general, the backend should not need to know just what the stuff the
application intersperses actually means, but it should not get
distracted by it.

> It will significantly increase the size of the API. Those providing
> cairo bindings don't want to see an explosion in the size of the API.

Not really: most of what Cairo needs to provide are a few generic hooks.
Then there will be a few PDF-specific commands for interspersing
material into the stream.

Most of the other stuff would be either the business of the application,
or of a specific more knowledgable PDFwrite_cairo library that can be
maintained and extended without further changes to Cairo itself.

> There are a couple of possible solutions. One would be to only support
> a very limited subset of the document management features. Links and
> metadata would fall in this category. The problem is there will always
> be someone who wants one more little feature and so the API keeps
> growing.

I don't see that.

> Another approach would be provide an API for inserting PDF
> dictionaries that can be used by an external library to support most
> of the document management features. I have not investigated this
> concept in sufficient detail to determine if it is feasible.

That sounds more like it.  I don't know whether the granularity and/or
access should be "dictionary level" though.  The main goal is to be able
to generate PDF output that intersperses material under control of the
application while maintaining consistency of offsets, PDF objects,
encoding.

> The second option has been on my TODO list for about 5 or 6 years but
> I never found the the time to progress it. Contributions are welcome
> since it is clear I am unlikely complete it. I suggest proposing an
> API first.

Well, one would probably have to develop this kind of LilyPond
functionality in a branch in parallel with Cairo.  If the design is done
well, Cairo will have time to stabilize and get into stable distribution
before LilyPond is going to switch.

-- 
David Kastrup