Re: [Docutils-develop] HTML Acronyms

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

Jason Diamond wrote:
> I want to translate "`reST`:acronym:" into "<acronym
> title='reStructuredText'>reST</acronym>". The value of the title
> attribute has to be defined out-of-band since you can't parameterize
> interpreted text. Right now I have them in a separate file but I'm
> experimenting with creating a directive that will use some form of reST
> syntax to let you define them.

I understand.  Sounds reasonable.  What happens when an attribute without a
lookup table entry comes along?

> So instead of an `interpreted` node, I'll have an `acronym` node? I'll
> be moving my code to `visit_acronym` and `depart_acronym`?

Yes.

> But you're letting people create new node types just by making up new
> role names?

No, not arbitrarily.  Authors would have to choose from a pre-determined set
of roles, each having pre-existing software support.  For instance, your
acronym example would have to have support in the parser, to create the
"acronym" elements and associate "title" attributes from a lookup table.

Interpreted text with unknown roles would generate errors.

> Won't that make defining the DTD difficult?

It would be impossible, which is a good indication that it's a bad approach
;).

> I like the interpreted/role approach. It would be nice if the walk/walkabout
> methods looked for the role attribute on intrepreted nodes, though. They could
> invoke `visit_interpreted_acronym` or `visit_interpreted_index_entry`
> depending on the role attribute and fall back to `visit_interpreted` in case
> the extended method doesn't exist.

Interesting idea.  In the scheme I'm considering though, there won't be any
"interpreted" elements left in the doctree by the time the Writer sees it.

Interpreted text is just syntax; the semantics haven't been finalized or
implemented yet.  The current "interpreted" element is merely a placeholder
for testing purposes and will disappear.  It's like the directive syntax.
Originally there was a generic "directive" element (before there was support
for directive processing in the parser), but it's gone now.  It's the same
situation for interpreted text.

> How about this::
> 
>     `interpreted text`:role1:role2:
> 
> Could we parameterize roles like this::
> 
>     `interpreted text`:role1(foo=bar):role2(baz=quux):
> 
> Yes, it's ugly. Just a different kind of ugly compared to XML.

These are possibilities, and I'll note them.  But they're too complex for my
liking.  I really want to avoid complex inline markup.

> The reason I was thinking about parameters (or attributes) was to
> "override" a defined acronym::
> 
>     `CSS`:acronym:
> 
> could produce::
> 
>     <acronym title="Cascading Style Sheets">CSS</acronym>
> 
> by default but::
> 
>     `CSS`:acronym(title=Content Scrambling System):
> 
> could produce::
> 
>     <acronym title="Content Scrambling System">CSS</acronym>
> 
> when writing about DVDs and copy protection.

My first inclination would be to use the existing substitution/directive
mechanism for something like this::

    `CSS`:acronym: is used for HTML, and |CSS| is used for DVDs.

    .. |CSS| acronym:: Content Scrambling System

> I'm not really pushing for these--

Good!

> just thought I'd throw them out there to see what you might think.

The effort is appreciated.

> I'd like to see reST stay simple but still
> be powerful enough to get most of what I'd like to do done.

I don't mind if directives are used for the gnarly stuff, but I'm loathe to
reduce readability by adding inline markup complexity.

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