Re: [Docutils-develop] HTML Acronyms

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

Jason Diamond wrote:
> I'm trying to add support to the html4css1 writer for acronyms. I want
> interpreted text that matches a known set of acronyms to output an
> <acronym> element instead of the default <span class="interpreted">
> element it outputs now. For example, `reST` should output <acronym
> title="reStructuredText">reST</acronym>.
> 
> I'm new to the docutils source code so was wondering what the best way
> to do this would be. I thought I'd add an --acronyms-file option to the
> writer, load the acronyms and their titles out of that file, and then
> check to see if the text for an interpreted node was one of those known
> acronyms. Is this an appropriate approach or should I be looking at
> implementing it via a transform? This makes sense to me since the
> acronym element I'm trying to output is specific to HTML.

There isn't a lot of support for interpreted text in Docutils yet.  It has
been a "future expansion" feature, but it looks like the future has arrived.
The main application of interpreted text has been the Python Source Reader,
which is making slow progress.  See PEP 258
(<http://docutils.sf.net/spec/pep-0258.html>) and
<http://docutils.sf.net/spec/pysource.html#interpreted-text> for details.

A quick & dirty way to implement what you want would be to indicate the role
of each acronym like this: "`reST`:acronym:" or "`reST`:a:".  This will put
the role into a doctree node attribute, which is easy to check for in code.
But the text is butt-ugly and this approach become obsolete (read on).

From <http://docutils.sf.net/spec/notes.html#restructuredtext-parser>:

    Alan Jaffray suggested (and I agree) that it would be sensible to:
    
    - have a directive to specify a default role for interpreted text
    - allow the reST processor to take an argument for the default role
    - issue a warning when processing documents with no default role
      which contain interpreted text with no explicitly specified role

(I just added "and/or command-line option" after "directive".)

An application (or document or processing run) could specify a default role,
so a ":role:" prefix or suffix wouldn't be required; plain `backquotes`
would be sufficient.

Ideally and eventually, the "interpreted" element will disappear from the
Docutils doctree.  In its place will be a customizable set of inline
elements including "acronym" and "index_entry", directly created by the
parser.

I won't be able to work on this for at least a week.  If you're interested
in helping out, please do!  If anything is unclear (and I'm sure there's
lots), please ask. 

-- 
David Goodger  <go...@py...>  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/