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