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