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. But it is probably not
   7 worth it.
   8 g-doc, gapi-doc, gnome-api-doc, ...
   9
  10 == remove and deprecate =
  11 - tree_index and object_index are still named *.sgml
  12 - in the makefiles
  13   sgml-build.stamp -> db-build.stamp
  14   sgml.stamp -> db.stamp
  15
  16 == design fixes ==
  17 === proper xml-id namesspaces ===
  18 We need proper xml-id namesspaces for document structure and symbols to avoid
  19 clashes e.g. between GtkWidget as a section and as a struct. Normal symbols
  20 should only be mangled to be a valid xml-id. Document structure ids should
  21 contain a prefix.
  22
  23 These are the rules regarding id-attributes:
  24
  25 http://www.w3.org/TR/html4/types.html#type-id:
  26 "ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by
  27  any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons
  28  (":"), and periods (".")."
  29
  30 http://www.w3.org/TR/xml-id/#id-avn
  31 "Attributes of type ID are subject to additional normalization rules: removing
  32  leading and trailing space characters and replacing sequences of spaces with a
  33  single space."
  34
  35 http://www.w3.org/TR/xml11/#NT-Name
  36 http://www.w3.org/TR/REC-xml/#NT-Name
  37
  38 So we could easily use "DOC:" as a prefix for document structure ids.
  39 In 1.x we add :CAPS as a suffix to avoid clashes between lower and uppercase
  40 constructs. XML-IDs are not case insensitive, so we don't need that.
  41
  42 If the ID contain a ':' xml processors believe it is using a namespace.
  43
  44 === less files to maintain ===
  45 - one needs to maintain $module-docs.xml
  46 - in most cases $module-sections.txt need manual maintenance
  47   - we could have a "Section:" tag for non-section comments to add them to a non
  48     default section
  49   - we could have a "Private_Symbols:" tag in section to list symbols that
  50     should be in private subsection
  51 - the $module.types file need manual maintenance if one need special includes
  52   - can we make the scanner smarter?
  53
  54 === srcdir != builddir builds ===
  55 - all tools get a search path
  56   - it contains builddir:srcdir if those are different or just one of them if
  57     they are the same
  58   - all files we read are checked through the path
  59   - all files are written based on the first entry
  60
  61 === build dependencies ===
  62
  63 === error/warning reporting ===
  64 - don't fail the build on doc-issues, instead fail the tests
  65 - all diagnostic output from the tools run during build in gcc style
  66 - instead of having -{undocumented,undeclared,unused}.txt have just one file
  67   'doc-module.log'
  68   - contains all the build diagnostics as well
  69   - summary as 'INFO' level
  70 - gtkdoc-check will scan that file for 'ERROR'/'WARNING' lines
  71   - depending on the CHECK_OPTIONS and the found lines if will fail certain
  72     tests
  73
  74 - TODO
  75   - recheck all output and check whether we need Warnings/Errors or just
  76     Warnings and flags to silence them
  77   - Do we need a way to suppress false positives?
  78
  79 === docbook -> markdown ===
  80 The main performance culprit is the use of docbook (tools). Also writing docbook
  81 in source comments is cumbersome. We already support lots of markdown, so we'd
  82 like to have a pure markdown based workflow.
  83
  84 For that we'd like to provide a migration path:
  85 - convert existing docbook files to markdown (e.g. pandoc)
  86 - convert/identify comments using docbook to markdown
  87
  88 Next we need a replacement for gtkdoc-mkdb: gtkdoc-mkmd to create extract
  89 markdown from  sources and generate support files (index files). We also need to
  90 patch gtkdoc-{mkdb/pdf} to run respective tools (e.g. pandoc).
  91
  92 We can enable such a toolchain via the configure flavors option.
  93
  94 TODO:
  95 - markdown does not define a way to aggregate fragments into a large book
  96   - we can only concat all the files in a stable order