#95 Multiterm definition items

[Kirill Smelkov]

Following discussion on docutils-users about multi-term definition list items [1,2],
I'am also posting my patches here, just to make sure they don't get lost.

Thanks,
Kirill

[1] https://sourceforge.net/mailarchive/forum.php?thread_name=F406FAD0-FC0D-425E-B9DB-EC6D959E8371%40tibsnjoan.co.uk&forum_name=docutils-users
[2] http://permalink.gmane.org/gmane.text.docutils.user/6765

[Kirill Smelkov]

0001-rst-Add-support-for-parsing-multiterm-definitions.patch

[Kirill Smelkov]

[Kirill Smelkov]

[Kirill Smelkov]

[Kirill Smelkov]

(how the end result looks like)

[Kirill Smelkov]

Example of multi-term definition items in literature:

http://lwn.net/images/pdf/LDD3/ch02.pdf , page 26(40)

[Günter Milde]

My suggestion is to use empty comments as content for all but the last multi-def term:

function1(some,arguments)
   Behaves like this

function2(some,arguments)
   ..
function3(some,other,arguments)
   ..
function4(some,variant,on,those)
   All behave in this other way, which is best described in
   one place together. Blah blah blah...

The resulting HTML5 looks very much like your example. For LaTeX you would need to define a custom definition list style.

[Günter Milde]

See also [feature-requests:#60] for allowing multi-term definitions in the doctree and writer support. It is solved by commit [r9747] which changes the DTD, documentation, and nodes.definition_list_item.content_model to allow multiple terms for one definition.

[Günter Milde]

The syntax implemented in the proposed patch has one drawback explained by David Goodger in the original docutils-users thread:

Perhaps we could define
definition list items as one term per line, so this input:

term 1
term 2
    definition

would produce this output:

<definition_list>
    <definition_list_item>
        <term>
            term 1
        <term>
            term 2
        <definition>
            <paragraph>
                definition

The current output is:

<paragraph>
    term 1
    term 2
<system_message level="3" line="3" source="<stdin>" type="ERROR">
    <paragraph>
        Unexpected indentation.
<block_quote>
    <paragraph>
        definition

I think this type of mistake is currently quite common. For example,
a paragraph followed immediately (no blank line) by an indented bullet
list. If we make this change to definition lists a lot of those
helpful errors will disappear, and potentially unhelpful definition
lists will take their place. Will the new behavior seem surprising or
ambiguous?