Re: [Docutils-develop] HTML Acronyms

[Jason D. <ja...@in...>]

On Fri, 2003-01-03 at 17:13, David Goodger wrote:
> [David Goodger]
> >> 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).
>                 ^
>                 I meant to say "*may* become obsolete"
> 
> [Jason Diamond]
> > This is what I did. It is ugly but not as much as in HTML. At least
> > the titles can be defined elsewhere.
> 
> (By "titles" I assume you mean roles [as in `interpreted text`:role:].
> Correct?  If not, please explain what you do mean.)

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.

> That's fine, but please be aware that the current internal
> representation will probably be ripped out and replaced before long.

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

> >> 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.
> > 
> > How will that work? Will acronyms and index entries use a different
> > syntax to differentiate themselves from each other?
> 
> No, they'll still use interpreted text syntax.  I meant that
> internally, acronyms will be <acronym> elements and index entries will
> be <index_entry> elements; there will be no <interpreted role="...">
> elements.  I don't plan on adding new syntax.

But you're letting people create new node types just by making up new
role names? Won't that make defining the DTD difficult? 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.

> > What if an acronym was also an index entry?
> 
> That's a tough one.  We're approaching the limitations of
> reStructuredText now.  Inline markup cannot be nested, so you would
> either have to choose one of the roles, or make up a new combined
> "acronym-index-entry" role.  The latter case could easily become quite
> complicated.
> 
> I suppose the interpreted text syntax *could* be extended for multiple
> roles, something like this::
> 
>     `interpreted text`:role1,role2:
> 
> But at first glance that seems exceedingly ugly to me.  Basically, if
> a document is so complex as to require nested inline markup, perhaps
> another markup system should be considered.  reStructuredText does not
> have the flexibility of XML (by design).

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.

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.

I'm not really pushing for these--just thought I'd throw them out there
to see what you might think. I'd like to see reST stay simple but still
be powerful enough to get most of what I'd like to do done.

Jason