tools/c10e-html: run fixup conditionally
[gtk-doc.git] / TODO
blob9fe99fd24d4aea4f81fe06e532492ba4efb504d8
2 The TODO list for the gtk-doc project is at Bugzilla,
3 the bugtracking system of the GNOME project.
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. :-)
9 To put an other request on the TODO list, visit
10  http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc
12 Also have a look at
13  http://live.gnome.org/DocumentationProject/GtkDocFuture
14 and join discussion about future features.
17 Developers can also add items here :)
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
27 == .types ==
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
34 == -section.txt ==
35 https://bugzilla.gnome.org/show_bug.cgi?id=646094
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__
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
66 = More abbreviations =
67 * expand urls (needds more work, see gtkdoc-mkdb : ExpandAbbreviations)
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.
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?
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)
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
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.
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
112 == custom properties ==
113 - gtk has style and child properties
115 == extra gobject property flags ==
116 - gstreamer has 'controllable' properties
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=531572 : html-single
125   http://bugzilla.gnome.org/show_bug.cgi?id=466535 : pdf
126   http://bugzilla.gnome.org/show_bug.cgi?id=467488 : man
127   we need more configure options in gtk-doc.m4:
128   --(enable|disable)-gtk-doc-(html|pdf|man|html-single|rtf)
129   - html : enabled by default
130   - html-single : is single page html
131 * validation
132     xmllint --noout --xinclude --postvalid tester-docs.xml
133     xmllint --noout --postvalid tester-docs.fo --dtdvalid file://$HOME/download/fo.dtd
134     - fo.dtd : http://www.renderx.com/Tests/validator/fo.zip
135 * single page
136   xsltproc  --nonet --xinclude -o gtk-docs.html /home/ensonic/projects/gtk-doc/gtk-doc-single.xsl  gtk-docs.sgml
137   * need to check if we can pass the style-sheet class as a parameter (--stringparam gtkdoc.stylesheet=(chunk|docbook))
138   * we might also need to reflow some things, as gtk-doc.xsl also runs the devhelp/devhelp2 generation
139     - but then the urls in the devhelp file, refer to the chunked html anyway
142 = Warnings =
143 Bugzilla has some requests for extra warnings. We should support a common
144 commandline option(s) in all tools to enable/disable the warnings. The makefiles
145 should pass the flags from an env-var (GTKDOC_OPTIONS). The env-var should be
146 used after the regular flags, so that the env-var can override hardcoded
147 settings (in Makefile.am).
149 Lets take this warning for the example:
150   "Symbol name not found at the start of the comment block."
152 Version 1: (template "warn-xxx!, warn-yyy!")
153 --warn-missing-symbol-at-comment-start
154 --no-warn-missing-symbol-at-comment-start
156 Version 2: (template "warn:s@")
157 -Wmissing-symbol-at-comment-start
158 -Wno-missing-symbol-at-comment-start
159 -warn missing-symbol-at-comment-start
160 -warn no-missing-symbol-at-comment-start
162 more warnings:
163   - 'deprecated' deprecating 'features'
164   - 'dummy-docs' check if symbol docs are very short and repeat mainly words
165     from the symbol.
166   - possible xrefs (e.g. adding a # or () would make it a successful xref)
169 = GIR =
170 == scanning ==
171 * ideas
172   * use gir files
173     1) replace gtkdoc-scan/gtkdoc-scangobject by gtkdoc-gir and output the classical files or
174        patch gtkdoc-scan/gtkdoc-scangobject to output gir files
175     2) patch gtkdoc-mkdb to read stuff from gir instead of classical files
176   * if gir-files would have the comments too (they are getting this now):
177     * we could even drop scanning the sources
178     * IDEs could use the gir-files to show doc-tooltips for symbols
179   * we might need yet another makefile flavour to use gir files
180 * perl and xml
181   * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
183 == binding docs ==
184 * simmillar workflow to gettext
185 * add gtkdoc-mk??? to generate binding doc templates
186   * have c-comments there as comments
187   * when updating templates, mark sections that have changed as fuzzy
188 * add options to gtkdoc-mkdb to build docbook from those templates
189 * questions
190   * could we use the tmpl file mechanism?
191   * directory structure?
192     * we need to list the languages like ALL_LINGUAS for translations
193     * we need to create subdirs for binding docs, ideally we use one for 'C' as well
194 * devhelp
195   * devhelp files need a language attribute in the book-tag
196     language={C,C++,JavaScript,Perl,Python,...}
197   * devhelp could show a selector for the language
198   * need to get existing python/~mm docs to use it, gtk-doc could output
199     language=C for own docs
201 === installation ===
202 * need to install each book with a prefix
203 * would be good to have a language attribute in book tag to allow filter by language
204 * look at /usr/share/gtk-doc/html/pygobject/index.html
207 = external processors =
208 We need parametric, user definable macros.
209 |[ ... ]| - programlistings
210 |macro(arg1,arg2,...)[ ... ]| - call macro
211   - pass args as parameters (on the commandline)
212   - pass some gtk-doc vars in environment
213     (gtk-doc version, module, srcdir, buildir)
214   - content of [] on stdin or as a file
215   - get output on stdout or file
216   - and replace the macro with it
217 The changes could be made in gtkdoc-mkdb::ExpandAbbreviations()
218 == example macros ==
219 |highlight(c)[...]| - highlight source code for a specific language (c)
220   - what will this output? preformatted html to be xincluded?
221   - we could have macros for each format, the docbook xml macro would leave
222     enough traces in the html so that a html macro can continue
223 |dot(svg)[...]| - format dot graph and include result as mediaobject (in svg format)
224 |ditta(svg)[...]| - parse ascii art and include result as mediaobject (in svg format)
225   - we need to generate a filename for the image or use anoter parameter
227 == where to define macros ==
228 * system wide and with the package, <prefix>/share/gtk-doc/macros, $(srcdir)
229 * prefix for custom macros?
230 * we could require stdin for input and stdout for output, the wrapper for the
231   actual tool can ensure the convention
234 = styling =
235 === process html ===
236 if we highlight to html we get colors, we need to check what tags we should process though:
237 <pre class="programlisting"> is used for all code boxes.
238 <div class="informalexample"><pre class="programlisting"> is used for examples.
239 problems:
240 * in html we don't know the language anymore
241   * add another div
242 * with source-highlight, constants and types are not markedup.
243   for types we might need to build an own lang file dynamically and include
244   /usr/share/source-highlight/c.lang
245 === |[ ... ]| does not allow setting the language ===
246 * check for vi/emacs/jedit modelines
247   jedit: http://www.jedit.org/users-guide/buffer-local.html
248   vim: http://vim.wikia.com/wiki/Modeline_magic
249   emacs: http://www.delorie.com/gnu/docs/emacs/emacs_486.html
250 * allow <!-- language="C" --> comments after |[
251 * we need to catch those when processing the docbook and expanding the |[
252 * require new macro syntax
254 == show inherited api ==
255 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?
256 could we do that using javascript and some other magic?
259 = Markup =
260 == tags ==
261 * to document the api-life cycle we have: since, deprecated and stability:
262 * other things we might want to specify:
263   * multi-threading safety: mt-safe, use-with-lock <lock>
265 == protected scope ==
266 * we can have /* < protected > */ in classes
267 * we can have <SUBSECTION Protected> in -section.txt
268 * ideally we have Scope: {Public, Protected, Private} supported in doc comments
269 * there is a bug for gir, https://bugzilla.gnome.org/show_bug.cgi?id=594125
271 == wildcards in symbol names ==
272 Sometimes one defines a set of function and macros with very similar purpose, e.g.
273 READ_INT8, READ_INT16, READ_INT32. It would be great to allow documenting a symbol
274 READ_INT* instead of 3 docs which are copy'n'pasted anyway. In the output we will have
275 all matching declarations in one source listing. Multiple wildcards are okay.
278 = documentation best practises #518427 =
279 * we'd like offer a more complete skelleton
280   * structure
281   * docbook markup (part/chapter structure)
282 * structure
283   Suggested structure for api-docs.
284   Idea is to have more content that api reference. It would be good to have a
285   gnome-platform document in devhelp, so that we could xref that instead of
286   explaining 100 times how to use pkg-config.
288   * examples
289     * gobject in devhelp
290       * concepts / api / tools / tutorial / related tools
291     * gtk in devhelp
292       * overview / api / migation / tools
293     * qt reference docs in qt assistant
294       * classes / overview / tutorial&examples
295   * recommendation
296     * front-page
297       * table with details (http://www.docbook.org/tdg/en/html/bookinfo.html)
298         (problem: what enclosing tag)
299         Logo, Module Version
300         Copyright and Legalnotice
301         Links
302         * homepage, mailing lists, irc channel
303         * repository, source releases, bugtracker
304       * TOC
305     * introduction - what is is about
306     * concepts - explain basic ideas and terminology
307     * development - how to build and run, env-vars, different platforms
308     * api - classic api docs
309     * tutorial & examples - integrated to keep it up-to-date and cross referenced
310     * migration - how to for api changes, deprecations
311     * (releated) tools - tools part of the package or recommended for development
312     * indexes - api-index, depretations, new api since xxx
314 proposed structure in docbook xml:
315 <book>
316   <bookinfo>
317   </bookinfo>
318   <preface><title>Introduction</title>
319     ...
320   </preface>
321   <part label="I"><title>xxx Overview</title>
322     <xi:include href="building.xml" />
323     ...
324   </part>
325   <reference label="II"><title>xxx Core Reference</title>
326     <xi:include href="xml/gtkmain.xml" />
327     ...
328   </part>
329   <reference label="III"><title>xxx Object Reference</title>
330     <chapter><title>Object Hierarchy</title>
331       <xi:include href="xml/tree_index.sgml" />
332     </chapter>
333     <chapter>...
334   </part>
335   <index>...</index>
336 </book>
338 some things to check:
339 * gtk,glib: can we make a <part> for the glosary and index's (according to docbook, yes)
340   should we use <appendix>? its like a chapter.
341 * gobject: uses a <preface> for introductions
342 * gobject: uses <reference> as a parent for the xi:includeed <refentry> docs
345 = extra link for symbols =
346 need options for configure:
347 --enable-gtk-doc-codesearch-links
348 --enable-gtk-doc-liveedit-links
349 == viewvc,cgit,... ==
350 - link to some online service for the code
351 - problem: most don't have local anchors for the symbols
352 - where to set the uri (in the document, like for online url)?
353 - what about a template URL containing a %s for the "path/file" or a special macro
354   http://svn.gnome.org/viewvc/gtk-doc/trunk/tests/gobject/src/gobject.c?view=markup
355   http://buzztard.svn.sourceforge.net/viewvc/buzztard/trunk/buzztard/src/lib/core/core.c?view=markup
356   - unfortunately we can't link to symbols (only lines)
357   - linking to files is difficult as in gtkdoc we have modules
359 == codesearch ==
360 - google (code) link : http://www.google.com/codesearch?q=g_object_unref
361 == live editing ==
362 The idea is to have an 'edit' link in an online version of the docs (build from
363 head development version) per doc-entry (symbols and section).
364 The link goes to a cgi and that gets following parameters: docmodule,symbol.
365 E.g. http://library.gnome.org/devel/references/edit?docmodule=glib&symbol=g_new
366 The cgi would need a hashmap to get from docmodule to the way to check it out
367 (ideally it has a recent checkout and only updates it).
368 problems:
369 - signal that this has been edited already?
370 - support for xi:included examples
371 - updating the checkout could be slow
374 = fix missing since docs =
375 cd gstreamer/gstreamer/docs/gst
376 gtkdoc-mkdb --module=gstreamer --source-dir=../../gst --outputsymbolswithoutsince
377 cd gstreamer/gstreamer/src
378 git bisect start
379 git bisect good
380 git bisect bad RELEASE-0_10_0
381 git bisect run script.sh
383 script:
384 #!/bin/sh
385 make ctags
386 grep "gst_caps_is_always_compatible" tags
389 = performance =
390 - timestamp each step
391   make check >make.log
392 - try CFLAGS=-O0 for compiling the scanner, no need to optimize it
393   CFLAGS="-O0" make check >make.log
394   safes max 0.5 sec.
395 - xslt
396   http://docbook2x.sourceforge.net/latest/doc/performance.html
397   - play with xsltproc --profile --verbose --timing
398     cd tests/gobject/docs/html
399     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
400     - l10n.language is slow
401       bug: https://sourceforge.net/tracker/index.php?func=detail&aid=2918673&group_id=21935&atid=373750
402       see: http://www.mail-archive.com/docbook-apps@lists.oasis-open.org/msg05412.html
403       - overide l10n.language
404         glib/gobject
405         real        user        sys
406         2m15.221s   1m58.740s   0m1.456s
407         >
408         1m55.480s   1m44.296s   0m2.125s
409       - override many template related to gentext
410         real        user        sys
411         0m43.327s   0m38.594s   0m4.724s
412         >
413         real        user        sys
414         0m33.282s   0m29.266s   0m4.012s
415       - removing the gentext calls for nav-bar alt tags does not help
418   - try plain docbook xslt to see if maybe we have bad xslt templates in the
419     customisation layer (gtk-doc.xsl)
421   - we could do the xinlcude processing once and use it for both html and pdf
422     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
423     real        user       sys
424     0m4.846s    0m4.434s   0m0.147s
425     0m4.842s    0m4.386s   0m0.145s
428     time xmllint --nonet --xinclude ../tester-docs.xml >./tester-docs-all.xml
429     real        user       sys
430     0m0.596s    0m0.546s   0m0.023s
432     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
433     real        user       sys
434     0m4.167s    0m3.834s   0m0.106s
435     0m4.248s    0m3.851s   0m0.114s
438     time xmllint --nonet --c14n --xinclude ../tester-docs.xml >./tester-docs-all2.xml
440     real        user       sys
441     0m0.700s    0m0.636s   0m0.034s
443     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
445     real        user       sys
446     0m3.344s    0m3.026s   0m0.109s
447     0m3.372s    0m3.037s   0m0.115s
450     l ../tester-docs.xml ./tester-docs-all*.xml
452   - we could also try to compact the installed xslt
453     xmllint --nonet --c14n --xinclude gtk-doc.xsl | sed -ne '/<!--/ { :c; /-->/! { N; b c; }; /-->/s/<!--.*-->//g }; /^  *$/!p;' | sed '/^$/d' >gtk-doc.pre.xsl
454     - unfortunately there is no way to ask xsltproc to pre-transform an xslt, that could
455       - strip comments
456       - process xsl:import and xsl:include
457   - compile xslt
458     http://sourceforge.net/projects/xsltc/
459     http://www.xmlhack.com/read.php?item=618
460   - extra xsltproc options:
461     --novalid: saves ~ 0.12 sec
464 = python =
465 - consider swithcing to this markdown parser
466   https://pythonhosted.org/Markdown/index.html
467 - switch intermediate files to json/yaml
468   - we need to pick something, that we can easilly output from plain c (produced by gtkdoc-scangobj)
469   - decl-list.txt and .types would need to stay
470   - maybe maintain one file per sourcefile (in a subdir) to eventually be able to
471     do incremental builds
472 - refactor Read{Args,Declarations,Signals}File to output into a single dictionary each:
473   Signal{Names,Objects,Returns,...}[key] -> Signals[key].{names,objects,returns,...}