Publishing

Publishing PageSeeder data to print, the Web or both

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 transformations.
  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 transformations.

Note

When processing documents that have cross references (XRefs) with a @type of "embed" or "transclude", the same fragment can occur multiple times in a single document. This is a legitimate use of these link types. However, it is important to remember that for fragments, which had previously existed in only one place but now occur in more than one, the address becomes ambiguous. Where these fragments are a destination for other XRefs, ambiguity prevents the links from resolving.

To address this, the process will examine sub-hierarchies for a location that contains both the XRef and its target. If a sub-hierarchy can be processed without ambiguity on its own, its internal links will not change when it becomes a component of a larger hierarchy.

Remember the Reference Check option under the Dev tab in the Developer perspective is a useful tool for checking cross references before publishing.  

Definition

Minimal definition:

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

 Full definition:

<ps:process
              src="[source]"
             dest="[destination]"
    stripmetadata="[true|false]"
      generatetoc="[true|false]"
      preservesrc="[true|false]"
      failonerror="[true|false]"
        processed="[true|false]"
           config="[config name]">

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

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

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

 <number
     numberconfig="[numbering config path]"
         includes="[patterns]"
         excludes="[patterns]">
    <include name="[name]" />
    <exclude name="[name]" />
                            </number>

 <images
             src="[uriid|uriidfolders|
                   permalink|location]"
        location="[folder path]"
        includes="[patterns]"
        excludes="[patterns]">
   <include name="[name]" />
   <exclude name="[name]" />
                            </images>

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

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

Attributes

AttributeDescriptionRequiredDefault

src

The source folder on the file system of the universal portable format input. For example:

c:\working\portable

Yes

dest

The destination folder on the file system for the universal processed format output. For example:

c:\working\process

Yes

stripmetadata

If "true", strip manifest.xml and all document/fragment metadata

No

"false"

generatetoc

If "true", generate table of contents for every <toc/> element. For details see Universal Processed Format.

No

"false"

preservesrc

If "true", keep the original source files, if "false", remove them.

No

"false"

failonerror

If "true", stop the build process on error.

No

"true"

processed

If "true", the value of <document>/@level will be changed to "processed".

No

"true"
convertmarkdown

If "true", convert the syntax of the content where <property datatype="markdown"> from markdown to valid PageSeeder markup language (XML).

No
"true"
config

Universal PS config name.

No

"default"

Elements

Note

In the elements below, nested <include name="x" /> or  <exclude name="x" /> elements can be used instead of @includes or @excludes attributes to avoid problems with commas in filenames.

Element <manifestdoc>

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

AttributeDescriptionRequired

filename

Filename for generated PSML document, for example:

manifest
Yes

includes

A comma-separated list of patterns matching documents/folders to include. If no list is present, then all documents/folders are included. The pattern format is similar to the file selection in other Ant tasks, for example:

*.psml,archive,folder1/*.psml,**/*.psml
No

excludes

A comma-separated list of patterns matching documents/folders to exclude. If no list is present, then no documents/folders are excluded. The pattern format is similar to the file selection in other Ant tasks, for example:

_local/**,_external/**
No

 

Element <pretransform>

Provides a mechanism to pre process PSML files with XSLT. The generate XML must be valid PSML. This element may contain nested <param name="x" expression="y" /> elements for passing XSLT parameters.

AttributeDescriptionRequired

xslt

Path to XSLT file to apply to all PS XML files before all other processing (must produce valid PSML)

Yes

includes

A comma-separated list of patterns matching documents/folders to include. If no list is present, then all documents/folders are included. The pattern format is similar to the file selection in other Ant tasks, for example:

*.psml,archive,folder1/*.psml,**/*.psml

No

excludes

A comma-separated list of patterns matching documents/folders to exclude. If no list is present, then no documents/folders are excluded. The pattern format is similar to the file selection in other Ant tasks, for example:

_local/**,_external/**

No

 

Element <xref>

Processes the cross references in PSML files.

AttributeDescriptionRequired

types

Comma separated list of XRef types to process in the included files. For example:

transclude,embed

Yes

levels

Whether to modify heading levels in target documents based on the XRef @level attribute.

Default is "true".

No

xreffragment

Defines how to handle XRefs in an <xref-fragment> element.
Possible values are:

  • "include" – process XRefs in an xref-fragment,
  • "exclude" – do not process XRefs in an xref-fragment and,
  • "only" – process XRefs only in an xref-fragment.

Default is "include".

No

includes

A comma-separated list of patterns matching documents/folders to include. If no list is present, then all documents/folders are included. The pattern format is similar to the file selection in other Ant tasks, for example:

*.psml,archive,folder1/*.psml,**/*.psml

