[ClusterLabs] Q: RA metadata description

[Ulrich Windl]

Hi!

The desription of RA metadata is poor for years (e.g. the DTD has almost no comments) (I still prefer the DTD for readability over the RNG), and working on an RA I have a question:

How is the <longdesc> to be formatted? A "crm ra info <RA>" des not seem to wrap long lines at terminal width. So are the long lines in <longdesc> expected to be wrapped in XML? Even if not, for practical reasons of readability the lines may be wrapped manually in XML.
So are there any formatting rules, or maybe even some markup?

BTW: Is there a reason why the DTD is named "ra-api-1.dtd", while the RNG is named "metadata.rng"?

Regards,
Ulrich

P.S. Here's the "well-documented" DTD:
<?xml version="1.0" encoding="UTF-8"?>

<!ELEMENT resource-agent (version,longdesc,shortdesc,parameters?,actions) >
<!ATTLIST resource-agent
        name    CDATA   #REQUIRED
        version CDATA   #IMPLIED>

<!ELEMENT version (#PCDATA)>

<!ELEMENT parameters (parameter*)>

<!ELEMENT actions (action*)>

<!ELEMENT parameter (longdesc+,shortdesc+,content)>
<!ATTLIST parameter
        name    CDATA   #REQUIRED
        required  (1|0)   "0"
        unique  (1|0)   "0">

<!ELEMENT longdesc ANY>
<!ATTLIST longdesc
        lang    NMTOKEN #IMPLIED>

<!ELEMENT shortdesc ANY>
<!ATTLIST shortdesc
        lang    NMTOKEN #IMPLIED>

<!ELEMENT content EMPTY>
<!ATTLIST content
        type    (string|integer|boolean|time)        #REQUIRED
        default CDATA   #IMPLIED>

<!ELEMENT action EMPTY>
<!ATTLIST action
        name (start|stop|recover|monitor|restart|migrate_to|migrate_from|promote|demote|notify|status|reload|meta-data|usage|methods|validate-all) #REQUIRED
        timeout         CDATA   #REQUIRED
        interval        CDATA   #IMPLIED
        start-delay     CDATA   #IMPLIED
        role            CDATA   #IMPLIED
        depth           CDATA   #IMPLIED>