Re: [Docutils-develop] Transforms...?

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Adam Chodorowski wrote:
> I (will) have several little larger reST documents on a website and
> I want to construct an index page with short descriptions and a link
> to the full document. So I thought I'd simply extract the abstract /
> introduction section of those documents for the short description on
> the index page to avoid duplication and ease maintanence.
> 
> The idea is to churn through the documents twice: the first pass
> creates the HTMl documents in full, while the second pass applies
> this filter/transform to get the abstract and adds it to the index
> page. 

I assume that there's more to the index file than just the abstracts
(such as introductory material, and perhaps repeated wrappers around
abstracts).  I can think of several ways to do what you describe:

1. First process each document individually, writing out each result
   file as usual.  Then process the index file, which contains special
   references (directives), one per document, which cause the
   documents to be fully parsed a second time each and extract the
   "abstract" topics and insert them into the body of the index
   document.

   This would require some kind of "extraction" directives for the
   index document.

2. Store the abstracts as separate files, which are inserted into both
   the individual documents and into the index file with "include"
   directives (not yet implemented).

   This would require a new "include" directive (which is already on
   the To Do list).

3. As in (1), except process all of the individual documents in a
   single process, storing the extracted abstracts in a list (so the
   documents don't have to be processed a second time), and parse and
   assemble the index file last.

   This would require a new specialized front-end, along with at least
   a placeholder directive to locate the insertion-points for
   abstracts.

4. Write a full-blown templating system for Docutils.  I think
   Python's ht2html.py is a good model: simple but effective.  Either
   add programmability through a pre-processor like YAPTU or with
   directives like "repeat".  Very vague ideas at this point.

Which were you thinking of?

> Another thing I would like to do is to either add templating support
> to the HTML writer, or write a "fragment" HTML writer (which would
> only write out the body of the document, so you can wrap it in your
> own header/footer for layout (navigation bar etc)). But that's a
> different topic. :)

The HTML writer already exposes the components, so you can just grab
the document body (everything inside but not including <body> &
</body>).  Use ``docutils.io.StringIO`` for the "destination_class"
parameter of ``docutils.core.Publisher.__init__`` to avoid writing a
file.  (Hmm, idea: NullIO class.)

However, the idea of custom headers & footers is what inspired the
"decoration" element (which contains "header" & "footer" elements).
It hasn't been fully developed yet.

>>> Also, I noticed that there seems to be some provision for language
>>> localization.
...
> The --language option is supposed to be used for this?

Yes.

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