#266 Creating labels (hyperlink targets) in description items

[Jellby]

It doesn't seem to be possible to add a hyperlink target to a description list element (see http://stackoverflow.com/questions/26003717/anchor-in-arbitrary-position-with-sphinx-restructuredtext for a sample). (See also https://bitbucket.org/birkenfeld/sphinx/issue/1581/creating-labels-hyperlink-targets-in).

With a normal (un)ordered list, this works, although it's not quite intuitive (it looks like the label belongs to Item 1):

Some text

.. class:: myclass


* Item 1
  Text

  .. _label:


* Item 2
  Text
* Item 3
  Text

but everything I've tried with a description list either breaks the assigned class, or drops the label, or assigns the label to the description rather than the definition.

[Günter Milde]

There is no obvious solution: How should consistent input look like if you want to label lists, list elements and list element content?

This is a limitation of the simple markup format.

You may use an inline internal target::

Item 2
  Text

_`Item 3`
  Text

The Stackoverflow question linked above mentions the problem of nested inline markup currently not supported: this is one more argument to make nested inline markup possible.

[Jellby]

Well, I would suggest that something like:

.. class:: myclass

**Term 1**
  Definition

.. _label_for_term_2:

*Term 2*
  Definition

should not break the list in two, or, maybe more in agreement with the current behaviour, that this should work, as it does for normal (un)ordered lists:

.. class:: myclass

**Term 1**
  Definition

  .. _label_for_term_2:

*Term 2*
  Definition

(note the label is indented), as far as I can see the label in this case is simply ignored.

[Günter Milde]

Suggestion 1 would be a clear non-compatible change of the rST syntax:

Any text whose indentation is less than that of the current level (i.e., unindented text or “dedents”) ends the current level of indentation.

-- docs/ref/rst/restructuredtext.txt

You might try starting a discussion about constructs that move out of the way (.. class:: directive and explicit hyperlink targets) beeing an exception to this rule on docutils-devel. (However, I don't think the case will be considered so important as to warrant a complication of the rules.)

Suggestion 2 works for XML:

* item 1

  .. _label_ul_item_2:


* item 2

Term 1
  Definition 1

  .. _label_dl_item_2:

Term 2
  Definition 2

the label is attached to item 2 as in the unordered list (see attachment).

The problem ist, that in HTML, there is no separate element for a definition list item and hence the id is dropped.

One could consider wrapping a definition list item into a div element with id (or class) set whenever there is a relevant argument present in the document tree. Would this solve your problem?

[Günter Milde]

About the "non-intuitive" syntax: The rST specification says:

The "class" directive sets the "classes" attribute value on its content
or on the first immediately following comment element.

I added a clarifying footnote:

This is also true, if the class directive is "nested" at the end of
an indented text block.

It allows the "classification" of individual list items (except the
first as a preceding class directive applies to the list as a whole).

with examples.

[Günter Milde]

Closing this for now.

You may check if there are other cases of dropped class values in the HTML writer. (The LaTeX writer drops class values in most places, because the concept of adding arguments to objects is unknown in the LaTeX syntax.)

David Goodger suggested an interesting extension to the "class" directive, that would allow "classification" of first list elements as well as table columns, rows, and cells:

a :parent: or :container: option, to assign the class to the
element containing the directive (the parent element). This option
could also take an argument, the element type for assignment, so a
class could be assigned to an arbitrary ancestor of the directive.

This could also be used in tables (":parent: entry" puts a class on a
cell; ":parent: row"; even ":parent: col" could be done, with a bit of
work).

See http://docutils.sourceforge.net/docs/dev/todo.html#misc-class &
http://article.gmane.org/gmane.text.docutils.devel/3165

However, this does not easily translate to internal hyperlink targets.