2 This documents purpose is to collect what needs to be changed for a potential
6 Its not about Gtk. Its about C APIs with GObject support. But it is probably not
8 g-doc, gapi-doc, gnome-api-doc, ...
10 == remove and deprecate =
11 - tree_index and object_index are still named *.sgml
13 sgml-build.stamp -> db-build.stamp
14 sgml.stamp -> db.stamp
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
23 These are the rules regarding id-attributes:
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 (".")."
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
35 http://www.w3.org/TR/xml11/#NT-Name
36 http://www.w3.org/TR/REC-xml/#NT-Name
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.
42 If the ID contain a ':' xml processors believe it is using a namespace.
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
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?
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
58 - all files we read are checked through the path
59 - all files are written based on the first entry
61 === build dependencies ===
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
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
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?
79 === docbook -> markdown ===
80 The main performance culprit is the use of docbook (tools). Also writing docbook
81 in source comments is cumbersome. Finally the docbook toolchain is a heavy
82 dependency and harms portability. We already support lots of markdown, so we'd
83 like to have a pure markdown based workflow.
85 For that we'd like to provide a migration path:
86 - convert existing docbook files to markdown (e.g. using pandoc)
87 - convert/identify comments using docbook to markdown
89 Next we would replace gtkdoc-mkdb+gtkdoc-fixxref with gtkdoc-mkhtml2. This would
92 We could change gtkdoc-mkpdf to use wkhtmltopdf/htmldoc. For man-pages we
93 can use https://rtomayko.github.io/ronn/ronn.1.html.
94 The devhelp2 files would be output directly from gtkdoc-mkhtml2.
96 We can enable this new toolchain via the configure flavors option (needs support
97 for cmake, meson, ...).
99 These would be the steps to do this:
100 1.) [in progress] write the docbook comment migation tool:
101 see tools: tools/db2md.py
102 At the same time improve the amount of markdown we handle:
104 ** or __: <empahsis role="strong">
105 but be careful with already existing '*' and '_' chars (check warnings in
108 2.) [unassigned] create the plumbing for the new tool chain
109 Add the new makefile flavour to run gtkdoc-mkhtml2 instead. Add --flavour
110 options for gtkdocize. Create a stub gtkdoc-mkhtml2 tool.
112 3.) [in progress] refactor gtkdoc/mkdb.py to exctract reusable code
114 - only have the parse there
116 4.) [unassigned] write gtkdoc/mkhtml2.py
117 - select a template engine (e.g. jinja)
118 - create templates from the current html for the various page types (refentry,
120 - we won't need content_files and expand_content_files in Makefile.am, as
121 mkhtml2 would read $(DOC_MODULE)-docs.md (rename to index.md?) and find local
123 - convert all hand-written md files starting from the main-doc to html
126 wkhtmltopdf html/*.html tester2.pdf
127 Error: This version of wkhtmltopdf is build against an unpatched version of QT, and does not support more then one input document.
129 htmldoc --book --outfile tester2.pdf html/*.html
130 - need to pass html files in the logical order
131 - unicode issues (passing --charset utf-8 fails)
132 - --link seems to create bad links (opens file-browser)
133 - no css rendering :/
135 pandoc -r docbook -w markdown_github -o tester-docs.md tester-docs.xml
136 - pandoc has no xi:include support
137 - if we pipe it through xmllint we convert everything.
138 xmllint --noent --xinclude tester-docs.xml | pandoc -r docbook -w markdown -o tester-docs.md
139 - the index.md would need to represent the structure the docbook chunker would
143 - add an option to generate markdown comments
145 gstreamer plugindocs:
146 - generate markdown formatted files
148 === only drop docbook-xsl ===
149 Since the processing with docbook-xsl is what is slow, we could also consider to
150 keep the whole gtkdoc-mkdb and have 2 codepaths in gtkdoc-mkhtml. The new code-
151 path would real the docbook with element-tree, replicate the chunking that
152 docbook-xsl does and use a templating system to generate the html files
155 This is probably easier to achieve, but has less potential in the long run (e.g.
156 incremental doc updates).
158 On the plus side, we can do rarely used output-formats (like pdf, man) the way
159 we do them right now.
161 These would be the steps to do this:
162 1.) [done] write a the chunker
163 - standalone tool to load the docbook xml and chunk it (just touch the resulting
164 *.html files) until we produce the same
166 2.) [unassigned] transform some docbook to html
167 - evaluate template engines
169 - we can use the block syntax to handle nesting
170 - we need to warn when not handling certain docbook
172 3.) [unassigned] integrate this into the gtkdoc library
173 - add an option to gtkgoc-mkhtml (e.g. --engine={xslt,builtin} or just --noxlst)