Tutorials

Task-driven tutorials and recipes for PageSeeder

How to import and export LwDITA in PageSeeder

Skills requiredXML
Time required (minutes)45
Intended audienceDeveloper
DifficultyMedium
CategoryDocument

Objective

PageSeeder can be used to edit, manage and publish content from different XML formats. This tutorial shows how to import/export and edit Lightweight DITA  (LwDITA) XML format in PageSeeder.

It includes how to:

  • model the LwDITA format in PSML;
  • import LwDITA as PSML using map and topic document types;
  • create and edit map and topic documents in PageSeeder;
  • export map documents as DocX, PDF and back to LwDITA format.

Prerequisites

To complete this tutorial requires:

  • Administrator access to a PageSeeder server.

All the necessary files for this tutorial are on Github .

Tutorial

Model LwDITA in PSML

The following resources were used to map the LwDITA XDITA format elements and attributes to PSML elements and attributes.

For simplicity a one to one file mapping between LwDITA XDITA files and PSML files was used and the mapping below was created. Any customization of PageSeeder document configurations has also been listed in the Document config column.

Mapping of general XDITA elements to PSML

ComponentXDITAPSMLDocument config
Alternate text<alt>@alt on <image>
Body<body><section>
Bold<b><bold>
Cross reference<xref><link> for external target; <xref> for internal target
Data<data><property> under <metadata>topic/document-template.psml can be used to configure property/@name values
Definition description<dd><para prefix="[dt]"> content
Definition list entry<dlentry><para prefix="[dt]">
Definition term<dt>@prefix on <para>
Definition list<dl><block label="dl"><labeling> in topic/document-config.psml
Description<desc><block label="desc"> in <block label="fig"><labeling> in topic/document-config.psml
Figure<fig><block label="fig"><labeling> in topic/document-config.psml
Footnote<fn><inline label="fn"><labeling> in topic/document-config.psml
Image<image><image>
Italics<i><italic>
Key definition<keydef><para><inline label="keydef">[@keys]</inline>[linktext]</para><labeling> in map/document-config.psml
Link text<linktext>See keydef above
List item<li><item>
Map<map><document type="map"><creation> in map/document-config.psml
Note<note><block label="note"><labeling> in topic/document-config.psml
Ordered list<ol><nlist>
Paragraph<p><para>
Navigation title<navtitle>@title on <uri> or <blockxref>
Phrase<ph>if @keyref then <inline label="keyref">[@keyref]</inline>; else if @props then <inline label="[@props]"><labeling> in topic/document-config.psml
Preformatted text<pre><preformat>
Prolog<prolog><metadata>
Section<section><section>
Short description<shortdesc><description> under <uri>
Table<simpletable><table>
Simple table entry<stentry><cell>
Simple table header<sthead><row part="header">
Simple table row<strow><row>
Subscript<sub><sub>
Superscript<sup><sup>
Title<title><block label="title"> in <block label="fig">; <heading level="2"> in <fragment>
Topic<topic><document type="topic"><creation> in topic/document-config.psml
Topic metadata<topicmeta>Not applicable
Topic reference<topicref><blockxref>
Underline<u><underline>
Unordered list<ul><list>

Mapping of multimedia XDITA elements to PSML

ComponentXDITAPSML
Audio<audio><properties-fragment type="audio">
Autoplay<media-autoplay><property name="media-autoplay">
Controls<media-controls><property name="media-controls">
Loop<media-loop><property name="media-loop">
Muted<media-muted><property name="media-muted">
Poster<video-poster><property name="video-poster">
Source<media-source><property name="media-source" count="n">
Track<media-track><property name="media-track" count="n">
Video<video><properties-fragment type="video">

These are all configured in topic/document-template.psml and topic/editor-config.json.

Mapping of XDITA attributes to PSML

Component/SetXDITAPSMLDocument config
Architecture attributes
ditaarch@xmlns:ditaarchNot applicable
DITAArchVersion@ditaarch:DITAArchVersionNot applicable
Domains@domainsNot applicable
Localization attributes
Direction

@dir

Not applicable
Language@xml:langNot applicable
Translate@translateNot applicable
Data definition
Name@name@name on <property>topic/document-template.psml can be used to configure @name values
Value@value@value on <property>
Figure display attributes
Expanse@expanse<inline label="expanse"><labeling> in topic/document-config.psml
Frame@frame<inline label="frame"><labeling> in topic/document-config.psml
Scale@scale<inline label="scale"><labeling> in topic/document-config.psml
Filtering attribute
Props@props<inline label="props"><labeling> in topic/document-config.psml
Footnote control
Callout@calloutNot implemented but could use <inline label="callout">
Image size
Height@height@height
Width@width@width
Note type
Type@type@label on <inline>
Processing attribute
Output class@outputclassNot implemented but could use @role on some elements
Reference attributes
Link target

@href

@href and @frag
Format of target resource@format@mediatype
Relationship of source to target@scopeNot implemented but could use @labels
Reuse attributes
Identifier

@id

@id on parent <fragment>
Content reference@conref@href on <blockxref type="transclude">
Video size
Height@height<property name="height">topic/document-template.psml and topic/editor-config.json.
Width@width<property name="width">topic/document-template.psml and topic/editor-config.json.

