[gtk-doc] design: update

[Stefan Kost <stefkost src gnome org>]

commit 315368cd466ec985a1f93cccefd2d04dd3ed38be
Author: Stefan Kost <ensonic users sf net>
Date:   Fri Dec 25 01:33:53 2009 +0200

    design: update

 doc/design-1.x.txt |   19 +++++++++++++++++++
 doc/design-2.x.txt |   15 +++++++++++++++
 2 files changed, 34 insertions(+), 0 deletions(-)
---
diff --git a/doc/design-1.x.txt b/doc/design-1.x.txt
index 17d82fe..7586fc3 100644
--- a/doc/design-1.x.txt
+++ b/doc/design-1.x.txt
@@ -7,3 +7,22 @@ When creating SGML IDS, we append ":CAPS" to all
 all-caps identifiers to prevent name clashes (SGML ids are case-insensitive).
 (It basically never is the case that mixed-case identifiers would collide.)
 
+Unfortunately we create ambigous ids. The document structure ids are e.g.
+GtkWidget.{top_of_page,synopsis,object-hierarchy,...}
+and that is ambigous with eventual structure memeber of the same name.
+
+cd tests
+find . -name "*.xml" -exec grep -o "id=\"[a-zA-Z_:.\-]*\"" {} \; | sort | uniq
+
+== section-ids ==
+gtk-doc differenciates between plain-sections and gobject-sections:
++---------+----------------+
+| type    | section-id     |
++---------+----------------+
+| plain   | $module-$title |
+| gobject | $title         |
++---------+----------------+
+
+- links to #GtkWidget would go to $title
+- linking to the struct would need #GtkWidget-struct
+
diff --git a/doc/design-2.x.txt b/doc/design-2.x.txt
index 753f3cd..8fbd123 100644
--- a/doc/design-2.x.txt
+++ b/doc/design-2.x.txt
@@ -2,6 +2,10 @@
 This documents purpose is to collect what needs to be changed for a potential
 gtk-doc-2.X.
 
+== name ==
+Its not about Gtk. Its about C APIs with GObject support.
+g-doc, gapi-doc, gnome-api-doc, ...
+
 == remove and deprecate =
 - get rid of anything related to tmpl (gtkdoc-mktmpl, the makefile rules, ..)
 - get rid of sgml, we will only use docbook xml
@@ -34,6 +38,17 @@ So we could easily use "DOC:" as a prefix for document structure ids.
 In 1.x we add :CAPS as a suffix to avoid clashes between lower and uppercase
 constructs. XML-IDs are not case insensitive, so we don't need that.
 
+If the ID contain a ':' xml processors belive it is using a namespace.
+
+=== less files to maintain ===
+- one needs to maintain $module-docs.xml
+- in most cases $module-sections.txt need manual maintenance
+  - we could have a "Section:" tag for non-section comments to add them to a non
+    default section
+  - we would need to comment to mark things as private
+- the $module.types file need manual maintenance if one need special includes
+  - can we make the scanner smarter?
+
 === srcdir != builddir builds ===
 
 === build dependencies ===