doc/design-1.x.txt

   1 = gtk-doc-1.X =
   2 This document attempts to reverse engineer some design decisions in
   3 gtk-doc-1.X.
   4
   5 == sgml-ids ==
   6 When creating SGML IDS, we append ":CAPS" to all
   7 all-caps identifiers to prevent name clashes (SGML ids are case-insensitive).
   8 (It basically never is the case that mixed-case identifiers would collide.)
   9
  10 Unfortunately we create ambiguous ids. The document structure ids are e.g.
  11 GtkWidget.{top_of_page,synopsis,object-hierarchy,...}
  12 and that is ambiguous with eventual structure member of the same name.
  13
  14 cd tests
  15 find . -name "*.xml" -exec grep -o "id=\"[a-zA-Z_:.\-]*\"" {} \; | sort | uniq
  16
  17 == section-ids ==
  18 gtk-doc differentiates between plain-sections and gobject-sections:
  19 +---------+----------------+
  20 | type    | section-id     |
  21 +---------+----------------+
  22 | plain   | $module-$title |
  23 | gobject | $title         |
  24 +---------+----------------+
  25
  26 - links to #GtkWidget would go to $title
  27 - linking to the struct would need #GtkWidget-struct
  28