<document>

Summary

The <document> element is the document element of all PSML documents. Core metadata relating to the document is attached as attributes, followed by the document’s content.

To be portable, a document must contain at least one <section> or <toc> element and at least one <fragment> element in one of the sections (it can be any kind of fragment).

Usage context

Attributes

This element includes the following attributes:

@date

The date of the latest change on the document in ISO 8601 date time format (including the time zone). INFORMATIONAL - ignored by upload.

For example: 2014-01-17T17:53:41+10:00.

It could be the date of the last edit or the date of the last version created or the creation date of the document.

@edit

A boolean flag to indicate whether the document can be edited in the user interface or not. Non editable documents can only be modified as a whole through the API or by upload.

The default is true.

@id

The URI ID of the document. INFORMATIONAL - ignored by upload.

@level

Unlike the integer values of heading level or levels of indent, in this context the @level attribute indicates the nature of the PSML in the document. Allowable values are the following:

• metadata – is the same as the portable format except it doesn’t include the content.
• portable – as the name implies, portable documents have been expressed in such a way that they can be round-tripped through external apps or moved from one PageSeeder server to another without loss of fidelity.

• processed – when exporting a document collection to act as input to a conventional publishing app, such as InDesign, a lot of downstream processing can be avoided if values like document references and paragraph numbers are resolved by PageSeeder prior to export. This is the role of the processed format.

The default value for the @level attribute is portable.

@lockstructure

A boolean flag indicating whether the structure of the document is locked.

When the structure is locked, sections and fragments cannot be moved, deleted or inserted. Editing, however, might be permitted if the edit flag allows it.

The default is false so that moving, inserting and deleting fragments is permitted.

@position

The position (instance number) of the document in the publication. Document content can be included multiple times in a publication. Introduced in v0.12 of the PSML schema in PageSeeder v5.96. INFORMATIONAL - ignored by upload. Only occurs in processed level PSML.

@publicationid

The publication ID for this document instance. Introduced in v0.12 of the PSML schema in PageSeeder v5.96. INFORMATIONAL - ignored by upload. Only occurs in processed level PSML.

@schemaversion

An informational attribute to indicate what version of the PSML schema this document validates. INFORMATIONAL - ignored by upload.

This can be used to select an appropriate processor. Beta versions of PSML start with “0.”, so '0.7' is actually 'Beta 7'.

@status

The status of this document. INFORMATIONAL - ignored by upload.

@type

The document type. Overrides <uri>/@documenttype on upload.

It can only contain alphanumeric characters and underscores. It must match the following regular expression:

^[a-zA-Z0-9_]*$

The document type is also specified on the <uri> element when the PSML document includes metadata. When the <uri> element is present, its @documenttype attribute must match this attribute.

@version

The name of the version of this document when there is one. INFORMATIONAL - ignored by upload.

If the document is the original, that is, before any edits or versions were made, the @version attribute has the value original.

If the document is the current document and does not correspond to a particular version, the @version attribute has the value current.

Examples

Default document

The following example is a complete sample default document without any metadata.

<document level="portable">

  <!-- Title -->
  <section id="title">
    <fragment id="1">
      <heading level="1"><!-- title goes here --></heading>
    </fragment>
  </section>

  <!-- Content -->
  <section id="content">
    <fragment id="2">
      <para><!-- description goes here --></para>
    </fragment>
  </section>

</document>

Schema

XML Schema

<xs:element name="document">

  <xs:complexType>
    <xs:sequence>
      <xs:element ref="documentinfo" minOccurs="0" maxOccurs="1"/>
      <xs:element ref="fragmentinfo" minOccurs="0" maxOccurs="1"/>
      <xs:element ref="metadata" minOccurs="0" maxOccurs="1" />

      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element ref="section"/><!-- portable only -->
        <xs:element ref="toc"/><!-- portable only -->
        <xs:element ref="fragments"/><!-- metadata only -->
      </xs:choice>
    </xs:sequence>

    <xs:attribute name="level" use="required">
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="metadata"/>
          <xs:enumeration value="portable"/>
          <xs:enumeration value="processed"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>

    <xs:attribute name="schemaversion" type="xs:string"/>
    <xs:attribute name="type" type="document-type" />
    <xs:attribute name="edit" type="xs:boolean" default="true"/>
    <xs:attribute name="lockstructure"
                  type="xs:boolean"
                  default="false"/>
    <xs:attribute name="version" type="xs:string"/>
    <xs:attribute name="date" type="xs:dateTime"/>
    <xs:attribute name="status" type="xs:string"/>
    <xs:attribute name="id" type="xs:long"/>
  </xs:complexType>

  <xs:key name="section-id">
    <xs:selector xpath="section"/>
    <xs:field xpath="@id"/>
  </xs:key>

  <xs:key name="fragment-id">
    <xs:selector xpath="section/fragment |
                        section/xref-fragment |
                        section/properties-fragment | 
                        section/media-fragment"/>
    <xs:field xpath="@id"/>
  </xs:key>
</xs:element>

Relax Schema

element document {
   attribute level { "portable" | "metadata" | "processed" },
   attribute type { document-type }?,
   attribute date { xs:dateTime },
   attribute edit { xs:boolean }?,
   attribute id { xs:long },
   attribute lockstructure { xs:boolean }?,
   attribute version { text },
   attribute status { text },
   attribute schemaversion { text },
   element documentinfo?,
   element fragmentinfo?,
   element metadata?,
  (element section | element toc | element fragments)+
}

Compatibility

This element was introduced in the first draft of PSML and is well-supported from PageSeeder 5.1.