Re: [Docutils-users] Multiple html classes per literal block?

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

Saunders, Graydon wrote:
> What I want to do is to have a code example which is included as a
> literal block and which has a range of lines specifed as having a
> different class name from the rest of the block, so it's possible to
> highlight some part of the code example as the interesting bit.

Not a bad idea.  A directive could fit the bill.  For example::

    .. literal::
       :highlight: 2-3

       Here's the literal block, line 1 (first non-blank line).
       Line numbering would be 1-based, including end-points,
       so non-geeks could use it too.
       The "highlight" option could take multiple line &
       range arguments, comma-separated.  Is there
       a standard for such notation?

An alternative would be to number the lines of a literal block, to allow for
textual references.  Something like this::

    .. literal::
       :numbered-lines:

       line one
       line two

Would produce something like::

    (1)    line one
    (2)    line two

> Ideally, one could specify multiple ranges per literal block and the
> associated class name extension so example 1 and example 2 can easily
> have the same kind of highlighting for the same 'notice this' things.

I'm not following.  What's "associated class name extension"?  Please
explain and provide examples.

> I don't think that's currently possible; if it is, I'd appreciate to be
> told how to do it.

Neither are currently possible; they'd require implementation.  Patches are
always welcome!

> I'm also unsure that it's necessarily an extension you'd care to
> entertain; I'd like to advance strongly that it would be very useful for
> anyone trying to build documentation addressing that theological
> question of 'why'.

I agree that it would be useful.  I'd be "willing to entertain" quite a bit,
if implemented as a directive.  It's much easier than new syntax.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv