2 This documents purpose is to collect what needs to be changed for a potential
6 Its not about Gtk. Its about C APIs with GObject support.
7 g-doc, gapi-doc, gnome-api-doc, ...
9 == remove and deprecate =
10 - get rid of anything related to tmpl (gtkdoc-mktmpl, the makefile rules, ..)
11 - get rid of sgml, we will only use docbook xml
12 - rename generated index.sgml to something like index.idx - it is not wellformed
15 sgml-build.stamp -> db-build.stamp
16 sgml.stamp -> db.stamp
19 === proper xml-id namesspaces ===
20 We need proper xml-id namesspaces for document structure and symbols to avoid
21 clashes e.g. between GtkWidget as a section and as a struct. Normal symbols
22 should only be mangled to be a valid xml-id. Document structure ids should
25 These are the rules regarding id-attributes:
27 http://www.w3.org/TR/html4/types.html#type-id:
28 "ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by
29 any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons
30 (":"), and periods (".")."
32 http://www.w3.org/TR/xml-id/#id-avn
33 "Attributes of type ID are subject to additional normalization rules: removing
34 leading and trailing space characters and replacing sequences of spaces with a
37 http://www.w3.org/TR/xml11/#NT-Name
38 http://www.w3.org/TR/REC-xml/#NT-Name
40 So we could easily use "DOC:" as a prefix for document structure ids.
41 In 1.x we add :CAPS as a suffix to avoid clashes between lower and uppercase
42 constructs. XML-IDs are not case insensitive, so we don't need that.
44 If the ID contain a ':' xml processors belive it is using a namespace.
46 === less files to maintain ===
47 - one needs to maintain $module-docs.xml
48 - in most cases $module-sections.txt need manual maintenance
49 - we could have a "Section:" tag for non-section comments to add them to a non
51 - we could have a "Private_Symbols:" tag in section to list symbols that
52 should be in private subsection
53 - the $module.types file need manual maintenance if one need special includes
54 - can we make the scanner smarter?
56 === srcdir != builddir builds ===
58 === build dependencies ===
61 - instead of having -{undocumented,undeclared,unused}.txt have just one file
62 - have sections in there for each type
63 - have a summary at the top
64 - have an option to disable generating the file
65 (or an option to specifically name it)
68 - use a wiki syntax: http://www.wikicreole.org/
69 - we need a template syntax on top of that for the various boxes (function, macro, struct, ...)
70 - perl module avaible: http://www.wikicreole.org/wiki/TextWikiCreole
71 http://search.cpan.org/~jburnett/Text-WikiCreole/
72 - we would need to extend it to return docbook xml