Home

MS Base

  • prefix: ms:
  • schema: b:

Categories (Data):

Categories (Governance):

documentation:

  
 

Schema element "b:documentation"

Documentation about the content of b:units.

Definitions

<element name="documentation" type="b:Documentation" />

<complexType name="Documentation">
  <sequence>
    <group ref="b:mediatype" />
    <element name="name"        type="string" [0..1] />
    <element name="altname"     type="string" [0..1] />
    <element name="title"       type="string" [0..1] />
    <element name="hint"        type="string" [0..1] />
    <element name="description" type="string" [0..1] />
    <element name="webpage"     type="anyURI" [0..1] />
  </sequence>
  <attributeGroup ref="b:doc-selector" />
</complexType>

Description

When you have additional documentation information inside another Unit, then use b:has references of kind ms:Role/Documentation.

See the Manual Units as defined by Concept for bulk documentation: Units of type msc:Type/Manual.

element altname

Alternatives for the name, which can also be used to address the Unit. Alternatives could be alternative spellings, the name in lowercase, abbreviation, name without accent, etc.

element description

An extensive explanation about the content of the Unit. For instance, what the impact of the content of the Unit is, why it is there, how it can be used, and so on. Typically a piece of what would be a manual-page fragement.

element hint

This is a very short (typically a few lines) help to the meaning of this Unit. This may be shown as tooltip when moving over the Unit.

element name

The name is displayed as translation of the Unit's name. When missing, that value will be used, which defaults to the Unit's id.

element title

A one-liner which describes the name. This may be shown as a chapter title or header on top of a hint.

element webpage

When a simple description is not enough: a reference to a web-page, maybe on some website which is also owned by the Namespace holder.

Examples

documentation inside the Unit itself 

<unit uid="IMG00001.jpg">
  <name>2022-02-04 picture 1</name>
  <content>
  	<mediatype>iana:MediaType/image/jpeg</mediatype>
  </content>
  <documentation>
    <mediatype>iana:MediaType/text/plain</mediatype>
    <language>ietf:Language/nl-NL</language>
    <name>2022-02-04 foto 1</name>
    <title>Vakantie in Zeeland</title>
  </documentation>
</unit>

"unit" : {
   "uid" : "IMG00001.jpg",
   "name" : "2022-02-04 picture 1",
   "content" : {
      "mediatype" : "iana:MediaType/image/jpeg"
   },
   "documentation" : {
     "language" : "ietf:Language/nl-NL",
     "name" : "2022-02-04 foto 1",
     "hint" : "Vakantie in Zeeland"
   }
}

documentation inside the Unit, two languages 

<unit uid="IMG00001.jpg">
  <content>
    <mediatype>iana:MediaType/image/jpeg</type>
  </content>
  <documentation>
    <mediatype>iana:MediaType/text/plain</type>
    <documentation>
      <language>ietf:Language/nl-NL</language>
      <name>2022-02-04 foto 1</name>
      <hint>Vakantie in Zeeland</hint>
    </documentation>
    <documentation>
      <language>ietf:Language/en-US</language>
      <name>04-02-2022 photo 1</name>
      <hint>Holidays in Zeeland (NL)</hint>
    </documentation>
  </documentation>
</unit>

"unit" : {
   "uid" : "IMG00001.jpg",
   "content" : {
      "mediatype" : "iana:MediaType/image/jpeg",
   },
   "documentation" : { 
      "mediatype" : "iana:MediaType/text/plain",
      "documentation" : [ {
         "language" : "ietf:Language/nl-NL",
         "name" : "2022-02-04 foto 1",
         "hint" : "Vakantie in Zeeland"
      }, {
         "language" : "ietf:Language/en-US",
         "name" : "04-02-2022 photo 1",
         "hint" : "Holidays in Zeeland (NL)"
      } ]
   }
}

documentation in some other Unit, explicit 

<unit uid="IMG00001.jpg">
  <content>
  	<type>iana:MediaType/image/jpeg</type>
  </content>
  <definitions>
    <has role="ms:Role/Documentation" unitref="Story/IMG00001" />
  </definitions>
</unit>

"unit" : {
   "uid" : "IMG00001.jpg",
   "type" : "iana:MediaType/image/jpeg",
   "content" : { },
   "definitions" : [{
      "has" : [{
         "role" : "ms:Role/Documentation",
         "unitref" : "Story/IMG00001.jpg"
      }]
   }]
}

Of course, the complexity is now in the Unit named Story/IMG00001. As big benefit, the access and caching rules in the Story Namespace can be very different from the rules for the Unit which it is documenting.

documentation in some other Unit, implicit 

<unit uid="hol">
  <name>Holiday Pictures</name>
  <type>ms:Type/Namespace</type>
  <namespace />
  <has role="ms:Role/Documentation" unitref="Story" />
</unit>

"unit" : {
   "uid" : "hol",
   "name" : "Holiday Pictures",
   "type" : "ms:Type/Namespace",
   "namespace" : { },
   "has" : {
      "role" : "ms:Role/Documentation",
      "unitref" : "Story"
   }
}

Documentation search tries Story/unit-id and Story. Also visits parent Namespaces.

mark@overmeer.net      Web-pages generated on 2023-12-19