TODO

   1
   2 The TODO list for the gtk-doc project is at Bugzilla,
   3 the bugtracking system of the GNOME project.
   4
   5 Visit
   6  http://bugzilla.gnome.org/buglist.cgi?product=gtk-doc&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED
   7 to see what is allready requested, or where you can help. :-)
   8
   9 To put an other request on the TODO list, visit
  10  http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc
  11
  12 Also have a look at
  13  http://live.gnome.org/DocumentationProject/GtkDocFuture
  14 and join discussion about future features.
  15
  16
  17 Developers can also add items here :)
  18
  19 = Less files to manually edit =
  20 The goal is that we configure gtk-doc in configure.ac and Makefile.am and
  21 document the code in the sources. Right no we also have to edit a bunch of extra
  22 files:
  23  * $(DOC_MODULE).types
  24  * $(DOC_MODULE)-docs.xml
  25  * $(DOC_MODULE)-sections.txt
  26
  27 == .types ==
  28
  29 * using SCAN_OPTION="--rebuild-types" can be used to avoid maintaining the types
  30   file
  31 * we need to check if this works well for all kind of _types (e.g. boxed)
  32   https://bugzilla.gnome.org/show_bug.cgi?id=605025
  33
  34 == -section.txt ==
  35 https://bugzilla.gnome.org/show_bug.cgi?id=646094
  36
  37 * using SCAN_OPTION="--rebuild-sections" can be used to use the audogenerated
  38   sections file
  39 * when scanning a header file, everything of the header and the respective .c
  40   file will be put to one section
  41 * symbols can be hidden using __GTK_DOC_IGNORE__
  42
  43 * we need comment markup to override the section
  44   e.g.: " * InSection: xxxx"
  45   this needs gtkdoc-mkdb::ScanSourceFile to understand a new tag, which
  46   otherwise would appear as verbatim in the sources
  47 * if one has "@InSection: xxxx" in a section comment we could patch the
  48   main.xml file and insert then xi:include line (would possibly rely on a
  49   special comment-pair there, we might also need to rewrite these
  50   auto-generated xi:includes everytime as the placements could have been
  51   changed, or we have a xi:inlcude for each chapter, that we regenerate).
  52 * we need a way to specify subsections (Standart, Private)
  53   this could be done in the SECTION comment
  54   e.g.: "@HideSymbols: <list-of-symbols-to-hide>
  55   * we could allow to have a SUBSECTION:xxx comment block too
  56     but then we list all the symbols here to override the auto-section placement
  57 * if we want to avoid the "InSection in symbol docs we could also have
  58   e.g.: "@ExtraSymbols: <list-of-symbols-to-include>
  59 * documented symbols that are in a file without section comment and do not
  60   appear in "@ExtraSymbols", "@HideSymbols" would go to unused.txt
  61   * shall we deprecated the unused sub-sections?
  62 * can we have both at the same time (for migration)
  63   * yes, read section-file first and add/override from inline comments
  64
  65
  66 = More abbreviations =
  67 * expand urls (needds more work, see gtkdoc-mkdb : ExpandAbbreviations)
  68
  69
  70 = Running =
  71 gtk-doc is using a makefile with several targets to get from sources to docs. It
  72 uses makefile variables for configuration.
  73 It might be easier to have a gtkdoc tool that can run the other gtkdoc tools
  74 in the right order (ev. by importing them as modules). This could handle a few
  75 things nicer that the makefiles don't do well. This would also make it easy to
  76 run it manually or integrate into other build systems.
  77
  78
  79 = Intermediate files =
  80 Can we change the intermediate files into e.g. json or yaml so that we can just
  81 load it from python?
  82
  83 Can we drop the decl-list.txt file (or rename to make sure this is what a
  84 generated section.txt would look like)
  85
  86
  87 = Issues =
  88 * gtkdoc-fixxref makefile targets use $HTML_DIR
  89   * HTML_DIR: The directory where gtk-doc generated documentation is installed
  90     it comes from gtk-doc.m4 (--with-html-dir) but has no default
  91   * automake exports $htmldir which is by default:
  92     ${prefix}/share/doc/${PACKAGE_TARNAME}
  93   * the Makefile uses $(DESTDIR)$(TARGET_DIR)
  94     where TARGET_DIR = $(HTML_DIR)/$(DOC_MODULE)
  95     http://www.gnu.org/software/libtool/manual/automake/DESTDIR.html
  96 * gtkdoc does not know about module versions
  97   * this is causing troubles when multiple library versions are installed
  98     (gtk+-{2,3}, gstreamer-{0.8,0.10,1.0}
  99   * right now gtk-doc is xreffing against any <module>/*.devhelp2 found
 100   * just using the one with a higher number won't work
 101
 102
 103 = Extensibility =
 104 We'd like to extend gtk-doc to understand conventions/features of gobject libs.
 105 Ideally libs register their extension hooks, so that other libs that use these
 106 libs can benefit from the extensions too.
 107
 108 == custom get_types collector ==
 109 - the default method takes the types from a type file
 110 - gstreamer plugin docs take a list of types from the gst plugin registry
 111
 112 == custom properties ==
 113 - gtk has style and child properties
 114
 115 == extra gobject property flags ==
 116 - gstreamer has 'controllable' properties
 117
 118 = Output =
 119 * http://sagehill.net/docbookxsl/index.html
 120 * multipage-html
 121   * would be good to be able to have page titles as a concatenation of document
 122     name and page name (gtk+:GtkWIdget)
 123 * formats
 124   http://bugzilla.gnome.org/show_bug.cgi?id=466535 : pdf
 125   http://bugzilla.gnome.org/show_bug.cgi?id=467488 : man
 126   we need more configure options in gtk-doc.m4:
 127   --(enable|disable)-gtk-doc-(html|pdf|man)
 128   - html : enabled by default
 129 * validation
 130     xmllint --noout --xinclude --postvalid tester-docs.xml
 131     xmllint --noout --postvalid tester-docs.fo --dtdvalid file://$HOME/download/fo.dtd
 132     - fo.dtd : http://www.renderx.com/Tests/validator/fo.zip
 133
 134 = Warnings =
 135 Bugzilla has some requests for extra warnings. We should support a common
 136 commandline option(s) in all tools to enable/disable the warnings. The makefiles
 137 should pass the flags from an env-var (GTKDOC_OPTIONS). The env-var should be
 138 used after the regular flags, so that the env-var can override hardcoded
 139 settings (in Makefile.am).
 140
 141 Lets take this warning for the example:
 142   "Symbol name not found at the start of the comment block."
 143
 144 Version 1: (template "warn-xxx!, warn-yyy!")
 145 --warn-missing-symbol-at-comment-start
 146 --no-warn-missing-symbol-at-comment-start
 147
 148 Version 2: (template "warn:s@")
 149 -Wmissing-symbol-at-comment-start
 150 -Wno-missing-symbol-at-comment-start
 151 -warn missing-symbol-at-comment-start
 152 -warn no-missing-symbol-at-comment-start
 153
 154 more warnings:
 155   - 'deprecated' deprecating 'features'
 156   - 'dummy-docs' check if symbol docs are very short and repeat mainly words
 157     from the symbol.
 158   - possible xrefs (e.g. adding a # or () would make it a successful xref)
 159
 160
 161 = GIR =
 162 == scanning ==
 163 * ideas
 164   * use gir files
 165     1) replace gtkdoc-scan/gtkdoc-scangobject by gtkdoc-gir and output the classical files or
 166        patch gtkdoc-scan/gtkdoc-scangobject to output gir files
 167     2) patch gtkdoc-mkdb to read stuff from gir instead of classical files
 168   * if gir-files would have the comments too (they are getting this now):
 169     * we could even drop scanning the sources
 170     * IDEs could use the gir-files to show doc-tooltips for symbols
 171   * we might need yet another makefile flavour to use gir files
 172 * perl and xml
 173   * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
 174
 175 == binding docs ==
 176 * simmillar workflow to gettext
 177 * add gtkdoc-mk??? to generate binding doc templates
 178   * have c-comments there as comments
 179   * when updating templates, mark sections that have changed as fuzzy
 180 * add options to gtkdoc-mkdb to build docbook from those templates
 181 * questions
 182   * could we use the tmpl file mechanism?
 183   * directory structure?
 184     * we need to list the languages like ALL_LINGUAS for translations
 185     * we need to create subdirs for binding docs, ideally we use one for 'C' as well
 186 * devhelp
 187   * devhelp files need a language attribute in the book-tag
 188     language={C,C++,JavaScript,Perl,Python,...}
 189   * devhelp could show a selector for the language
 190   * need to get existing python/~mm docs to use it, gtk-doc could output
 191     language=C for own docs
 192
 193 === installation ===
 194 * need to install each book with a prefix
 195 * would be good to have a language attribute in book tag to allow filter by language
 196 * look at /usr/share/gtk-doc/html/pygobject/index.html
 197
 198
 199 = external processors =
 200 We need parametric, user definable macros.
 201 |[ ... ]| - programlistings
 202 |macro(arg1,arg2,...)[ ... ]| - call macro
 203   - pass args as parameters (on the commandline)
 204   - pass some gtk-doc vars in environment
 205     (gtk-doc version, module, srcdir, buildir)
 206   - content of [] on stdin or as a file
 207   - get output on stdout or file
 208   - and replace the macro with it
 209 The changes could be made in gtkdoc-mkdb::ExpandAbbreviations()
 210 == example macros ==
 211 |highlight(c)[...]| - highlight source code for a specific language (c)
 212   - what will this output? preformatted html to be xincluded?
 213   - we could have macros for each format, the docbook xml macro would leave
 214     enough traces in the html so that a html macro can continue
 215 |dot(svg)[...]| - format dot graph and include result as mediaobject (in svg format)
 216 |ditta(svg)[...]| - parse ascii art and include result as mediaobject (in svg format)
 217   - we need to generate a filename for the image or use anoter parameter
 218
 219 == where to define macros ==
 220 * system wide and with the package, <prefix>/share/gtk-doc/macros, $(srcdir)
 221 * prefix for custom macros?
 222 * we could require stdin for input and stdout for output, the wrapper for the
 223   actual tool can ensure the convention
 224
 225
 226 = styling =
 227 === process html ===
 228 if we highlight to html we get colors, we need to check what tags we should process though:
 229 <pre class="programlisting"> is used for all code boxes.
 230 <div class="informalexample"><pre class="programlisting"> is used for examples.
 231 problems:
 232 * in html we don't know the language anymore
 233   * add another div
 234 * with source-highlight, constants and types are not markedup.
 235   for types we might need to build an own lang file dynamically and include
 236   /usr/share/source-highlight/c.lang
 237 === |[ ... ]| does not allow setting the language ===
 238 * check for vi/emacs/jedit modelines
 239   jedit: http://www.jedit.org/users-guide/buffer-local.html
 240   vim: http://vim.wikia.com/wiki/Modeline_magic
 241   emacs: http://www.delorie.com/gnu/docs/emacs/emacs_486.html
 242 * allow <!-- language="C" --> comments after |[
 243 * we need to catch those when processing the docbook and expanding the |[
 244 * require new macro syntax
 245
 246 == show inherited api ==
 247 could we write small html files for each object for methods, signals and properties and then use iframes to combine those at runtime like in javadoc?
 248 could we do that using javascript and some other magic?
 249
 250
 251 = Markup =
 252 == tags ==
 253 * to document the api-life cycle we have: since, deprecated and stability:
 254 * other things we might want to specify:
 255   * multi-threading safety: mt-safe, use-with-lock <lock>
 256
 257 == protected scope ==
 258 * we can have /* < protected > */ in classes
 259 * we can have <SUBSECTION Protected> in -section.txt
 260 * ideally we have Scope: {Public, Protected, Private} supported in doc comments
 261 * there is a bug for gir, https://bugzilla.gnome.org/show_bug.cgi?id=594125
 262
 263 == wildcards in symbol names ==
 264 Sometimes one defines a set of function and macros with very similar purpose, e.g.
 265 READ_INT8, READ_INT16, READ_INT32. It would be great to allow documenting a symbol
 266 READ_INT* instead of 3 docs which are copy'n'pasted anyway. In the output we will have
 267 all matching declarations in one source listing. Multiple wildcards are okay.
 268
 269
 270 = documentation best practises #518427 =
 271 * we'd like offer a more complete skelleton
 272   * structure
 273   * docbook markup (part/chapter structure)
 274 * structure
 275   Suggested structure for api-docs.
 276   Idea is to have more content that api reference. It would be good to have a
 277   gnome-platform document in devhelp, so that we could xref that instead of
 278   explaining 100 times how to use pkg-config.
 279
 280   * examples
 281     * gobject in devhelp
 282       * concepts / api / tools / tutorial / related tools
 283     * gtk in devhelp
 284       * overview / api / migation / tools
 285     * qt reference docs in qt assistant
 286       * classes / overview / tutorial&examples
 287   * recommendation
 288     * front-page
 289       * table with details (http://www.docbook.org/tdg/en/html/bookinfo.html)
 290         (problem: what enclosing tag)
 291         Logo, Module Version
 292         Copyright and Legalnotice
 293         Links
 294         * homepage, mailing lists, irc channel
 295         * repository, source releases, bugtracker
 296       * TOC
 297     * introduction - what is is about
 298     * concepts - explain basic ideas and terminology
 299     * development - how to build and run, env-vars, different platforms
 300     * api - classic api docs
 301     * tutorial & examples - integrated to keep it up-to-date and cross referenced
 302     * migration - how to for api changes, deprecations
 303     * (releated) tools - tools part of the package or recommended for development
 304     * indexes - api-index, depretations, new api since xxx
 305
 306 proposed structure in docbook xml:
 307 <book>
 308   <bookinfo>
 309   </bookinfo>
 310   <preface><title>Introduction</title>
 311     ...
 312   </preface>
 313   <part label="I"><title>xxx Overview</title>
 314     <xi:include href="building.xml" />
 315     ...
 316   </part>
 317   <reference label="II"><title>xxx Core Reference</title>
 318     <xi:include href="xml/gtkmain.xml" />
 319     ...
 320   </part>
 321   <reference label="III"><title>xxx Object Reference</title>
 322     <chapter><title>Object Hierarchy</title>
 323       <xi:include href="xml/tree_index.sgml" />
 324     </chapter>
 325     <chapter>...
 326   </part>
 327   <index>...</index>
 328 </book>
 329
 330 some things to check:
 331 * gtk,glib: can we make a <part> for the glosary and index's (according to docbook, yes)
 332   should we use <appendix>? its like a chapter.
 333 * gobject: uses a <preface> for introductions
 334 * gobject: uses <reference> as a parent for the xi:includeed <refentry> docs
 335
 336
 337 = extra link for symbols =
 338 need options for configure:
 339 --enable-gtk-doc-codesearch-links
 340 --enable-gtk-doc-liveedit-links
 341 == viewvc,cgit,... ==
 342 - link to some online service for the code
 343 - problem: most don't have local anchors for the symbols
 344 - where to set the uri (in the document, like for online url)?
 345 - what about a template URL containing a %s for the "path/file" or a special macro
 346   http://svn.gnome.org/viewvc/gtk-doc/trunk/tests/gobject/src/gobject.c?view=markup
 347   http://buzztard.svn.sourceforge.net/viewvc/buzztard/trunk/buzztard/src/lib/core/core.c?view=markup
 348   - unfortunately we can't link to symbols (only lines)
 349   - linking to files is difficult as in gtkdoc we have modules
 350
 351 == codesearch ==
 352 - google (code) link : http://www.google.com/codesearch?q=g_object_unref
 353 == live editing ==
 354 The idea is to have an 'edit' link in an online version of the docs (build from
 355 head development version) per doc-entry (symbols and section).
 356 The link goes to a cgi and that gets following parameters: docmodule,symbol.
 357 E.g. http://library.gnome.org/devel/references/edit?docmodule=glib&symbol=g_new
 358 The cgi would need a hashmap to get from docmodule to the way to check it out
 359 (ideally it has a recent checkout and only updates it).
 360 problems:
 361 - signal that this has been edited already?
 362 - support for xi:included examples
 363 - updating the checkout could be slow
 364
 365
 366 = fix missing since docs =
 367 cd gstreamer/gstreamer/docs/gst
 368 gtkdoc-mkdb --module=gstreamer --source-dir=../../gst --outputsymbolswithoutsince
 369 cd gstreamer/gstreamer/src
 370 git bisect start
 371 git bisect good
 372 git bisect bad RELEASE-0_10_0
 373 git bisect run script.sh
 374
 375 script:
 376 #!/bin/sh
 377 make ctags
 378 grep "gst_caps_is_always_compatible" tags
 379
 380
 381 = performance =
 382 - timestamp each step
 383   make check >make.log
 384 - try CFLAGS=-O0 for compiling the scanner, no need to optimize it
 385   CFLAGS="-O0" make check >make.log
 386   safes max 0.5 sec.
 387 - xslt
 388   http://docbook2x.sourceforge.net/latest/doc/performance.html
 389   - play with xsltproc --profile --verbose --timing
 390     cd tests/gobject/docs/html
 391     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
 392     - l10n.language is slow
 393       bug: https://sourceforge.net/tracker/index.php?func=detail&aid=2918673&group_id=21935&atid=373750
 394       see: http://www.mail-archive.com/docbook-apps@lists.oasis-open.org/msg05412.html
 395       - overide l10n.language
 396         glib/gobject
 397         real        user        sys
 398         2m15.221s   1m58.740s   0m1.456s
 399         >
 400         1m55.480s   1m44.296s   0m2.125s
 401       - override many template related to gentext
 402         real        user        sys
 403         0m43.327s   0m38.594s   0m4.724s
 404         >
 405         real        user        sys
 406         0m33.282s   0m29.266s   0m4.012s
 407       - removing the gentext calls for nav-bar alt tags does not help
 408
 409   - we could do the xinlcude processing once and use it for both html and pdf
 410     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
 411     real        user       sys
 412     0m4.846s    0m4.434s   0m0.147s
 413     0m4.842s    0m4.386s   0m0.145s
 414
 415
 416     time xmllint --nonet --xinclude ../tester-docs.xml >./tester-docs-all.xml
 417     real        user       sys
 418     0m0.596s    0m0.546s   0m0.023s
 419
 420     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
 421     real        user       sys
 422     0m4.167s    0m3.834s   0m0.106s
 423     0m4.248s    0m3.851s   0m0.114s
 424
 425
 426     time xmllint --nonet --c14n --xinclude ../tester-docs.xml >./tester-docs-all2.xml
 427
 428     real        user       sys
 429     0m0.700s    0m0.636s   0m0.034s
 430
 431     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
 432
 433     real        user       sys
 434     0m3.344s    0m3.026s   0m0.109s
 435     0m3.372s    0m3.037s   0m0.115s
 436
 437
 438     l ../tester-docs.xml ./tester-docs-all*.xml
 439
 440   - we could also try to compact the installed xslt
 441     xmllint --nonet --c14n --xinclude gtk-doc.xsl | sed -ne '/<!--/ { :c; /-->/! { N; b c; }; /-->/s/<!--.*-->//g }; /^  *$/!p;' | sed '/^$/d' >gtk-doc.pre.xsl
 442     - unfortunately there is no way to ask xsltproc to pre-transform an xslt, that could
 443       - strip comments
 444       - process xsl:import and xsl:include
 445   - extra xsltproc options:
 446     --novalid: saves ~ 0.12 sec
 447
 448   - strip DOCTYPES on xincludes
 449     - there is a performance bottleneck in libxml, where it parses DTD for each fragment
 450     - we're using the dtd to
 451       - validate fragments
 452       - inject package name/version etc.
 453     - 1) we could provide a flags to gtkdoc-mkdb to not put any doctype on
 454          generated file and manually result entities in generated files (and
 455          expand_content_files)
 456       - to get a list of entities:
 457         - we could parse entities from the main doc-file header
 458           - tricky as with xml/gtkdocentities.ent, they are in a extra file
 459         - we could pass entities as args for gtkdoc-mkdb
 460         - if the flag is used, we should warn if entities are in the header
 461     - 2) if the doctype on the main doc, does not conatin entities, skip adding
 462          the doctype to generated output
 463     - 3) if the doctype on the main doc contains entities, only add the doctype
 464          if the generated content contains entities ([&%][_a-zA-Z]*;)
 465     - a quick check on the gnome modules showed:
 466       - quite a few don't use entities
 467       - those that use version.xml
 468         - seem to mostly use it in the main doc
 469         - but a few use it for man pages
 470           find . -name "*.xml" -exec grep -Hn "&version;" {} \; | grep -v "\-docs.xml"
 471
 472 find . -name "*.xml" -exec egrep --color -Hn '&[_a-zA-Z]*;' {} \; | egrep -v '&(amp|lt|gt|quot|apos|nbsp);' | egrep --color '&[_a-zA-Z]*;'
 473 find . -name "*.xml" -exec egrep -o '&[_a-zA-Z]*;' {} \; | sort | uniq -c | sort -n
 474
 475 = python =
 476 - consider swithcing to this markdown parser
 477   https://pythonhosted.org/Markdown/index.html
 478 - switch intermediate files to json/yaml
 479   - we need to pick something, that we can easilly output from plain c (produced by gtkdoc-scangobj)
 480   - decl-list.txt and .types would need to stay
 481   - maybe maintain one file per sourcefile (in a subdir) to eventually be able to
 482     do incremental builds
 483 - refactor Read{Args,Declarations,Signals}File to output into a single dictionary each:
 484   Signal{Names,Objects,Returns,...}[key] -> Signals[key].{names,objects,returns,...}