Dropdowns: support improved grammar and value descriptions

[josteinaj]

From https://github.com/daisy/pipeline-mod-braille/pull/72#issuecomment-174959831:

However the paragraph below that says that the a:documentation should not have any child elements. So maybe instead of name and description do first line vs. next lines?

Ok. Yeah, that would work. And it would presumably be parsed as markdown the same way as for the script/template documentation. And since "If an a:documentation element does not have a preceding sibling element from the RELAX NG namespace, then the specified documentation applies to the parent element", we should probably drop multi-language support? So then this would be valid:

<choice id="dtbook-to-pef:braille-translator">

    <value>celia</value>
    <documentation xmlns="http://relaxng.org/ns/compatibility/annotations/1.0" xml:space="preserve">
        Celia

        [Celia](celia.fi) is a Finnish state-owned special library which produces and provides literature in accessible formats.
    </documentation>

    <value>dedicon</value>
    <documentation xmlns="http://relaxng.org/ns/compatibility/annotations/1.0" xml:space="preserve">Dedicon
Dedicon is a **Dutch** special library which produces and provides literature in accessible formats.</documentation>

    <value>mtm</value>
    <!-- no name/description, but it's ok. documentation belongs to first preceding sibling which must be a <value> -->

    <value>nlb</value>
    <documentation xmlns="http://relaxng.org/ns/compatibility/annotations/1.0" xml:space="preserve">NLB</documentation>
    <!-- nlb only has a name -->

    (...)
</choice>

[bertfrees]

Does this mean I have to change the descriptions in the scripts now, are will both work?

[josteinaj]

There shouldn't be a need to update the descriptions unless you want value descriptions.

[bertfrees]

Like for example https://github.com/snaekobbi/pipeline-mod-nlb/blob/master/src/main/resources/xml/xml-to-pef.xpl#L15.

[josteinaj]

Yeah, you can see this datatype test:

• braille-translator.xml
• JUnit assertions

So both kinds of documentation are allowed. The "first-following-element" documentation is preferred over the "top-of-document" documentation when both are present in the requested language. (The multi-language feature is not something I expect we'll be using but it's there anyway.)

[bertfrees]

Cool.

Well I can see how the multi-language thing could be useful: if for example Davy want to see what options are available in the Norwegian script, he'll ideally want to see the descriptions in English.

[josteinaj]

Yeah, I'd have to add multi-language support to the Web UI first though. The translation currently used is:

1. the one with no language, if present, otherwise...
2. the one with english language, if present, otherwise...
3. an arbitrary language is picked

The Web UI would have to specify a preferred language.