From 200e5b1f85163e3660c8906ee0b0dd593862e2be Mon Sep 17 00:00:00 2001
From: Stefan Kost <stefkost@src.gnome.org>
Date: Mon, 20 Oct 2008 20:15:32 +0000
Subject: [PATCH] More docs and planning.

	* TODO:
	* devhelp2.xsd:
	  More docs and planning.


svn path=/trunk/; revision=613
---
 ChangeLog    |  6 ++++
 TODO         |  8 ++++--
 devhelp2.xsd | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++-------
 3 files changed, 93 insertions(+), 12 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 3e5c325..4ec3e48 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2008-10-20  Stefan Kost  <ensonic@users.sf.net>
 
+	* TODO:
+	* devhelp2.xsd:
+	  More docs and planning.
+
+2008-10-20  Stefan Kost  <ensonic@users.sf.net>
+
 	* tests/annotations/docs/tester-docs.xml:
 	* tests/annotations/src/tester.c:
 	* tests/gobject/docs/tester-docs.xml:
diff --git a/TODO b/TODO
index a649e35..2bd4bf6 100644
--- a/TODO
+++ b/TODO
@@ -124,8 +124,12 @@ diff -u --exclude="Makefile*" docs docs-tmpl | diffstat
 = GIR =
 == scanning ==
 * ideas
-  1) replace gtkdoc-scan/gtkdoc-scangobject by gtkdoc-gir and output the classical files
-  2) patch gtkdoc-mkdb to read stuff from gir instead of classical files
+  * use gir files
+    1) replace gtkdoc-scan/gtkdoc-scangobject by gtkdoc-gir and output the classical files
+    2) patch gtkdoc-mkdb to read stuff from gir instead of classical files
+  * if gir-files would have the comments too:
+    * we could even drop scanning the sources
+    * IDEs could use the gir-files to show doc-tooltips for symbols  
 * perl and xml
   * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
 == handling the annotations ==
diff --git a/devhelp2.xsd b/devhelp2.xsd
index 11487cb..c58b9bc 100644
--- a/devhelp2.xsd
+++ b/devhelp2.xsd
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 get http://xml.fiforms.org/xs3p/ and generate docs
-xsltproc -o buzztard.xsd.html /home/ensonic/download/xs3p-1.1.3/xs3p.xsl buzztard.xsd
+xsltproc -o devhelp2.xsd.html $HOME/download/xs3p-1.1.3/xs3p.xsl devhelp2.xsd
 -->
 <xsd:schema
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
@@ -9,6 +9,12 @@ xsltproc -o buzztard.xsd.html /home/ensonic/download/xs3p-1.1.3/xs3p.xsl buzztar
   targetNamespace="urn:devhelp"
   elementFormDefault="qualified">
 
+  <xsd:annotation>
+    <xsd:documentation>
+      Devhelp2 files are use in the 'devhelp' documentation browser.
+    </xsd:documentation>
+  </xsd:annotation>  
+
   <xsd:simpleType name="keyword-type">
     <xsd:restriction base="xsd:string">
       <xsd:enumeration value="constant"/>
@@ -22,6 +28,11 @@ xsltproc -o buzztard.xsd.html /home/ensonic/download/xs3p-1.1.3/xs3p.xsl buzztar
       <xsd:enumeration value="union"/>
       <xsd:enumeration value="variable"/>
     </xsd:restriction>
+    <xsd:annotation>
+      <xsd:documentation>
+        Known keyword types.
+      </xsd:documentation>
+    </xsd:annotation>  
   </xsd:simpleType>
   
   <xsd:simpleType name="language-type">
@@ -35,19 +46,79 @@ xsltproc -o buzztard.xsd.html /home/ensonic/download/xs3p-1.1.3/xs3p.xsl buzztar
       <xsd:enumeration value="python"/>
       <xsd:enumeration value="vala"/>
     </xsd:restriction>
+    <xsd:annotation>
+      <xsd:documentation>
+        Known programing languages.
+      </xsd:documentation>
+    </xsd:annotation>  
   </xsd:simpleType>
 
-  <xsd:attribute name="title" type="xsd:string"/>
-  <xsd:attribute name="link" type="xsd:string"/>
-  <xsd:attribute name="author" type="xsd:string"/>
-  <xsd:attribute name="name" type="xsd:string"/>
-  <xsd:attribute name="version" type="xsd:integer"/>
+  <xsd:attribute name="title" type="xsd:string">
+    <xsd:annotation>
+      <xsd:documentation>
+        Title of the reference manual.
+      </xsd:documentation>
+    </xsd:annotation>  
+  </xsd:attribute>
+  <xsd:attribute name="link" type="xsd:string">
+    <xsd:annotation>
+      <xsd:documentation>
+        Entry point to the manual. Can be given as a relative path to the
+        location of the devhelp2 file..
+      </xsd:documentation>
+    </xsd:annotation>  
+  </xsd:attribute>
+  <xsd:attribute name="author" type="xsd:string">
+    <xsd:annotation>
+      <xsd:documentation>
+        Author of the document. Multiple authors are separated by ','.
+      </xsd:documentation>
+    </xsd:annotation>  
+  </xsd:attribute>
+  <xsd:attribute name="name" type="xsd:string">
+    <xsd:annotation>
+      <xsd:documentation>
+        Short name of the manual.
+      </xsd:documentation>
+    </xsd:annotation>  
+  </xsd:attribute>
+  <xsd:attribute name="version" type="xsd:integer">
+    <xsd:annotation>
+      <xsd:documentation>
+        Version of the devhelp xml specification (2).
+      </xsd:documentation>
+    </xsd:annotation>  
+  </xsd:attribute>
+  <xsd:attribute name="language" type="language-type">
+    <xsd:annotation>
+      <xsd:documentation>
+        Programing language this manual refers to.
+      </xsd:documentation>
+    </xsd:annotation>  
+  </xsd:attribute>
 
-  <xsd:attribute name="type" type="keyword-type"/>
-  <xsd:attribute name="since" type="xsd:float"/>
-  <xsd:attribute name="deprecated" type="xsd:boolean"/>
+  <xsd:attribute name="type" type="keyword-type">
+    <xsd:annotation>
+      <xsd:documentation>
+        Type of the keyword.
+      </xsd:documentation>
+    </xsd:annotation>  
+  </xsd:attribute>
+  <xsd:attribute name="since" type="xsd:string">
+    <xsd:annotation>
+      <xsd:documentation>
+        Version since that the keyword is part of the API.
+      </xsd:documentation>
+    </xsd:annotation>  
+  </xsd:attribute>
+  <xsd:attribute name="deprecated" type="xsd:boolean">
+    <xsd:annotation>
+      <xsd:documentation>
+        Marks the keyword as deprecated.
+      </xsd:documentation>
+    </xsd:annotation>  
+  </xsd:attribute>
 
-  <xsd:attribute name="language" type="language-type"/>
 
   <xsd:element name="sub">
     <xsd:complexType>
-- 
2.11.4.GIT