Task process

Used to produce Universal Processed Format from Universal Portable Format, this task can be used to do the following, in order:

1. Create a PSML document from the manifest.xml.
2. Pre-process a custom transformation.
3. Process cross-references.
4. Process paragraph and list numbering and table of contents.
5. Process image references.
6. Process metadata in or out.
7. Post-process a custom transformation.

Definition

Minimal definition:

<ps:process src="[source]"
            dest="[destination]"/>

 Full definition:

<ps:process src="[source]"
            dest="[destination]"
            embedlinkmetadata="[true|false]"
            stripmetadata="[true|false]"
            preservesrc="[true|false]"
            failonerror="[true|false]"
            placeholders="[true|false]"
            processed="[true|false]"
            convertmarkdown="[true|false]"
            convertasciimath="[true|false]"
            converttex="[true|false]"
            config="[config name]">

  <manifestdoc filename="[filename]">
    <include name="[name]" />
    <exclude name="[name]" />
  </manifestdoc>

  <pretransform xslt="[pre XSLT path]">
    <include name="[name]" />
    <exclude name="[name]" />
    <param name="[x]"
           expression="[y]" />
    ...
  </pretransform> 

  <xrefs types="[xref types]"
         xreffragment="[include,exclude,only]">
    <include name="[name]" />
    <exclude name="[name]" />
  </xrefs>

  <publication config="[publication config path]"
               rootfile="[path relative to src]"
               generatetoc="[true|false]"
               headingleveladjust="[numbering|content]" />

  <images src="[uriid|uriidfolders|
          permalink|filename|filenameencode|location]"
          location="[folder path]"
          embedmetadata="[true|false]">
    <include name="[name]" />
    <exclude name="[name]" />
  </images>

  <strip manifest="[true|false]"
         documentinfo="[all,docid,title,description,
         labels,publication,versions]"
         fragmentinfo="[all,labels]"
         xrefs="[all,docid,uriid,notfound,unresolved,reversexrefs]"
         images="uriid" />
 
  <posttransform xslt="[post XSLT path]">
    <include name="[name]" />
    <exclude name="[name]" />
    <param name="[x]"
           expression="[y]" />
    ...
  </posttransform>

  <error xrefnotfound="true"
         xrefambiguous="true"
         imagenotfound="true" />
</ps:process>

Attributes

Elements

Element <include>

A pattern matching documents/folders to include. If not present, then all documents/folders are included. It can not be used directly under the <ps:process> element.

Element <exclude>

A pattern matching documents/folders to exclude. If not present, then no documents/folders are excluded. It can not be used directly under the <ps:process> element.

Element <manifestdoc>

Creates a PSML document of type manifest containing a <blockxref> of type embed for each PSML file in the process src folder, in alphabetical order. The generated file is included in PSML files for subsequent processing.

This element might contain multiple nested <include name="" /> or <exclude name="" /> elements as defined in the previous sections.

Element <pretransform>

Provides a mechanism to pre process PSML files with XSLT. The generated XML must be valid PSML.

This element might contain multiple nested <include name="" /> or <exclude name="" /> elements as defined in the previous sections.

This element might also contain nested <param name="x" expression="y" /> elements for passing XSLT parameters.

Element <xrefs>

Processes the cross-references in PSML files which does the following:

