[repository schema] Define documentation purposes and add standard purposes

[kleihan]

The schema has an optional attribute purpose for documentation elements and defines a few standard purposes. A user may add to the list as it is extensible.

    <xs:simpleType name="purpose_t">
        <xs:annotation>
            <xs:documentation>Extensible annotation purposes</xs:documentation>
        </xs:annotation>
        <xs:union memberTypes="fixr:purpose_enum xs:string"/>
    </xs:simpleType>

The standard purposes are currently SYNOPSIS, ELABORATION, EXAMPLE, DISPLAY. The specification only lists them but does not offer a definition.

Multiple languages can be supported by specifying the language of each element in its langId attribute. 
Also, multiple categories of documentation are supported by populating the purpose attribute. 
Suggested values of purpose include “SYNOPSIS”, “ELABORATION”, “EXAMPLE”, and “DISPLAY”.

It is proposed to define DISPLAY as the purpose to provide a more elaborate name other than the value of the name attribute, for example (taken from #193):

<fixr:message msgType="F" name="OrderCancelRequest">
  ...
  <fixr:annotation>
    <fixr:documentation purpose="DISPLAY">
      Cancel Order Message (Specifying Order Acceptance Number)</fixr:documentation>
  </fixr:annotation>
</fixr:message>

It is further proposed to standardize the following purposes with clear definitions in the specification:

• DEFINITION (very short, single line description as opposed to an entire paragraph for SYNOPSIS and multiple paragraphs, lists,... for ELABORATION)
• CAPTION (as image or figure caption, e.g. for graphical representations of messages, groups, components)
• TOOLTIP (for GUIs when the mouse hovers over the name of an element)

User-defined purposes should still be allowed but the standard purposes should cover most use cases.

[martinswanson]

Generally supportive of adding clearer guidance for the purpose attribute, not least because it simplifies document generation.

Specific notes:

• DISPLAY as a solution to #193 makes sense.
• DEFINITION would help align Orchestra documentation to ISO 20022's MessageDefinition which is used in the List of Messages and in the functional description of messages in the Message Definition Reports (MDRs).
• CAPTION would be useful if we want to add text used in FIX media files to FIX Latest.

Suggested wording:

Multiple languages can be supported by specifying the language of each element in its langId attribute. Also, multiple categories of documentation are supported by populating the purpose attribute. Suggested values of purpose include “SYNOPSIS”, “ELABORATION”, “EXAMPLE”, “DISPLAY”, “CAPTION”, “TOOLTIP”, and “DEFINITION”.

• SYNOPSIS: Provides a brief summary of the element, typically highlighting its key function or purpose, restricted to one paragraph for conciseness.
• ELABORATION: Offers a more detailed explanation of the element, clarifying its usage, functionality, or background.
• EXAMPLE: Includes a sample or illustration demonstrating how the element is used in practice.
• DISPLAY: Defines a user-friendly or descriptive name for the element, often used for presentation purposes.
• CAPTION: Provides a descriptive label or title for the element, often used for headings or brief annotations.
• TOOLTIP: A short message or hint that appears when hovering over the element, usually explaining its function or use.
• DEFINITION: Gives a precise and formal explanation of the element, restricted to one sentence in length to ensure brevity.