Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.


#21 Add :valueasclass: option to role directive


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

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

This would render similar to:

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

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


  • David Goodger
    David Goodger

    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`?

  • 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

    Does that make more sense?

  • David Goodger
    David Goodger

    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.

  • 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