How to import and export LwDITA in PageSeeder

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.

• http://docs.oasis-open.org/dita/LwDITA/v1.0/LwDITA-v1.0.pdf 
• http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html  for background explanations.
• https://github.com/oasis-tcs/dita-lwdita  for DTDs and sample XML.
• PSML element reference

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

Mapping of multimedia XDITA elements to PSML

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

Mapping of XDITA attributes to PSML

Following is a detailed breakdown of mapping between the languages.

Architecture attributes

Localization attributes

Data definition

Figure display attributes

Filtering attribute

Footnote control

Image size

Note type

Processing attribute

Reference attributes

Reuse attributes

Video size

@conref support

This tutorial has been implemented with support for  @conref for <audio>, <dl>, <dentry>, <note>, <ol>, <p>, <pre>, <section>, <simpletable>, <ul>, <video>

To use @conref with the following objects, the content must be wrapped with a <p> element: <fn>, <dt>, <dd>, <li>, <sentry>, <sthead>, <strow>

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.