diff options
Diffstat (limited to 'sandbox/grubert/making_a_writer.txt')
| -rw-r--r-- | sandbox/grubert/making_a_writer.txt | 133 |
1 files changed, 0 insertions, 133 deletions
diff --git a/sandbox/grubert/making_a_writer.txt b/sandbox/grubert/making_a_writer.txt deleted file mode 100644 index 4d76b5170..000000000 --- a/sandbox/grubert/making_a_writer.txt +++ /dev/null @@ -1,133 +0,0 @@ -=============== -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. |