1. Replaces the <xref> or <blockxref> element’s content with the PSML of the target document or fragment, provided the element has the following attributes: @frag, @href, @type, @uriid.
2. Prefixes fragment @id with [URI ID][_n]- so that all fragment IDs are unique.
3. For any xref of type none that points to content now included in the document (by item 1) the @href is changed to the @id of the target document or fragment (for example #456, #456-3, #456_2-3).

This element might contain multiple nested <include name="" /> or <exclude name="" /> elements as defined in previous sections.

Element <number>

Generates auto-numbering in PSML files.

This element might contain multiple nested <include name="" /> or <exclude name="" /> elements as defined in previous sections.

Element <publication>

Generates table of contents and auto-numbering in PSML files. Available in PageSeeder v5.96 or higher.

Element <images>

This element provides options to control how images are managed and rewrites the path accordingly.

This element might contain multiple nested <include name="" /> or <exclude name="" /> elements as defined in previous sections.

Element <strip>

Provides finer control over the elements to strip. Must not be used in conjunction with the @stripmetadata attribute.

Element <posttransform>

Provides a mechanism to post process PSML source files with XSLT. The generated XML must be valid PSML.

This element might contain multiple nested <include name="" /> or <exclude name="" /> elements as defined in previous sections.

This element might also contain nested <param name="x" expression="y" /> elements for passing XSLT parameters.

Element <error>

The element is used to customize error handling.

Environment

This task uses the following PS config environment properties:

• site.prefix – site prefix for the <image src="permalink"> option.

default –  /ps

Errors

Possible errors are:

• Required attribute or environment property missing.
• Attribute or property invalid.
• Required metadata missing.
• Pre/post transform XSLT error.
• Pre/post transform validation error.
• Internal link pointing to URI x fragment y is ambiguous because this content appears in multiple locations.
• Reference loop detected when resolving xref from x to y.
• Xref target not found (see <error> element).
• Image not found (see <error> element).

Examples

Consolidate documents

Process the xrefs so that the linked documents are concatenated into a single file. Extract all images into a single folder using permalink notation.

<ps:process src="c:\working\export"
            dest="c:\working\process"
            stripmetadata="true">

  <xrefs types="embed,transclude">   
    <include name="spec.psml" />
  </xrefs>

  <images src="uriid"
          location="c:\working\images" />

 </ps:process>

Remove Doc IDs and URI IDs

<ps:process src="c:\working\export"
            dest="c:\working\process">

  <strip documentinfo="docid"
         xrefs="docid,uriid">

    <error imagenotfound="true"
           xrefnotfound="true" />
 
</ps:process>

Concatenate all downloaded PSML documents

<ps:process src="c:\working\export"
            dest="c:\working\process"
            stripmetadata="true">

  <manifestdoc filename="manifest">
    <exclude name="META-INF/**" />
  </manifest>

  <xrefs types="embed">
    <include name="manifest.psml" />
  </xrefs>

</ps:process>

Copy documents to another group

To copy PSML documents to another PageSeeder group they must be exported, processed and then uploaded. To process PSML so that the copies stay independent from one another on the same server (i.e. they don’t reference each other) use the following options:

<ps:process src="${download}"
            dest="${process}"
            placeholders="false"
            processed="false"
            convertmarkdown="false"
            convertasciimath="false"
            converttex="false">
  <strip documentinfo="docid,publication"
         xrefs="docid,uriid"
         images="uriid"
         manifest="true" />
</ps:process>

PageSeeder doesn't allow the same publicationid on different sets of documents in the same PageSeeder server domain. However, if you need publications to be preserved in the other group you could remove the documentinfo="publication" and add a <posttransform> with an XSLT that adds a suffix to the publication/@id when copying.

Use alternate images

This makes it possible to have images for editing and use for web delivery at the same time as having higher resolution images for publishing to paper. The idea is that when:

<image src="">..<metadata>..<xref type="alternate" href=""></image>

replace

image/@src

with

xref/@href

Process task

<ps:process src="c:\working\export"
            dest="c:\working\process"
            generatetoc="true">

  <xrefs types="embed,transclude">
    <include name="spec.psml" />
  </xrefs>

  <images embedmetadata="true"/>

  <posttransform xslt="c:\working\alternate-images.xsl">
    <include name="spec.psml" />
  </posttransform>

</ps:process>

alternate-images.xsl

<xsl:stylesheet version="2.0"
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <!-- change image src to alternate image -->
  <xsl:template match="image[.//xref/@type='alternate']">
    <image src="{.//xref[@type='alternate']/@href}">
      <xsl:copy-of select="@*[not(name()='src')]"/>
    </image>
  </xsl:template>

  <!-- copy all other elements unchanged -->
  <xsl:template match="@*|node()">
    <xsl:copy>
      <xsl:apply-templates select="@*|node()"/>
    </xsl:copy>
  </xsl:template>

</xsl:stylesheet>

Image ‘shell’ documents

A shell document contains both a lo-res and hi-res image. For editing, the link typically refers to the lo-res with the hi-res used to publish to paper or PDF. Although the approach of alternate images (see previous example) is recommended generally, there are legitimate use cases for the shell approach. 

Essentially the idea is to replace the references to: 

<fragment id="lores"><image .../>

with

<fragment id="hires"><image .../>

Process task

<ps:process
    src="c:\working\export"
    dest="c:\working\process"
    stripmetadata="true">
  <xrefs
      types="embed,transclude">
    <include name="spec.psml" />
  </xrefs>
  <number
      config="c:\working\defaultNumberingConfig.xml" >
    <include name="spec.psml" />
  </number>
  <pretransform xslt="c:\working\hires-images.xsl" />
</ps:process>

hires-images.xsl

<xsl:stylesheet version="2.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <!-- change blockxref to point to hires image -->
  <xsl:template match="blockxref[@fragment='lores']">
    <blockxref fragment="hires">
      <xsl:copy-of select="@*[not(name()='fragment']"/>
      <xsl:apply-templates />
    </blockxref>
  </xsl:template>

  <!-- copy all other elements unchanged -->
  <xsl:template match="@*|node()">
    <xsl:copy>
      <xsl:apply-templates select="@*|node()"/>
    </xsl:copy>
  </xsl:template>

</xsl:stylesheet>