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
|