Debian Codegraph @

attic/TODO

raw
1 The TODO list for the gtk-doc project is at Bugzilla,
2 the bugtracking system of the GNOME project.
3
4 Visit
5 http://bugzilla.gnome.org/buglist.cgi?product=gtk-doc&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED
6 to see what is already requested, or where you can help. :-)
7
8 To put an other request on the TODO list, visit
9 http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc
10
11 Also have a look at
12 http://live.gnome.org/DocumentationProject/GtkDocFuture
13 and join discussion about future features.
14
15
16 Developers can also add items here :)
17
18 = Less files to manually edit =
19 The goal is that we configure gtk-doc in configure.ac and Makefile.am and
20 document the code in the sources. Right no we also have to edit a bunch of extra
21 files:
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 ==
34 https://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 =
70 gtk-doc is using a makefile with several targets to get from sources to docs. It
71 uses makefile variables for configuration.
72 It might be easier to have a gtkdoc tool that can run the other gtkdoc tools
73 in the right order (ev. by importing them as modules). This could handle a few
74 things nicer that the makefiles don't do well. This would also make it easy to
75 run it manually or integrate into other build systems.
76
77
78 = Intermediate files =
79 Can we change the intermediate files into e.g. json or yaml so that we can just
80 load it from python?
81
82 Can we drop the decl-list.txt file (or rename to make sure this is what a
83 generated 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 =
103 We'd like to extend gtk-doc to understand conventions/features of gobject libs.
104 Ideally libs register their extension hooks, so that other libs that use these
105 libs 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 =
134 Bugzilla has some requests for extra warnings. We should support a common
135 commandline option(s) in all tools to enable/disable the warnings. The makefiles
136 should pass the flags from an env-var (GTKDOC_OPTIONS). The env-var should be
137 used after the regular flags, so that the env-var can override hardcoded
138 settings (in Makefile.am).
139
140 Lets take this warning for the example:
141 "Symbol name not found at the start of the comment block."
142
143 Version 1: (template "warn-xxx!, warn-yyy!")
144 --warn-missing-symbol-at-comment-start
145 --no-warn-missing-symbol-at-comment-start
146
147 Version 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
153 more 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 =
199 We 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
208 The 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 ===
227 if 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.
230 problems:
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 ==
246 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?
247 could 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 ==
263 Sometimes one defines a set of function and macros with very similar purpose, e.g.
264 READ_INT8, READ_INT16, READ_INT32. It would be great to allow documenting a symbol
265 READ_INT* instead of 3 docs which are copy'n'pasted anyway. In the output we will have
266 all 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
305 proposed 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
329 some 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 =
337 need 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 ==
353 The idea is to have an 'edit' link in an online version of the docs (build from
354 head development version) per doc-entry (symbols and section).
355 The link goes to a cgi and that gets following parameters: docmodule,symbol.
356 E.g. http://library.gnome.org/devel/references/edit?docmodule=glib&symbol=g_new
357 The 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).
359 problems:
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 =
366 cd gstreamer/gstreamer/docs/gst
367 gtkdoc-mkdb --module=gstreamer --source-dir=../../gst --outputsymbolswithoutsince
368 cd gstreamer/gstreamer/src
369 git bisect start
370 git bisect good
371 git bisect bad RELEASE-0_10_0
372 git bisect run script.sh
373
374 script:
375 #!/bin/sh
376 make ctags
377 grep "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/[email protected]/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
471 find . -name "*.xml" -exec egrep --color -Hn '&[_a-zA-Z]*;' {} \; | egrep -v '&(amp|lt|gt|quot|apos|nbsp);' | egrep --color '&[_a-zA-Z]*;'
472 find . -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,...}