Re: gobject API docs and tutorial merge : stage 1

On Tue, 2005-04-05 at 09:27 +0200, Mathieu Lacage wrote: 
> On Mon, 2005-04-04 at 12:33 -0400, Owen Taylor wrote:
> > I think the question is whether advantages of the use of custom
> > tools ... whether specialized or extensions to gtk-doc ... is worth the
> > hassle of maintaining those tools, compared to just writing straight-up
> > docbook. Sure, it's painful to write:
> > 
> >  <link linkend="pango-fc-font-lock-face"><function>pango_fc_font_lock_face()</function></link>
> I think the original idea behind this was that I wanted to be able to
> generate nice-looking cross-refs for both html and pdf output. That way,
> I could put the intelligence required to generate the right linkends
> depending on the type of output tool.

The above expresses the right cross reference information in docbook.
Nothing more is necessary.... the docbook => html and docbook => pdf
stylesheets can do the rest.

> I have not had time to really attempt to generate nice pdf output with
> cross refs though.
> > 
> > But if the tutorial is mostly already written, then it can be done automated
> > once and then just updated from there.
> yes.
> > 
> > Another possibility would be to extend gtk-doc.dtd and gtk-doc.xsl to allow
> > 
> >  <gtkdocfunction function="pango_fc_lock_face"/>
> > 
> > Or maybe
> > 
> >  <gtkdoclink target="#PangoFcFont"/>
> > 
> > and then expand that out in the xsl. Though it means that we no longer have
> > standard docbook that can be processed by standard docbook tools. And doing
> > the function->id conversion in xsl might be hard.
> I have no idea how hard which is why I suggested to just hack it with
> perl code.

I think hacking it with Perl code is a very bad idea. The gtk-doc build
process is complicated enough as is. Adding another layer is going to
result in something very fragile.

While extending gtk-doc might be possible, I really think that keeping
it simple is the right thing to do.


Attachment: signature.asc
Description: This is a digitally signed message part

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]