sandbox/tibs/pysource/group-notes.txt

   1 Adding <group>, losing <package_section> and their ilk
   2 ======================================================
   3
   4 :Author: Tibs
   5 :Date: 2001-11-18
   6
   7 Background
   8 ----------
   9 I am currently writing software that will take information from
  10 Python source files, produce a DPS node tree therefrom, and allow
  11 the user to generate HTML from that.
  12
  13 My initial implementation produced a *variant* of the DPS node
  14 tree, which contained many structures that related closely to the
  15 information derived from Python - for instance, something like::
  16
  17     <py_class name="Fred">
  18         <docstring>
  19             This is a very silly class.
  20         <py_attr_list>
  21             <py_attr name="jim">
  22         <py_method "name="method">
  23
  24 For various reasons, the (implicit) DTD wasn't shaping up very
  25 like that proposed by David Goodger, so I asked about the
  26 possibility of amending the "standard" DTD. This led to a
  27 discussion of how the flow of information through a DPS processor
  28 should actually work, with the result being David's diagram
  29 [#diagram]_::
  30
  31   +--------+     +--------+     +------------+     +--------+
  32   | READER | --> | linker | --> | transforms | --> | WRITER |
  33   +--------+     +--------+     +------------+     +--------+
  34       |                          TOC, index,            |
  35       |                          etc. (optional)        |
  36   +--------+                                       +--------+
  37   | PARSER |                                       | filer  |
  38   +--------+                                       +--------+
  39
  40 David also made the point that, within this plan, the result of
  41 the ``linker`` phase is a normal DPS tree, which can be
  42 transformed with any of the "standard" transformation tools (for
  43 instance, to resolve automatic footnotes), and then output with
  44 any writer.
  45
  46 Whilst David's diagram is not *quite* how I see the process, it's
  47 close enough for this purpose. Thus pydps [#pydps]_ might be shown
  48 as::
  49
  50   +--------+     +--------------+     +------------+     +---------+
  51   | READER | --> | transform.py | --> | transforms | --> | html.py |
  52   +--------+     +--------------+     +------------+     +---------+
  53       |                                                      |
  54   +----------+                                     +---------------+
  55   | visit.py |                                     | buildhtml.py  |
  56   +----------+                                     +---------------+
  57
  58 The "READER" is implicit in the main utility (currently
  59 ``pydps.py``), and locates the relevant Python files. It then
  60 uses ``visit.py`` to generate a tree representing the Python code
  61 (the Python ``compiler`` module, standard with Python 2.2 and
  62 above, but in ``Tools`` before that, is used).
  63
  64 ``transform.py`` (which, by David's diagrams, should maybe be
  65 called ``link``) transforms that information into a proper DPS
  66 node tree. At the time of writing, no transformations are done.
  67
  68 Finally, HTML is output from the DPS node tree by ``html.py``.
  69
  70 So, in summary:
  71
  72    1. ``transform.py`` generates a *normal* DPS tree. It doesn't
  73       use any "odd" nodes (except <group> - but we'll discuss
  74       that later on). This means that it should be possible to
  75       plug in any other writer, and produce a different format as
  76       output - a very significant advantage.
  77
  78    2. ``html.py`` expects to be given a *normal* DPS tree. This
  79       means that it should be usable by any other utility that
  80       also provides a normal DPS tree - again an advantage.
  81
  82 The problem
  83 -----------
  84 But there is a clash in requirements here. Whilst it is very nice
  85 to be able to represent the Python information as "normal" DPS
  86 (guaranteeing that anyone can do useful things with it), there is
  87 some need to transfer information that goes beyond that. There
  88 are two main reasons for wanting to do this:
  89
  90   * Data mining
  91   * Presentation
  92
  93 For the first, although DPS/reST/pydps is primarily about
  94 producing human-viewable documentation, it might also be nice to
  95 be able to extract parts of it automatically, for various
  96 purposes - for instance, retrieve just the information about
  97 which classes inherit from other. This information will, in part,
  98 be obvious from the text chosen within the document (a title like
  99 "Class Fred" might be taken to be useful, for instance!), but it
 100 would be nice to give a bit more help.
 101
 102 For the second, it's relatively difficult to produce better
 103 layout for DPS Python documentation without more information to
 104 work on. If one uses the (rather garish) default presentation
 105 produced by pydps (and no, I'm not saying that's a *nice*
 106 presentation, but it is the one I've got as an example), it is
 107 clearly useful to be able to:
 108
 109   1. group together the package/class/method/etc title and its
 110      full name/path/whatever
 111
 112   2. group together a method or function's signature and its
 113      docstring
 114
 115 David's original approach to this was to introduce a host of
 116 Python specific tags into ``nodes.py`` [#nodes]_ - for instance::
 117
 118     package_section
 119     module_section
 120     ...
 121     instance_attribute_section
 122     ...
 123     parameter_item
 124     parameter_tuple
 125     ...
 126     package
 127     module
 128     class_attribute
 129
 130 There are several problems with approach. Perhaps the most
 131 serious is that *all* generic DPS writers need to understand
 132 this host of elements that are only relevant to Python. Clearly,
 133 someone writing a writer for other purposes may be reluctant to
 134 go to this (to them) redundant effort.
 135
 136 From my point of view, an immediate problem is that the set of
 137 elements is not *quite* what I want - which means working towards
 138 a set of patches for ``nodes.py`` and the relevant DTD, and
 139 getting David to agree to them (well, that last is a useful
 140 process to have in place, but still). Since I'm not likely to get
 141 it right immediately, this is a repetitive process.
 142
 143 Lastly, one might imagine someone from another programming
 144 language domain adopting DPS/reST. One can expect them to be
 145 frustrated if the set of constructs provided for Python doesn't
 146 quite match the set of constructs required to describe their
 147 language in a natural manner.
 148
 149 Luckily (!), I have a counter proposal, which hopefully keeps the
 150 baby and just loses the bath water.
 151
 152 Groups and "style"
 153 ------------------
 154 The first thing that I realised was that, for convenience of
 155 output at least, I wanted to be able to group elements together -
 156 or, in terms of the DPS tree, insert an arbitrary "subroot"
 157 within the tree to 'abstract' a branch of the tree.
 158
 159 This is particularly useful for linking together the parts of the
 160 text that deal with (for instance) attribution, or unusual
 161 globals, without having to embed yet another section.
 162
 163 There is, of course, precedent. HTML provides <div> and <span> -
 164 one for "structural" elements, and one for inline elements (I
 165 forget which is which), and TeX and LaTeX are well-known for
 166 their use of grouping (e.g., the ``\begin{xxx}`` and
 167 ``\end{xxx}`` in LaTeX).
 168
 169 I don't consider it worth making the <div>/<span> distinction in
 170 the context of a tree - it is perfectly evident what is beingp
 171 grouped from the elements themselves.
 172
 173 Once one has a <group> element, it is natural to annotate it with
 174 *what* it is a group of/for. I chose the arbitrary term "style" -
 175 partly because it is not used in HTML/XML for any purpose I am
 176 aware of.
 177
 178 And once one has the "style" attribute, it becomes possible to
 179 use it elsewhere - most notably in <section> elements, saving the
 180 need for a myriad of different sections for different purposes.
 181
 182 In these instances, it is perhaps acting more like the "class"
 183 attribute in HTML - indicating, to some extent, meaning, but
 184 aimed mostly at presentation (via CSS).
 185
 186 The other obvious place to use it is in the automatically
 187 generated text for things like names, where (at least
 188 pre-"combing"/transformation) one is "pretending" to have
 189 assigned a role (just as a person might in a docstring) (but see
 190 [#style]_).
 191
 192 Summary
 193 -------
 194 Current DPS defines many element types for use in Python code
 195 representation.
 196
 197 However, there are major advantages in only using the "simple"
 198 DPS nodes for all purposes.
 199
 200 This becomes simple and practical given a single extra, general
 201 purpose, element: <group>.
 202
 203 Furthermore, adding a standard attribute called "style" (or
 204 perhaps "role" - see [#style]_) seems to fulfil any other
 205 outstanding requirements.
 206
 207 References
 208 ----------
 209 .. [#diagram] in email by David Goodger to Doc-SIG, dated
 210    21 September 2001 04:31, "Re: [Doc-SIG] DPS components".
 211
 212 .. [#style] Hmm - maybe "style" should be "role", to match
 213    with the way that a ``:role:`of something``` gets handled...
 214
 215 .. [#pydps] Normally to be found at
 216    http://www.tibsnjoan.co.uk/reST/pydps.tgz,
 217    although note that this is not currently up-to-date.
 218
 219 .. [#nodes] dps/dps/nodes.py in the DPS distribution
 220    (``dps.nodes`` if one is importing it).