docs/ref/transforms.txt

   1 =====================
   2  Docutils Transforms
   3 =====================
   4
   5 :Author: David Goodger
   6 :Contact: docutils-develop@lists.sourceforge.net
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This document has been placed in the public domain.
  10
  11
  12 .. contents::
  13
  14 Transforms change the document tree in-place, add to the tree, or prune it.
  15 Transforms resolve references and footnote numbers, process interpreted
  16 text, and do other context-sensitive processing. Each transform is a
  17 subclass of ``docutils.tranforms.Transform``.
  18
  19 There are `transforms added by components`_, others (e.g.
  20 ``parts.Contents``) are added by the parser, if a corresponding directive is
  21 found in the document.
  22
  23 To add a transform, components (objects inheriting from
  24 Docutils.Component like Readers, Parsers, Writers, Input, Output) overwrite
  25 the ``get_transforms()`` method of their base class. After the Reader has
  26 finished processing, the Publisher calls
  27 ``Transformer.populate_from_components()`` with a list of components and all
  28 transforms returned by the component's ``get_transforms()`` method are
  29 stored in a `transformer object` attached to the document tree.
  30
  31
  32 For more about transforms and the Transformer object, see also `PEP
  33 258`_. (The ``default_transforms()`` attribute of component classes mentioned
  34 there is deprecated. Use the ``get_transforms()`` method instead.)
  35
  36 .. _PEP 258: ../peps/pep-0258.html#transformer
  37
  38
  39 Transforms Listed in Priority Order
  40 ===================================
  41
  42 Transform classes each have a default_priority attribute which is used by
  43 the Transformer to apply transforms in order (low to high). The default
  44 priority can be overridden when adding transforms to the Transformer object.
  45
  46
  47 ==============================  ============================  ========
  48 Transform: module.Class         Added By                      Priority
  49 ==============================  ============================  ========
  50 misc.class                      "class" (d/p)                 210
  51
  52 references.Substitutions        standalone (r), pep (r)       220
  53
  54 references.PropagateTargets     standalone (r), pep (r)       260
  55
  56 frontmatter.DocTitle            standalone (r)                320
  57
  58 frontmatter.DocInfo             standalone (r)                340
  59
  60 frontmatter.SectSubTitle        standalone (r)                350
  61
  62 peps.Headers                    pep (r)                       360
  63
  64 peps.Contents                   pep (r)                       380
  65
  66 universal.StripClasses...       Writer (w)                    420
  67
  68 references.AnonymousHyperlinks  standalone (r), pep (r)       440
  69
  70 references.IndirectHyperlinks   standalone (r), pep (r)       460
  71
  72 peps.TargetNotes                pep (r)                       520
  73
  74 references.TargetNotes          peps.TargetNotes (t/p)        0
  75
  76 misc.CallBack                   peps.TargetNotes (t/p)        1
  77
  78 references.TargetNotes          "target-notes" (d/p)          540
  79
  80 references.Footnotes            standalone (r), pep (r)       620
  81
  82 references.ExternalTargets      standalone (r), pep (r)       640
  83
  84 references.InternalTargets      standalone (r), pep (r)       660
  85
  86 parts.SectNum                   "sectnum" (d/p)               710
  87
  88 parts.Contents                  "contents" (d/p),             720
  89                                 peps.Contents (t/p)
  90
  91 universal.StripComments         Reader (r)                    740
  92
  93 peps.PEPZero                    peps.Headers (t/p)            760
  94
  95 components.Filter               "meta" (d/p)                  780
  96
  97 universal.Decorations           Reader (r)                    820
  98
  99 misc.Transitions                standalone (r), pep (r)       830
 100
 101 universal.ExposeInternals       Reader (r)                    840
 102
 103 references.DanglingReferences   standalone (r), pep (r)       850
 104
 105 universal.Messages              Writer (w)                    860
 106
 107 universal.FilterMessages        Writer (w)                    870
 108
 109 universal.SmartQuotes           Parser                        850
 110
 111 universal.TestMessages          DocutilsTestSupport           880
 112
 113 writer_aux.Compound             newlatex2e (w)                910
 114
 115 writer_aux.Admonitions          html4css1 (w),                920
 116                                 latex2e (w)
 117
 118 misc.CallBack                   n/a                           990
 119 ==============================  ============================  ========
 120
 121 Key:
 122
 123 * (r): Reader
 124 * (w): Writer
 125 * (d): Directive
 126 * (t): Transform
 127 * (/p): Via a "pending" node
 128
 129
 130 Transform Priority Range Categories
 131 ===================================
 132
 133 ====  ====  ================================================
 134  Priority
 135 ----------  ------------------------------------------------
 136 From   To   Category
 137 ====  ====  ================================================
 138    0    99  immediate execution (added by another transform)
 139  100   199  very early (non-standard)
 140  200   299  very early
 141  300   399  early
 142  400   699  main
 143  700   799  late
 144  800   899  very late
 145  900   999  very late (non-standard)
 146 ====  ====  ================================================
 147
 148
 149 Transforms added by components
 150 ===============================
 151
 152
 153 readers.Reader:
 154   | universal.Decorations,
 155   | universal.ExposeInternals,
 156   | universal.StripComments
 157
 158 readers.ReReader:
 159   None
 160
 161 readers.standalone.Reader:
 162   | references.Substitutions,
 163   | references.PropagateTargets,
 164   | frontmatter.DocTitle,
 165   | frontmatter.SectionSubTitle,
 166   | frontmatter.DocInfo,
 167   | references.AnonymousHyperlinks,
 168   | references.IndirectHyperlinks,
 169   | references.Footnotes,
 170   | references.ExternalTargets,
 171   | references.InternalTargets,
 172   | references.DanglingReferences,
 173   | misc.Transitions
 174
 175 readers.pep.Reader:
 176   | references.Substitutions,
 177   | references.PropagateTargets,
 178   | references.AnonymousHyperlinks,
 179   | references.IndirectHyperlinks,
 180   | references.Footnotes,
 181   | references.ExternalTargets,
 182   | references.InternalTargets,
 183   | references.DanglingReferences,
 184   | misc.Transitions,
 185   | peps.Headers,
 186   | peps.Contents,
 187   | peps.TargetNotes
 188
 189 parsers.rst.Parser
 190   universal.SmartQuotes
 191
 192 writers.Writer:
 193   | universal.Messages,
 194   | universal.FilterMessages,
 195   | universal.StripClassesAndElements
 196
 197 writers.UnfilteredWriter
 198   None
 199
 200 writers.latex2e.Writer
 201   writer_aux.Admonitions
 202
 203 writers.html4css1.Writer:
 204   writer_aux.Admonitions
 205
 206 writers.odf_odt.Writer:
 207   removes references.DanglingReferences