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

[Saunders, G. <gsa...@ea...>]

> -----Original Message-----
> From: David Goodger [mailto:go...@py...]=20
> Sent: March 3, 2003 3:54 PM
> To: Saunders, Graydon; doc...@so...
> Subject: Re: [Docutils-users] Multiple html classes per literal block?
>=20
>=20
> Saunders, Graydon wrote:
> > What I want to do is to have a code example which is included as a=20
> > literal block and which has a range of lines specifed as having a=20
> > different class name from the rest of the block, so it's=20
> > possible to=20
> > highlight some part of the code example as the interesting bit.
>=20
> Not a bad idea.  A directive could fit the bill.  For example::
>=20
>     .. literal::
>        :highlight: 2-3
>=20
>        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.

Yes.

>        The "highlight" option could take multiple line &
>        range arguments, comma-separated.  Is there
>        a standard for such notation?

Not that I know of.

I'd expect either 2..6,19..28
Or 2-6,10-28

> An alternative would be to number the lines of a literal=20
> block, to allow for textual references.  Something like this::
>=20
>     .. literal::
>        :numbered-lines:
>=20
>        line one
>        line two
>=20
> Would produce something like::
>=20
>     (1)    line one
>     (2)    line two

That seems potentially handy, but it's not a current need.

> > Ideally, one could specify multiple ranges per literal=20
> > block and the=20
> > associated class name extension so example 1 and example 2=20
> > can easily=20
> > have the same kind of highlighting for the same 'notice=20
> > this' things.
>=20
> I'm not following.  What's "associated class name extension"?=20
>  Please explain and provide examples.

Right now, when I use

.. Include:: <foo>
	:literal:

The result is the contents of <foo> in=20
<pre class=3D"literal-block"></pre> tags.

If I've got two different sets of lines marked 'interesting', I'd like
to have them have different class names so I can give them distinct
colours in the stylesheet.

So=20
.. literal::=20
	:highlight: 2-6,10-28

I'd want whatever tags results in the HTML to have
'class=3D"literal-block:', 'class=3D"literal-block-interesting-1"' and
'class=3D"literal-block-interesting-2"' or similar so there's something
for the stylesheet to reference.  Incrementing numbers seems to fit
pretty well with the feel of reStructured Text.

The *next* time there's a literal directive -
.. literal::
	:highlight: 4-12

I'd want the class associated with those nine lines to be
'class=3D"literal-block-interesting-1"'.

If it was
.. Literal::
	:highlight: -,4-12

I'd want the class associated with those nine lines to be
'class=3D"literal-block-interesting-2"'.

That make sense?  The hope is to have examples with consistent
highlighting colours for different kinds of interesting, even when every
kind of interesting isn't present in every example.

> > I don't think that's currently possible; if it is, I'd=20
> > appreciate to=20
> > be told how to do it.
>=20
> Neither are currently possible; they'd require=20
> implementation.  Patches are always welcome!

Unfortunately, I entirely lack the programmer nature.

> > I'm also unsure that it's necessarily an extension you'd care to=20
> > entertain; I'd like to advance strongly that it would be=20
> > very useful=20
> > for anyone trying to build documentation addressing that=20
> > theological=20
> > question of 'why'.
>=20
> I agree that it would be useful.  I'd be "willing to=20
> entertain" quite a bit, if implemented as a directive.  It's=20
> much easier than new syntax.

Well, considering that 'include' is already a directive, I'd have to be
feeling quite unhinged to sugguest a syntax change.

Not feeling that unhinged. :)

Thank you!