PSML

A complete reference of PageSeeder's markup language PSML

<xref>

Summary

This element is used to create the in-line cross references that typically represent footnotes, endnotes or paragraph references in contracts or legislation ( for example –see section 8.3.2).

For block-level cross references, where processing the XRef injects or  'transcludes' entire paragraphs or documents into the XRef source, see the <blockxref> element.

Note

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

  • @href
  • @docid
  • @uriid

See example XRef markup

The content of this element is displayed as the link title until the link is processed and the content is discarded. Even though the content is INFORMATIONAL, the following exceptions are why developers should include text in the element content:

  • If @display="manual" and @title is missing or empty, the content will be used for the value of @title;
  • If the cross reference can not be resolved, some content will help a user to understand or debug what went wrong with the XRef.

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

NameTypeReq​uiredDescription

config

xref-confignoThe configuration name for this XRef.

display

xref-display noDefines format of target link text.

docid

document-idnoThe document ID of the target.
documenttypedocument-typenoThe target document's type..

external

booleannoIf "true", the target is a URL (external URI).

frag

fragment-idyesThe fragment ID of the target.

href

xs:stringnoPath to the target document.

id

xs:long noXLink ID of the cross-reference.

labels

label-listnoA list of XRef labels.

level

xref-levelnoThe level of heading the target document should start at.

mediatype

xs:stringnoThe target document media type.

reverselink

booleannoA flag indicating if the link is bidirectional.

reversetitle

xs:stringnoThe title in the reverse direction.

reversetype

xref-typenoAlways "none".

reversefrag

fragment-idnoThe fragment ID on the source.

title

xs:stringnoThe manually entered title.

type

xref-typenoType for link processing (default is "none").

unresolved

boolean noIf "true", the target document could not be resolved.

uriid

xs:long noURI ID of the target document.

urititle

xs:stringnoTitle of the target URI (generated).

urilabels

label-listnoLabels 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];
  • "template" – see Cross-reference display.

@docid

The document ID of the target, this value 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 that begins with a "/" character. If it is "#", the current document will be the target. It must always be URL encoded unless document/@level="processed".

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 representation of the current document.
  • math An in-line transclude link to a file or <media-fragment> with mediatype of application/mathml+xml or text/asciimath. Used for equations.

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.

@urilabels

A comma separated list of labels of the target URI. Introduced in v0.11 of the PSML schema in PageSeeder v5.95. INFORMATIONAL - ignored by upload.

Examples

When constructing <xref> elements, it is useful to remember that PageSeeder will automatically expand a minimally-expressed link. All that is required is the address of the document and fragment and some content to make the link visible. PageSeeder will see all the following examples as valid:

<xref href="filename.psml"
                frag="default">link title</xref>
<xref docid="server-wide_uniqueid"
                        frag="default">link title</xref>
<xref uriid="9999"
          frag="5">link title</xref>

Also, documents containing these minimal links* can be uploaded before the other end of the link is available.

After both ends of the XRef are available, any user with the appropriate permission can go to the Group Manage page under the Admin menu and select the option to Resolve References.

The PageSeeder server will then resolve the <xref> element, add the implied attributes and values and create a <reversexref> element at the link destination.

* The third example is using a URIID. As this value is generated by the system, the target of this XRef is already known.

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