PSML

A complete reference of PageSeeder's markup language PSML

<document>

Summary

The <document> element is the document element of all PSML documents. Core metadata relating to the document is attached as attributes.

The  contains the document metadata, followed by its 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 may be any kind of fragment).

Usage context

Element categorystructure
PSML levelportable
Permitted content<documentinfo>, <fragmentinfo>, <metadata>, <section>, <toc>,<fragments>
Permitted parentnone
HTML equivalent<html> 
OpenXML equivalent<w:document>
PSStandard equivalent<root>

Attributes

This element includes the following attributes

NameTypeRequiredDescription
datexs:dateTimenoThe date of the latest change on the document.
editbooleannoWhether or not this document is editable.
iddocument-idnoThe URI ID of the document.
leveldocument-levelyesThe level of the PSML.
lockstructurebooleannoFlag to disallow structural changes.
schemaversionxs:stringnoThe version of the PSML schema.
statusxs:stringnoThe status of the document version.
typedocument-typenoThe PSML document type.
versionxs:stringnoThe version of the document, the name of the version, "original" or "current".

@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 via the API or by upload.

The default is "true".

@id

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

Note

The URI ID is specific to a PageSeeder instance and is used mostly for traceability or to allow PageSeeder to identify the document more quickly.

@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 applications or moved from one PageSeeder server to another without loss of fidelity.
  • "processed" when exporting a document collections to act as input to a conventional publishing application 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 may be permitted if the edit flag allows it.

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

@schemaversion

An informational attribute to indicate what version of the PSML schema this document should validate. 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 regular expression below:

^[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 will have the value "original".

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

Examples

Default document

The example below 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.

PS Standard XML

The <document> element replaces the PS Standard XML element <root>.

Processing instruction

The processing instruction that was used in PS Standard XML documents to specify the document type and format is no longer supported in PSML.

The @document-type is now available as an attribute directly on the PSML <document> element. It can also be specified on the <uri> element.

Document properties

The document properties of PS Standard XML have also been moved to the <document> element as attributes.

<properties>
  <property name="document-type">
  <property name="add-fragment">
  <property name="delete-fragment">
  <property name="broadcast-discussion">
</properties>

These properties are now available as:

<document type="" lockstructure=""> ... </document>

See also

Created on , last edited on