No

excludes

A comma-separated list of patterns matching documents/folders to exclude. If no list is present, then no documents/folders are excluded. The pattern format is similar to the file selection in other Ant tasks, for example:

_local/**,_external/**

No

 

Element <number>

Generates auto-numbering in PSML files.

AttributeDescriptionRequired

numberconfig

Path to numbering config file for numbering included files.

Yes

includes

A comma-separated list of patterns matching documents/folders to include. If no list is present, then all documents/folders are included. The pattern format is similar to the file selection in other Ant tasks, for example:

*.psml,archive,folder1/*.psml,**/*.psml

No

excludes

A comma-separated list of patterns matching documents/folders to exclude. If no list is present, then no documents/folders are excluded. The pattern format is similar to the file selection in other Ant tasks, for example:

_local/**,_external/**

No

 

Element <images>

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

AttributeDescriptionRequired

src

Format of @src attribute on <image> elements. Allowed values are:

  • uriid – use the [uriid].[ext] format,
  • uriidfolders – use [uriid billions]/[uriid millions]/[uriid thousands]/[uriid].[ext] with leading zeros on folders. For example uriid 12345 would be 000/000/012/12345.png.
  • permalink – use the [ps.site.prefix]/uri/[uriid].[ext] format.
  • location – is the default. The @src attribute is not changed.

No

location

Move all <image> files to this folder path. If @src is "uriid" or "permalink" rename them to [uriid].[ext], otherwise use their path relative to src.

Yes, if src=uriid

embedmetadata

If "true" embed the <document level="metadata">... in the <image> element and apply src/location image processing to the @href of an <xref> where  metadata has type="alternate" and mediatype="image/*" 

No

includes

A comma-separated list of patterns matching documents/folders to include. If no list is present, then all documents/folders are included. The pattern format is similar to the file selection in other Ant tasks, for example:

*.psml,archive,folder1/*.psml,**/*.psml

No

excludes

A comma-separated list of patterns matching documents/folders to exclude. If no list is present, then no documents/folders are excluded. The pattern format is similar to the file selection in other Ant tasks, for example:

_local/**,_external/**

No

 

Element <strip>

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

AttributeDescriptionRequiredDefault

documentinfo

Comma separated list of items to strip. For example: 

all,docid,title,description,labels

"all" strips <documentinfo> elements.

No

"none"

fragmentinfo

Comma separated list of items to strip. For example:

all,labels

value of "all" strips <fragmentinfo> elements.

No

"none"

manifest

If "true" deletes the META-INF/manifest.xml file.

No

"false"

xrefs

Comma separated list of items to strip. For example:

all,docid,uriid,notfound,unresolved

values of all, notfound, unresolved strip <xref> markup but leaves the content

No

"none"

 

Element <posttransform>

Provides a mechanism to post process PSML source files with XSLT. The generated XML must be valid PSML. This element may contain nested <param name="x" expression="y" /> elements for passing XSLT parameters.

AttributeDescriptionRequired

xslt

Path to XSLT file to apply to all PS XML files after all other processing (must produce valid PSML)

Yes

includes

A comma-separated list of patterns matching documents/folders to include. If no list is present, then all documents/folders are included. The pattern format is similar to the file selection in other Ant tasks, for example:

*.psml,archive,folder1/*.psml,**/*.psml

No

excludes

A comma-separated list of patterns matching documents/folders to exclude. If no list is present, then no documents/folders are excluded. The pattern format is similar to the file selection in other Ant tasks, for example:

_local/**,_external/**

No

 

Element <error>

The element is used to customize error handling.

AttributeDescriptionRequiredDefault

xrefnotfound

If "true" raise an error if an xref target file is not in the export set.

No

"false"

imagenotfound

If "true" raise an error if a referenced image is not in the export set.

No

"false"

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>

  <number config="c:\working\defaultNumberingConfig.xml">
   <include name="spec.psml" />
  </number>

     <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 files.

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

      <manifestdoc filename="manifest"/>

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

  </ps:process>

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

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

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

     <number config="c:\working\defaultNumberingConfig.xml" >
              <include name="spec.psml" />
           </number>

    <images embedmetadata="true"/>
             <posttransform xslt="c:\working\alternate-images.xsl" />

 </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="*">
    <xsl:copy>
       <xsl:copy-of select="@*" />
     <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 example above) 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"
    strip-metadata="true"
    generatetoc="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="*">
    <xsl:copy>
      <xsl:copy-of select="@*" />
      <xsl:apply-templates select="node()" />
    </xsl:copy>
  </xsl:template>

</xsl:stylesheet>

Created on , last edited on