Re: [Docutils-develop] Re: pdf writer

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

Engelbert Gruber wrote:
>>> i recognized a new function supports in the writer:
>>> means the parser could ask the writer if it supports a certain
>>> construct and if not might use some other ?
>>
>> No, writers should support all elements defined in docutils.nodes.
> 
> everything derived from Element ?

Actually, everything derived from Node, except Element and TextElement
(classes in docutils.nodes).

> how should i know :-)

The docs should tell you, and if they don't, that's a bug.  In this
case, it's clearly a bug.  So you find out by asking questions, which
you've just done; thanks.  This prods me into updating the internal
docs, which I've now done.  See the changes to
docutils/writers/__init__.py.

Please continue to ask questions; it helps me pinpoint where
documentation is lacking (or perhaps more precisely, where the general
lack of documentation is most strongly and immediately felt).  Also,
you (and others) are using the code in ways I haven't anticipated, so
you'll find places where the code needs tweaking, reworking, or
expansion.  That's great for the project; keep those questions and bug
reports coming!

> does anyone know the automatic way to get the list ?

``docutils.nodes.node_class_names`` is a list of all concrete node
classes.  Here's some code to derive the list::

    from docutils import nodes
    from types import ClassType
    node_class_names = []
    for x in dir(nodes):
        c = getattr(nodes, x)
        if type(c) is ClassType and issubclass(c, nodes.Node) \
               and len(c.__bases__) > 1:
            node_class_names.append(x)

I've added a test to confirm that the stored list stays up to date (in
test/test_nodes.py).

> should but might not do always, as new elements are added
> not all writers will support immediatly and we should have a way
> to get documents out anyway.

If a new node type is added, all writers should be updated accordingly
(if a writer is not updated, it's a bug).  Once a writer has been
accepted into core Docutils, it's the responsibility of whoever adds
the new node type (probably me) to update all the writers.  I'd be
happy to help with writers in the sandbox too.

> (your modification os NodeVisitor should enable fallback elements in
> writers).

``Node.walk`` & ``Node.walkabout`` call ``NodeVisitor.unknown_visit``
& ``.unknown_departure`` when unknown node types are encountered.
These can be overridden if you want to get fancy, but I don't see the
point.  Better to get explicit feedback (exception tracebacks) if your
code isn't complete.  That's what testing is for.

>> only writers supporting HTML will include the meta tag, others
>> will discard it.  (See the docstring of
>> ``docutils.transforms.components.Filter`` for a detailed
>> explanation.)
>
> should this be the meta information in a pdf file and maybe a
> comment in latex or pdf metainformation in pdflatex ?

Could be.  I don't know much about PDF or LaTeX.  The "meta" directive
was intended for HTML, so I wouldn't be surprised if it doesn't match
the PDF idea of metadata.

-- 
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/