[Checkins] SVN: Sandbox/ulif/grok-reference-with-rest2/doc/grokref/HACKING.txt Updated documentation.

[Uli Fouquet]

Log message for revision 82796:
  Updated documentation.

Changed:
  U   Sandbox/ulif/grok-reference-with-rest2/doc/grokref/HACKING.txt

-=-
Modified: Sandbox/ulif/grok-reference-with-rest2/doc/grokref/HACKING.txt
===================================================================
--- Sandbox/ulif/grok-reference-with-rest2/doc/grokref/HACKING.txt	2008-01-11 00:31:39 UTC (rev 82795)
+++ Sandbox/ulif/grok-reference-with-rest2/doc/grokref/HACKING.txt	2008-01-11 01:17:47 UTC (rev 82796)
@@ -45,3 +45,105 @@
 provided by the standard Python documentation. The output, however,
 will be different from what you might expect, if you have seen the
 ``sphinx`` output before.
+
+
+Technical problems with ``sphinx`` (Nerd Stuff (TM))
+----------------------------------------------------
+
+``sphinx`` provides an extended set of roles and directives. These can
+simply be understood by a doctree generator, if you simply copy the
+`roles` and `directives` modules from the ``sphinx`` package.
+
+But you cannot easily create HTML this way, because your docutils
+writer will complain about unknown node types. This happens, because
+the generic ``sphinx`` roles and directives create new node types,
+which are defined in the ``addnodes`` module of the ``sphinx``
+package.
+
+You can (and must) simply make this new node types resolvable, by also
+adding the ``addnodes`` module of the ``sphinx`` package.
+
+Unfortunately, even this won't be enough. You also need a special
+translator, which is able to translate each of the extended node types
+into your destination format (HTML, LaTeX, whatever). Such a
+translator is neccessary for every single output format you want to
+support and every single node type has to be handled. This is very
+error-prone, boring and might lead to frustrations.
+
+
+The grokref simplification
+--------------------------
+
+The main simplification of the grokref package is, that it builds the
+extended set of roles and directives with standard docutils node types
+instead of new ones. This way, every stock docutils parser can
+understand the doctrees generated by grokref.
+
+The simplified roles and directives are enabled by importing the
+extensions.directives_plain and the extensions.roles_plain modules of
+Grokref somewhere in your code, before creating parsers, writers etc.
+
+The advantage of this procedere is, that you can easily add support
+for the extended set of roles and directives to any system using
+standard docutils parsers like Plone.
+
+The drawback, however, is, that some information is lost. For example,
+you cannot easily traverse doctree documents searching for
+toctrees. There is no toctree node type in standard docutils. A
+workaround is, to search for standard docutils comment nodes, which
+also provide an ``includefiles`` attribute (normal comment nodes won't
+do this). Similar markers exist for most of the new node types, so
+that you can still treat them special.
+
+
+The markers of node types (directives)
+--------------------------------------
+
+* ``toctree``:
+
+   created as docutils.nodes.comment node with attributes ``maxdepth``
+   and ``includefiles``.
+
+* ``function``, ``data``, ``class``, ``method``, ``attribute``,
+  ``exception``, ``cmdoption``, ``envvar``, ``describe``:
+
+   are all so-called ``desc`` nodes that are created as
+   docutils.nodes.inline nodes with an entry in the ``classes``
+   attribute (a list), that is build as ``desc-<desc-type>``.
+
+   For example each (virtual) ``function`` node will be a
+   docutils.nodes.inline node with an attribute ``classes``, which in
+   turn is a list that at least will contain the value
+   `desc-function`.
+
+   Standard HTML writers will render this node with a class attribute
+   'desc-class', so that those tags can be treated special by CSS.
+
+   In the end the ``function`` node might appear in HTML like this::
+
+     <div class="function admonition">...</div>
+
+* ``seealso``:
+
+  will be created as a docutils.nodes.admonition node with the value
+  ``seealso`` in the nodes ``classes`` list.
+
+* ``versionchanged``:
+
+  will be created as a docutils.nodes.admonition node with the value
+  ``versionchanged`` in the nodes ``classes`` list.
+
+* ``versionadded``:
+
+  will be created as a docutils.nodes.admonition node with the value
+  ``versionadded`` in the nodes ``classes`` list.
+
+* ``deprecated``:
+
+  will be created as a docutils.nodes.admonition node with the value
+  ``deprecated`` in the nodes ``classes`` list.
+
+The markers of node types (roles)
+--------------------------------------
+
+Simplified roles currently provide no special marker.
\ No newline at end of file