===============
Making a writer
===============

:Author: engelbert gruber
:Contact: grubert@users.sourceforge.net
:Date: $Date: 2002-11-16 03:50:51 +0100 (Sa, 16. Nov 2002) $
: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.