sandbox/grubert/making_a_writer.txt

   1 ===============
   2 Making a writer
   3 ===============
   4
   5 :Author: engelbert gruber
   6 :Contact: grubert@users.sourceforge.net
   7 :Date: $Date$
   8 :Web site: http://docutils.sourceforge.net/
   9
  10 .. contents::
  11
  12 Introduction
  13 ============
  14
  15 This might become a document sometime, is now a FAQ, collected
  16 from docutils-develop@lists.sourceforge.net.
  17
  18 This should give help in making a writer for the python docutils.
  19 Writers are backends writing to a dedicated format.
  20
  21 General description
  22 ===================
  23
  24 from PEP-0258:
  25
  26   Writers produce the final output (HTML, XML, TeX, etc.). Writers translate
  27         the internal document tree structure into the final data format, possibly
  28         running Writer-specific transforms first.
  29
  30         Responsibilities:
  31
  32   *     Run transforms over the doctree(s).
  33   *     Translate doctree(s) into specific output formats.
  34         * Transform references into format-native forms.
  35         * Write the translated output to the destination I/O.
  36
  37 or in other words
  38
  39   By the time the document gets to the Writer, it should be in
  40   final form.  The Writer's job is simply (and only) to translate from
  41   the Docutils doctree structure to the target format.  Some small
  42   transforms may be required, but they should be local and
  43   format-specific.
  44
  45
  46 The smallest writer
  47 ===================
  48
  49 Next to come. This should be a writer module where everything is done
  50 in unimplemented.
  51
  52
  53 Methods
  54 =======
  55
  56 Empty methods
  57 -------------
  58
  59 It is legal and does not hint to missing functionality, when a
  60 method only implements pass, it just means that this calls information
  61 is not used, the actual content is usually produced between ``visit_*``
  62 and ``depart_*`` calls. e.g.::
  63
  64     def visit_Text(self, node):
  65         self.body.append(self.encode(node.astext()))
  66
  67     def depart_Text(self, node):
  68         pass
  69
  70 As long as there is no need for termination depart_Text is ok.
  71
  72 Fallback methods
  73 ----------------
  74
  75 If derived from NodeVisitor
  76
  77 * unknown_visit, unknown_departure
  78
  79 Deriving from SparseNodeVisitor means everything might pass.
  80
  81 GenericNodeVisitor adds
  82
  83 * default_visit, default_depart.
  84
  85 unimplemented_visit( self, node) seams to be there for both.
  86
  87 Each might raise NotImplementedError(describe_here),
  88
  89 General Problems
  90 ----------------
  91
  92 html pages are more like papyrus rolls, if one wants to go more usual
  93 paper formats some things are different or not.
  94
  95 * page headings
  96 * page numbers
  97
  98
  99 Problems
 100 --------
 101
 102 In latex2e writer this looks awful to me, but as i understand this ensures
 103 that e.g. http addresses are not only text.
 104
 105 Maybe this is due to the fact that self.docinfo is used, if one would remove
 106 it context might be unecessary.
 107
 108 ::
 109
 110     def visit_docinfo_item (...):
 111         ...
 112         else:
 113             ##self.head.append('\\%s{%s}\n'
 114             ##            % (name, self.attval(node.astext())))
 115             self.docinfo.append('\\textbf{%s} &\n\t' % name)
 116             self.context.append(' \\\\\n')
 117             self.context.append(self.docinfo)
 118             self.context.append(len(self.body))
 119             ##raise nodes.SkipNode
 120
 121     def depart_docinfo_item(self, node):
 122         size = self.context.pop()
 123         dest = self.context.pop()
 124         tail = self.context.pop()
 125         tail = self.body[size:] + [tail]
 126         del self.body[size:]
 127         dest.extend(tail)
 128
 129
 130 Notes on Classes
 131 ----------------
 132
 133 To be completed.