Note

This tutorial supports @conref for audio, dl, dentry, note, ol, p, pre, section, simpletable, ul, video but not for fn, dt, dd, li, sentry, sthead, strow elements (this content must be wrapped in p elements to use @conref).

 

Configure LwDITA project customizations

  1. Login to PageSeeder as an administrator.
  2. Click on New project and enter the project name "lwdita", any description and any owner, then click Submit.
  3. Click Home page then New group and enter the group name "tutorial", any description, then click Submit.
  4. Select Developer perspective from the cube icon (top left).
  5. Select Project files from the Dev menu.
  6. Drag the ps-lwdita-[date].zip file (downloaded from Github) to the drop files area.
  7. Click the Import icon next to this zip file.
  8. Select Toolbox from the Dev menu, then click on Project files under PageSeeder publisher on the right.
  9. Drag the pspublisher-lwdita-[date].zip file (downloaded from Github) to the drop files area.
  10. Click the Import icon next to this zip file.
  11. Click on Publish scripts and then click edit to the right of the "upload dita" row (see below).
  12. This is the ANT script used to import a .dita file as PSML. Click on the Help (?) icon (top right) to find out more information.
  13. Click on Go to folder and then on lwdita-to-psml.xsl.
  14. This is the XSLT used to convert a .dita file to a PSML file. It implements all the mapping rules described above and is executed by the ANT script.
  15. Go back to the first Project files page (it should be in another tab) and click on Home.

 

Import LwDITA as PSML

  1. Ensure you are on the home page for the "lwdita-tutorial" group then click on the upload document icon (see below).
  2. Drag the sample-lwdita.zip file (downloaded from Github) to the drop files area.
  3. Click the Unzip icon next to this zip file.
  4. Click the List media button (bottom right).
  5. Click Options next to DITA or DITAMAP and click on Import LwDITA as PSML.
  6. Click the Continue button at the bottom.
  7. Wait a little while until the Confirm upload dialog appears, then click Continue and wait for the message "Successfully uploaded".
  8. Under this message click on the remotelighting.psml link. This is the main ditamap file converted to PSML and should look as shown below.
  9. Click on the links to explore the topic documents.
  10. Click on the Remote Control Specifications topic, then on the document settings icon and select outline transclusions (see below). This shows how the DITA conref appears as a transclusion at the bottom.

Create and edit map and topic documents

  1. On the map document click the pencil next to the Topicrefs section.
  2. Click Create Document.
  3. Select LwDITA topic and type a title "My topic".
  4. Click More document options then
    1. type a Document ID "lwdita-tutorial_mytopic" (for this tutorial we use the format [full group name]_[topic ID]) - note the underscore before topic ID.
    2. type a Description "This is my topic."
  5. Click Submit then click Save.
  6. Click on the My topic link and then click the add fragment icon (on the right).
    1. Type "This is my content."
    2. Press enter and type "This is my note.", then select the text, right click and select Add block 'note'.
    3. Click Save.
  7. Mouse over the pencil icon (on the right) and then the add fragment icon and choose Video.
    1. Next to Autoplay: select "true".
    2. Next to Source: type a URL to a video (e.g. https://www.youtube.com/watch?v=...) and click Add.
    3. Click Save.
  8. Select Document config from the Dev menu.
  9. To see how creation and editing are configured click on edit under "Document template", "Document config" and "Editor config", next to the "map" and topic" document types (see below). When viewing files click on the Help (?) icon (top right) to find out more information.

 

Export map documents as DocX, PDF and LwDITA

  1. On the map document click the export icon (top left).
  2. Click on Create DocX for LwDITA and click Export. Open the document in Word and notice that the keyrefs have been replaced by the keydef text "Remote Lighting Network" and the video/audio by links. This is done by the lwdita-post-transform.xsl described below. The "My topic" content should be at the bottom.

  3. Click on Create PDF for LwDITA and click Export. It should have the same replacements as for the DocX.

  4. Click on Export as LwDITA and click Export. Extract the .zip file and open the .ditamap and .dita files with a text editor (e.g. Notepad) to check the content. Note the new my_topic.dita file that was not in the original sample-lwdita.zip file.

  5. Select Document config from the Dev menu and then click on Publish scripts (top right).

  6. Click edit to the right of the "(Create DocX for LwDITA)" row (see below).
  7. This is the ANT script used to export as DocX. Click on the Help (?) icon (top right) to find out more information.
  8. Click on Go to folder and then on lwdita-post-transform.xsl.
  9. This is the XSLT used to replace the keyrefs by the keydef text and the video/audio by links. It is executed by the <ps:process> ANT task.
  10. Click on Publish scripts and then on edit to the right of the "(Create PDF for LwDITA)" row (see below). This is the ANT script used to export as PDF.
  11. Click on Publish scripts and then on edit to the right of the "(Export as LwDITA)" row (see below). This is the ANT script used to export as LwDITA.
  12. Click on Go to folder and then on psml-to-lwdita.xsl.
  13. This is the XSLT used to convert a PSML file to an LwDITA file. It implements the reverse of all the mapping rules described above and is executed by the ANT script.

Created on , last edited on