doc/design-2.x.txt

   1 = gtk-doc-2.X =
   2 This documents purpose is to collect what needs to be changed for a potential
   3 gtk-doc-2.X.
   4
   5 == name ==
   6 Its not about Gtk. Its about C APIs with GObject support.
   7 g-doc, gapi-doc, gnome-api-doc, ...
   8
   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
  13   sgml
  14 - in the makefiles
  15   sgml-build.stamp -> db-build.stamp
  16   sgml.stamp -> db.stamp
  17
  18 == design fixes ==
  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
  23 contain a prefix.
  24
  25 These are the rules regarding id-attributes:
  26
  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 (".")."
  31
  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
  35  single space."
  36
  37 http://www.w3.org/TR/xml11/#NT-Name
  38 http://www.w3.org/TR/REC-xml/#NT-Name
  39
  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.
  43
  44 If the ID contain a ':' xml processors belive it is using a namespace.
  45
  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
  50     default section
  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?
  55
  56 === srcdir != builddir builds ===
  57
  58 === build dependencies ===
  59
  60 === report files ===
  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)
  66
  67 === markup ===
  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
  73