[cairo] More docs

[Russell Shaw]

Owen Taylor wrote:
> On Sun, 2005-08-14 at 23:13 +1000, Russell Shaw wrote:
> 
>>I had to put in ugly extra blank lines because gtkdoc-mkdb seems to have
>>bugs. If you have:
>>
>><programlisting>
>>Ao.Co = Aa.Ca &lt;OP&gt; Ab.Cb
>>...
>>
>>then the xml generated has:
>>
>><para>
>><programlisting>
>>Ao.Co = Aa.Ca &lt;OP&gt; Ab.Cb
>></para>
>>...
>>
>>I spent far more time trying to debug gtkdoc than it took to find all the
>>cairo papers on the net, understand them, and make this doc:
> 
> If you are doing this inline (and I don't think this should be inline;
> while what you have is a good start, there's quite a bit of more
> information that should be provided to the user: it needs pictures and
> descriptions of what the operators used for, so I'd put the stuff into a
> separate .sgml file and then just refer to it from the cairo_operator_t
> description), then the "trick" used in gtk-doc is, instead of using a
> blank line, to use a line with a single space on it.

What do you mean by "instead of using a blank line" ? I tried all combinations
of adding and omitting blanklines without success. I even found that a pre-existing
<programlisting> later in the same file causes the same problems.