Frequently Asked Questions

Now, I am going to ask you that question once more and if you say “no” I am going to shoot you through the head. (MPFC 33)

General

What Yagdoc means?

Why the question always is “what it means” and never “does it mean anything”?

It can mean for instance Yet Another Gtk DOCcumenter. Or Yeti's Alternative Gtk-DOC. Or Yeast Assault Group's Dance Of Contradiction.

How do you pronounce Yagdoc?

Is my pronunciation really relevant? I pronounce it yuck-dots [jŭk'dŏʦ], if you insist.

Which Python version is required?

2.4 or newer.

What other packages are required?

SimpleParse, the Python parser. Not many distributions include it, I'm considering bundling it with yagdoc.

For GObject inspection, GLib is of course required, including working GModule – and at this moment GThread too – plus compiler, linker, the usual lot. If your package builds a library with GObjects it requires them anyway.

Why don't you improve gtk-doc instead?

I wonder where you got the “instead” part, definitely not by looking at who contributes to gtk-doc.

gtk-doc codebase has been spaghettizing by various special cases and afterthought features for a long time and it badly needs a rewrite. What's worse, it has to support all the crap in ancient Gnome documentation. Writing a new program works around the compatibility problem nicely.

How to you plan to replace gtk-doc?

This question does not make any sense.

inspect does not work with --as-needed

Does it still surprise you --as-needed breaks things? You'd better get used to it. And what question is this anyway?

On the positive side, I plan to compensate by using --no-as-needed when linking inspect. If libtool is used, with_gnu_ld is set accordingly in configure. It can be harder when the package does not use libtool.

It's slow

This does not sound much like a question either.

Given my approach to the design, it's amazingly fast. For instance it could be considerably sped up just by using plain tuples instead of Tokens. But I prefer to be able to read the code. Unless the time taken by gtkdoc-scan starts being comparable with the DocBook → HTML step, there's no need to worry about its speed.

Why yet another index file?

Isn't index.sgml and foo.devhelp2 enough?

Unfortunately, both are crap – or their design is shortsighted if you like euphemisms:

• index.sgml maps symbols names after conversion to SGML identifiers. The SGMLized id is already present in the href attribute after #, making the id attribute completely redundant. On the other hand the actual symbol name is not anywhere. So instead of

  <ANCHOR symbol="GtkMenu:tearoff-state" href="gtk/GtkMenu.html#GtkMenu--tearoff-state">

  it contains

  <ANCHOR id="GtkMenu--tearoff-state" href="gtk/GtkMenu.html#GtkMenu--tearoff-state">

• foo.devhelp2 maps titles to ids, therefore instead of

  <keyword type="property" name="GtkMenu:tearoff-state" link="GtkMenu.html#GtkMenu--tearoff-state"/>

  it contains

  <keyword type="" name="The :tearoff-state property" link="GtkMenu.html#GtkMenu--tearoff-state"/>

  Ah, did I mention it does not index enum values at all?