GNOME.org
 

[gtk-doc] docs: design docs and comments

commit d2bc4a59c331501336846569ad7cd7e9ff09054d
Author: Stefan Kost <ensonic users sf net>
Date:   Tue Dec 22 22:23:18 2009 +0200

    docs: design docs and comments
    
    Start to figure some design decission before my time and track ideas what should
    be changed in the future design. Update some comemnts accordingly.

 TODO                |   61 +++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/design-1.x.txt  |    9 +++++++
 doc/design-2.x.txt  |   28 +++++++++++++++++++++++
 gtkdoc-common.pl.in |    6 +++-
 gtkdoc-mkdb.in      |    7 +-----
 5 files changed, 103 insertions(+), 8 deletions(-)
---
diff --git a/TODO b/TODO
index 58017b4..47622bf 100644
--- a/TODO
+++ b/TODO
@@ -197,6 +197,7 @@ We need parametric, user definable macros.
   - content of [] on stdin or as a file
   - get output on stdout or file
   - and replace the macro with it
+The changes could be made in gtkdoc-mkdb::ExpandAbbreviations()
 === example macros ===
 |highlight(c)[...]| - highlight source code for a specific language
 |dot(abc.svg)[...]| - format dot graph and include result as mediaobject
@@ -374,3 +375,63 @@ script:
 make ctags
 grep "gst_caps_is_always_compatible" tags
 
+
+= performance =
+- timestamp each step
+  make check >make.log
+- try CFLAGS=-O0 for compiling the scanner, no need to optimize it
+  CFLAGS="-O0" make check >make.log
+  safes max 0.5 sec.
+- xslt
+  http://docbook2x.sourceforge.net/latest/doc/performance.html
+  - play with xsltproc --profile --verbose --timing
+    cd tests/gobject/docs
+    time /usr/bin/xsltproc 2>xslt.log --profile --verbose --timing --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --xinclude --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ../tester-docs.xml
+    - l10n.language is slow
+      bug: https://sourceforge.net/tracker/index.php?func=detail&aid=2918673&group_id=21935&atid=373750
+      see: http://www.mail-archive.com/docbook-apps lists oasis-open org/msg05412.html
+      - overide l10n.language
+        glib/gobject
+        real        user        sys
+        2m15.221s   1m58.740s   0m1.456s
+        >
+        1m55.480s   1m44.296s   0m2.125s
+
+      
+  - try plain docbook xslt to see if maybe we have bad xslt templates in the 
+    customisation layer (gtk-doc.xsl)
+
+  - we could do the xinlcude processing once and use it for both html and pdf
+    time /usr/bin/xsltproc 2>../xslt4.log --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --xinclude --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ../tester-docs.xml
+    real        user       sys
+    0m4.846s    0m4.434s   0m0.147s
+    0m4.842s    0m4.386s   0m0.145s
+    
+    
+    time xmllint --nonet --xinclude ../tester-docs.xml >./tester-docs-all.xml
+    real        user       sys
+    0m0.596s    0m0.546s   0m0.023s
+    
+    time /usr/bin/xsltproc 2>../xslt5.log --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ./tester-docs-all.xml
+    real        user       sys
+    0m4.167s    0m3.834s   0m0.106s
+    0m4.248s    0m3.851s   0m0.114s
+    
+    
+    time xmllint --nonet --c14n --xinclude ../tester-docs.xml >./tester-docs-all2.xml
+    
+    real        user       sys
+    0m0.700s    0m0.636s   0m0.034s
+    
+    time /usr/bin/xsltproc 2>../xslt6.log --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ./tester-docs-all2.xml
+    
+    real        user       sys
+    0m3.344s    0m3.026s   0m0.109s
+    0m3.372s    0m3.037s   0m0.115s
+    
+    
+    l ../tester-docs.xml ./tester-docs-all*.xml
+    
+  - we could also try to compact the installed xslt
+    xmllint --nonet --c14n --xinclude gtk-doc.xsl | sed -ne '/<!--/ { :c; /-->/! { N; b c; }; /-->/s/<!--.*-->//g }; /^  *$/!p;' | sed '/^$/d' >gtk-doc.pre.xsl
+
diff --git a/doc/design-1.x.txt b/doc/design-1.x.txt
new file mode 100644
index 0000000..17d82fe
--- /dev/null
+++ b/doc/design-1.x.txt
@@ -0,0 +1,9 @@
+= gtk-doc-1.X =
+This docuemnt attempts to reverse engenier some design decissions in 
+gtk-doc-1.X.
+
+== sgml-ids ==
+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.)
+
diff --git a/doc/design-2.x.txt b/doc/design-2.x.txt
new file mode 100644
index 0000000..03d6074
--- /dev/null
+++ b/doc/design-2.x.txt
@@ -0,0 +1,28 @@
+= gtk-doc-2.X =
+This documents purpose is to collect what needs to be changed for a potential
+gtk-doc-2.X.
+
+== 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
+- rename generated index.sgml to something like index.idx - it is not wellformed
+  sgml
+
+== design fixes ==
+=== proper xml-id namesspaces ===
+We need proper xml-id namesspaces for document structure and symbols to avoid
+clashes e.g. between GtkWidget as a section and as a struct. Normal symbols
+should only be mangled to be a valid xml-id. Document structure ids should 
+contain a prefix.
+
+These are the rules according to http://www.w3.org/TR/html4/types.html#type-id:
+"ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by
+ any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons
+ (":"), and periods (".")."
+ 
+So we could easily use "DOC:" as a prefix for document structure ids.
+
+=== srcdir != builddir builds ===
+
+=== build dependencies ===
+
diff --git a/gtkdoc-common.pl.in b/gtkdoc-common.pl.in
index d54cd19..188d4ac 100644
--- a/gtkdoc-common.pl.in
+++ b/gtkdoc-common.pl.in
@@ -341,8 +341,10 @@ sub LogWarning {
 #                  hyphens ("-"), underscores ("_"), colons (":"), and
 #                  periods (".")."
 #
-#		NOTE: SGML ids are case-insensitive, so we have a few special
-#		      cases to avoid clashes of ids.
+#		NOTE: 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.)
 # Arguments   : $id - the string to be converted into a valid SGML id.
 #############################################################################
 
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index d888cf3..e53475e 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -3,7 +3,7 @@
 #
 # gtk-doc - GTK DocBook documentation generator.
 # Copyright (C) 1998  Damon Chaplin
-#               2007,2008  Stefan Kost
+#               2007,2008,2009  Stefan Kost
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -23,11 +23,6 @@
 #############################################################################
 # Script      : gtkdoc-mkdb
 # Description : This creates the DocBook files from the edited templates.
-#
-#               NOTE: When creating SGML IDS, we append ":CAPS" to all
-#               all-caps identifiers to prevent name clashes. (It basically
-#               never is the case that mixed-case identifiers would collide.)
-#               See the CreateValidSGMLID function.
 #############################################################################
 
 use strict;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]