Editorial: fos record descriptions within xmlspec prose

[michaelhkay]

In the F+O spec, the uri-structure-record appearing in section 6.6, and various other similar record descriptions, are defined using the fos namespace markup in xpath-functions.xml. Normally the fos XML vocabulary is confined to function-catalog.xml, and is converted to the usual xmlspec vocabulary by the merge-function-specs stylesheet.

Using this vocabulary directly within an xmlspec document means that the document doesn't validate against its DTD, and that the fos islands aren't validated against the fos.xsd schema.

A better approach here might be to use XInclude to insert text from a separate, schema-validated, document.

[ndw]

Right. I will review and update the build accordingly.

[michaelhkay]

This is looking pretty messy.

We have three overlapping markup conventions:

fos:options

Used for describing the structure of options parameters. 18 occurrences. Always appears in the function catalog within fos:rules, generally as an immediate child but sometimes more deeply nested. The permitted content is defined in fos.xsd. When the element appears as an immediate child of fos:rules, it is validated by virtue of the declaration:

<xs:element name="rules">
    <xs:complexType>
      <xs:choice maxOccurs="unbounded">
        <xs:any namespace="##local" processContents="skip"/>
        <xs:element ref="fos:options"/>
        <xs:element ref="fos:record-description"/>
      </xs:choice>
      <xs:attributeGroup ref="fos:diff-markup"/>
    </xs:complexType>
  </xs:element>

but when it appears within narrative XHTML it is covered by the processContents="skip" wildcard and is therefore not validated.

fos:record-description

2 occurrences within function-catalog.xml, both as children of fos:rules. Used for describing records other than options parameters. Structure is defined in fos:xsd, with a very similar but not identical content model to fos:options. Also has three occurrences within xpath-functions.xml (where it is not validated, and not valid). One of these (for parse-html) describes an options parameter.

fos:record

Always appears in function-catalog.xml as a child of fos:type, which is referenced from function signatures. 3 occurrences.

[michaelhkay]

I suggest that we combine all three elements, using the structure of fos:options as a basis because it is the one that is used most frequently.

I suggest that we use the name fos:record-description and make it always appear at the top level of function-catalog.xml (at the same level as fos:function), with a globally-unique name. The fos:option child should be renamed fos:field.

The fos:options element is replaced with a reference to a global fos:record-description.

The fos:record element is also replaced with a reference to a global fos:record-description.

Where fos:record-description appears within xpath-functions.xml, it is replaced with a processing instruction <?record-description name?> Note that the stylesheet merge-functions-specs.xsl has a template rule with match="processing-instruction('type')" that appears to be designed for this purpose, but is currently unused.