PSML

A complete reference of PageSeeder's markup language PSML

<xref>

Summary

This element is used to create in-line cross reference.

For block-level cross references where a document or fragment of another document, is 'transcluded' as entire paragraphs, the links are expressed using the <blockxref> element.

Note

The @frag attribute is required, plus at least one of the following:

  • @href,
  • @docid,
  • @uriid.

This element's content text (displayed as the link title) is generated. Therefore the content is only INFORMATIONAL and is discarded by the upload process. The two exception to this are:

  • when @display='manual' and @title is missing or empty, then @title takes the value of the content;
  • when the cross reference can not be resolved, then the content is retained.

For these reasons it is a good practice to include some text in the element's content.

Link limit

Individual documents have a limit on the maximum number of cross-references including both inline <xref> and block <blockxref>.  The most common use case of reaching the limit is with references document acting as a table of contents.

Though the hard limit is higher it is not recommended to have more than 1,000 xrefs in a single document. Where more than 1,000 xrefs are required, create references documents that point to other references document. Documents that have more than 1,000 inline xrefs can be broken down to smaller documents and re-assembled with a references document.

Usage context

Element categoryinline
PSML levelportable
Permitted contenttext
Permitted parent
HTML equivalent<a>
OpenXML equivalent
PSStandard equivalent<xref> 

Attributes

This element includes the following attributes

NameTypeRequiredDescription
displayxref-display noDefines format of target link text
dociddocument-idnoThe document ID of the target 
documenttypedocument-typenoThe target document's type.
externalbooleannoIf "true" the target is a URL (external URI).
fragfragment-idyesThe fragment ID of the target
hrefxs:stringnoPath to the target document
idxs:long noXLink ID of the cross-reference 
labelslabel-listnoA list of XRef labels
levelxref-levelnoThe level of heading the target document should start at
mediatypexs:stringnoThe target document media type
reverselinkbooleannoA flag indicating if the link is bidirectional
reversetitlexs:stringnoThe title in the reverse direction
reversetypexref-typenoAlways "none"
reversefragfragment-idnoThe fragment ID on the source
titlexs:stringnoThe manually entered title
typexref-typenoType for link processing (default is "none").
unresolvedboolean noIf "true"  the target document could not be resolved.
uriidxs:long noURI ID of the target document
urititlexs:stringnoTitle of the target URI (generated)

@display 

Defines how the target link text of this cross-reference is displayed (Default is "document").

 The following values are allowed:

  • "document"  [document title];
  • "document+manual"  [document title]: [manual title];
  • "document+fragment"  [document title]: [target fragment id];
  • "manual"  [manual title]

@docid

The document ID of the target.

It overrides the uriid on upload.

@documenttype

The target document's type. INFORMATIONAL - ignored by upload.

@external

If "true" the target is a URL (external URI). INFORMATIONAL - ignored by upload.

@frag

The target fragment ID. When this value is "default" it refers to the entire document.

@href

When uploading this may be a path relative to the current document or an absolute path beginning with / and must be URL encoded.

It overrides the docid and uriid on upload.

@id

The ID of the XLink corresponding to this cross-reference. INFORMATIONAL - ignored by upload.

@labels

A comma-separated list of XRef labels.

@level

The level that the heading numbering of the target document should start from (1 to 5). 

@mediatype

The mediatype of the target document. INFORMATIONAL - ignored by upload.

The media type of PSML documents is "application/vnd.pageseeder.psml+xml".

@reverselink

A boolean attribute to indicate whether the cross-reference is bidirectional, that is a reverse cross reference. When set to "true" (default), the cross-reference will also appear on the target document as part of its metadata.

@reversetitle

The manually entered title to appear on the reverse cross reference.

@reversetype

Type for link processing of reverse cross reference (only "none" is currently supported)

@reversefrag

The fragment ID on the source. INFORMATIONAL - ignored by upload.

@title

The manually entered title to appear on the link (only used when @display='manual' or @display='document+manual'). When @display='manual' and @title is missing or empty, then @title takes the value of the element's content text.

@type

The type defines how PageSeeder should process the cross-reference.

The following values are allowed:

  • none  No link processing;
  • alternate – An alternate representations of the current document.

To create cross-references which have a different type (for example transclusions) use a <blockxref> element instead.

@unresolved

If "true" the target document doesn't exist. INFORMATIONAL - ignored by upload.

@uriid

The URI ID of the target document.

Ignored by upload if on a different PS server.

@urititle

An informational attribute providing title of the target URI. INFORMATIONAL - ignored by upload.

Examples

Schema

XML Schema

<xs:element name="xref">
   <xs:complexType>
      <xs:simpleContent>
         <xs:attribute name="id" type="xs:long"/>
         <xs:attribute name="docid" type="document-id"/>
         <xs:attribute name="href" type="xs:string"/>
         <xs:attribute name="uriid" type="xs:long">
         <xs:attribute name="frag" type="fragment-id" use="required"/>
         <xs:attribute name="title" type="xs:string"/>
         <xs:attribute name="level">
           <xs:simpleType>
             <xs:restriction base="xs:integer">
               <xs:pattern value="[1-5]"/>
             </xs:restriction>
           </xs:simpleType>
         </xs:attribute>
         <xs:attribute name="display">
            <xs:simpleType>
               <xs:restriction base="xs:string">
                  <xs:enumeration value="document" />
                  <xs:enumeration value="document+manual" />
                  <xs:enumeration value="document+fragment" />
                  <xs:enumeration value="manual" />
               </xs:restriction>
            </xs:simpleType>
         </xs:attribute>
         <xs:attribute name="labels" type="xs:string"/>
         <xs:attribute name="urititle" type="xs:string"/>
         <xs:attribute name="mediatype" type="xs:string"/>
         <xs:attribute name="documenttype" type="xs:string"/>
         <xs:attribute name="reverselink" type="xs:boolean"/>
         <xs:attribute name="reversetitle" type="xs:string"/>
         <xs:attribute name="reversetype">
            <xs:simpleType>
               <xs:restriction base="xs:string">
                  <xs:enumeration value="none" />
                  <xs:enumeration value="alternate"/> 
               </xs:restriction>
            </xs:simpleType>
         </xs:attribute>
         <xs:attribute name="reversefrag" type="fragment-id"/> 
         <xs:attribute name="unresolved" type="xs:boolean"/>
         <xs:attribute name="external" type="xs:boolean"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
</xs:element>

Relax Schema

element xref {
   attribute id { xs:long }?,
   attribute docid { document-id }?,
   attribute href { text }?,
   attribute uriid { xs:long }?,
   attribute frag { fragment-id },
   attribute title { text },
   attribute level { xs:integer }?,
   attribute type { string "none" | string "alternate" },
   attribute display { "document" | "document+manual"
                        | "document+fragment" | "manual"},
   attribute labels { text }?,
   attribute urititle { text }?,
   attribute mediatype { text }?,
   attribute documenttype { text }?,
   attribute reverselink { xs:boolean }?,
   attribute reversetitle { text }?,
   attribute reversetype { string "none"}?,
   attribute reversefrag { fragment-id },
   attribute unresolved { xs:boolean }?,
   attribute external { xs:boolean }?
}

Compatibility

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

Warning!

The types "replace" and "include" supported in PSStandard are no longer supported in PSML. Any <xref> with these types should be replaced by <blockxref>.

See also

Created on , last edited on