doc/design-2.x.txt

   1 = gtk-doc-2.X =
   2 This documents purpose is to collect what needs to be changed for a potential
   3 gtk-doc-2.X.
   4
   5 == name ==
   6 Its not about Gtk. Its about C APIs with GObject support. But it is probably not
   7 worth it.
   8 g-doc, gapi-doc, gnome-api-doc, ...
   9
  10 == remove and deprecate =
  11 - tree_index and object_index are still named *.sgml
  12 - in the makefiles
  13   sgml-build.stamp -> db-build.stamp
  14   sgml.stamp -> db.stamp
  15
  16 == design fixes ==
  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
  21 contain a prefix.
  22
  23 These are the rules regarding id-attributes:
  24
  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 (".")."
  29
  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
  33  single space."
  34
  35 http://www.w3.org/TR/xml11/#NT-Name
  36 http://www.w3.org/TR/REC-xml/#NT-Name
  37
  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.
  41
  42 If the ID contain a ':' xml processors believe it is using a namespace.
  43
  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
  48     default section
  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?
  53
  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
  57     they are the same
  58   - all files we read are checked through the path
  59   - all files are written based on the first entry
  60
  61 === build dependencies ===
  62
  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
  67   'doc-module.log'
  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
  72     tests
  73
  74 - TODO
  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?
  78
  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.
  84
  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
  88
  89 Next we would replace gtkdoc-mkdb+gtkdoc-fixxref with gtkdoc-mkhtml2. This would
  90 output html directly.
  91
  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.
  95
  96 We can enable this new toolchain via the configure flavors option (needs support
  97 for cmake, meson, ...).
  98
  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:
 103 * or _: <emphasis>
 104 ** or __: <empahsis role="strong">
 105 but be careful with already existing '*' and '_' chars (check warnings in
 106 tools/db2md.py).
 107
 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.
 111
 112 3.) [in progress] refactor gtkdoc/mkdb.py to exctract reusable code
 113 - gtkdoc/md_to_db.py
 114   - only have the parse there
 115
 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,
 119   index, ...).
 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
 122   links in there
 123 - convert all hand-written md files starting from the main-doc to html
 124
 125 Open Issues:
 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.
 128
 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 :/
 134
 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
 140   create
 141
 142 gdbus-codegen:
 143 - add an option to generate markdown comments
 144
 145 gstreamer plugindocs:
 146 - generate markdown formatted files
 147
 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
 153 (e.g. jinja).
 154
 155 This is probably easier to achieve, but has less potential in the long run (e.g.
 156 incremental doc updates).
 157
 158 On the plus side, we can do rarely used output-formats (like pdf, man) the way
 159 we do them right now.
 160
 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
 165
 166 2.) [unassigned] transform some docbook to html
 167 - evaluate template engines
 168   - jinja2:
 169     - we can use the block syntax to handle nesting
 170 - we need to warn when not handling certain docbook
 171
 172 3.) [unassigned] integrate this into the gtkdoc library
 173 - add an option to gtkgoc-mkhtml (e.g. --engine={xslt,builtin} or just --noxlst)