Re: [Docutils-develop] Re: pdf writer

[David G. <go...@us...>]

> On Wed, 29 May 2002, David Goodger wrote:
> > As I replied last time,
> >
> >     ``Node.walk`` & ``Node.walkabout`` call
> >     ``NodeVisitor.unknown_visit`` & ``.unknown_departure`` when
> >     unknown node types are encountered.
> >
> > You can implement the ``unknown_visit``/``unknown_departure``
> > methods of your ``NodeVisitor`` subclass to do whatever you like
> > (such as call ``node.astext()``).  If you choose to do this, I'd
> > recommend issuing a warning (a Python warning is OK, doesn't have
> > to be a system_message) saying "an unknown node (name) has been
> > encountered", otherwise it will be difficult to track down the
> > remaining unimplemented node types.
> >
> > This is only an interim solution though.  It's OK during
> > development, but the writer won't be complete until *all* node
> > types are handled in some way.  At that point, the
> > unknown_visit/unknown_departure methods should be removed, so that
> > later bugs *will* be noticed.

Engelbert Gruber wrote:
> A Python warning means what to you ?

The Python ``warnings`` module::

    import warnings
    warnings.warn("This is a warning.")

> And this is not an interim solution, as a user i want a document
> output and this has to contain every text, so i would leave the
> unknown_visit/departure in the writer. it does no harm if everything
> is known, but it gives at least illformatted output if something is
> unknown.

Leaving the unknown_visit/departure methods in the Writer *once it's
complete* is *not* an option.  It *will* do harm.  I'll spell it out
as explicitly and completely as I can.

During Writer development (i.e., while it's still in the sandbox),
having unknown_visit/departure methods is acceptable; you want to test
the code without getting exception tracebacks from node types you
haven't had time to implement yet.  The goal of the development is a
**complete** Writer, one that handles *all* standard Docutils nodes.
At this point, the Writer can be moved into the Docutils distribution.
Until the Writer is complete, it *will not* be moved into the
distribution.

Once Docutils is mature, new node types will be rare.  The ones that
*are* introduced will mostly be esoteric (all the basic ones are
already there) and therefore rarely used and perhaps not easily
noticed in the output.  When a new node class *is* introduced, *all*
Writers *must* be updated to support it.

However...

Let's imagine that a Writer is missed by accident and not updated with
support for the new node.  If that Writer contains catch-all
unknown_visit/departure methods, it would give *no sign* that support
for the new node type is missing.  The Writer would produce broken
output silently (i.e., without some kind of explicit indication that
"I don't know what an XYZ node is!"), which is *not* acceptable.  Such
a Writer could languish for a long time, producing broken output which
users may not notice, because of the esoteric nature of the new node,
or because presumably, the unknown_visit/departure methods would
produce some *approximation* of the correct output, like plain text.
Approximation is not good enough.  Rather, the Writer should raise an
exception if it hasn't been updated properly.

Leaving the catch-all unknown_visit/departure methods in a Writer is
dangerous.  It's similar to having try/except blocks that don't
explicitly specify exception classes (they'll catch *anything*, which
is usually not what you want).

But as I said before, in the interim (sandbox), anything goes.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/