[Docutils-develop] [ docutils-Feature Requests-2970278 ] Add :valueasclass: option to role directive

[SourceForge.net <no...@so...>]

Feature Requests item #2970278, was opened at 2010-03-14 11:31
Message generated for change (Comment added) made by timehorse
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=422033&aid=2970278&group_id=38414

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: Jeffrey C. Jacobs (timehorse)
Assigned to: Nobody/Anonymous (nobody)
Summary: Add :valueasclass: option to role directive

Initial Comment:
It would be nice, for the purposes of a more flexible form of indexing such that all text adorned with a role that had this property would, in addition to its standard role classes, receive a class of the form role<text> in it's class list.  This would allow for easy dynamic HTML using CSS for any such text markup.  In other words:

.. role:: keyword
   :valueasclass:

If you remember :keyword:`apple` or :keyword:`pear`, you're almost there!

This would render similar to:

The output would be
  <paragraph>
     If you remember 
     <keyword class='roleapple'>
          apple
      or 
     <keyword class='rolepear'>
    , you're almost there!

Where further CSS could highlight text of class roleapple or rolepear as necessary.

----------------------------------------------------------------------

>Comment By: Jeffrey C. Jacobs (timehorse)
Date: 2010-03-16 06:45

Message:
I just gave you a real-world use case.  I said, I am writing a script as in
a radio play; but be it a stage play or a tele play or a screen play the
same applies.  When Actor A logs in or I render a copy of his script, I
want to highlight all times his character name appears; when Actor B
appears for this actress, I want her name to appear highlighted.  So how
would I do that; say I have 20 characters in my script, A - T; currently, I
need to write:

.. role:: characterA
   :class: characterA

.. role:: characterB
   :class: characterB

.. role:: characterC
   :class: characterC

.. Repeated for the other 17 characters.

And then in my script I have to write :characterA:`A` tells
:characterB:`B` that her hair is ugly just before :characterC:`C` walks in
the door.

Now, ignoring for a moment that character is itself rather wordy (I could
have chosen ch as the prefix but I wanted to be clear what is being said),
names will *not* be simply A, B, C; they will be Charles, Monica, Father,
and so on.  This means I have to write each name twice in the rst as well
as define a whole bunch of roles that do basically the same thing just so
that I can use CSS to highlight the given actors' parts.

Since I am currently facing this problem, I obviously have a very great
desire for this convenience.  Also, I'm familiar with the code and know it
won't be that difficult to implement or add that much time to processing:
simply an if to check if the flag is there and then some extra processing. 
As such, I will vote my own suggestion:

+1 because I already have a use for it

----------------------------------------------------------------------

Comment By: David Goodger (goodger)
Date: 2010-03-15 23:17

Message:
I'm asking for a real-world use case, not hypothetical.

Every change requires a cost/benefit analysis. This change seems
frivolous, with little real-world benefit, only adding complexity.

-1 so far.

----------------------------------------------------------------------

Comment By: Jeffrey C. Jacobs (timehorse)
Date: 2010-03-14 13:47

Message:
To answer the Use Case question, take the above example as one slice of
text that throughout refers to various pieces of fruit.  When this is
rendered as HTML, all uses of the words apple will have a class of
roleapple, all of pear, rolepear, etc.  Now, say the client web browser
clicks a button that makes all apples appear red and all pears appear
brown.  One could easily inject code at the CSS level without going through
the rigor-moral of grepping the HTML for all occurrences of keywords
'apple' or 'pear' and applying the highlight to them specifically before
page rendering.  It is a much cleaner notation than creating a role for
each keyword, keywordapple, keywordpear, etc, which would, IMHO, make the
rst unnecessarily wordy: :keywordapple:`apple` :keywordpear:`pear`, etc. 
This is a generic use case; a more specific one would be to highlight the
use of any character's name in a script such that :character:`Kevin` would
be a way to highlight the name Kevin, applying something like turing all
uses of this character's name red so that the actors could easily find the
action elements that were associated with them in the script.

Also, I think the 'role' prefex isn't specific enough on second thinking;
instead, I would say the class name would be build <custom role name>
<class-mangled text>.

And in the case of your second point, I would suggest the name mangling
would work just like normal class decoration promotion with the addition
that the space is part of the class name and so should also get marked up:
class="keywordappleandpear ...", for instance.  In effect, it should be
noted that two different texts may mangle to the same class in which case
you might have to still specify an old-style role-with-class for these
elements, but if a particular combination is common enough you could just
define a different prefix, such as:

.. role:: keyword2
   :valueasclass:

Does that make more sense?

----------------------------------------------------------------------

Comment By: David Goodger (goodger)
Date: 2010-03-14 11:52

Message:
I don't see the point. What would this gain us? What is the use case?

What should the class be if the text is more than one word? IOW,
:keyword:`apple and pear`?

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=422033&aid=2970278&group_id=38414