DITA to PowerPoint Publishing Guide

DITA to PowerPoint: Overview

The DITA to PowerPoint plugin provides an option to create a Microsoft PowerPoint slide deck from DITA topics.

What the DITA to PowerPoint plugin does

The DITA to Microsoft PowerPoint plugin makes it possible to create presentations from DITA XML. This is because recent versions of Microsoft applications are based on XML. The plugin includes a default set of PowerPoint master layouts that cover a wide range of slide layouts.

Business benefits

Reusable content is everywhere. What is sometimes challenging is being able to reuse it. The DITA to PowerPoint plugin makes it easier to reuse slide content, in a sustainable and consistent manner.

The typical PowerPoint reuse scenario manifests as an enormous copy-and-paste exercise. Never mind what it takes to get a review or feedback in that paradigm. That's difficult to manage over time. With the DITA to PowerPoint plugin, you can reuse, rearrange, and create new presentations from a library of content and media, in a structured authoring environment. The plugin combines the advantages of a powerful presentation application with the advantages of a versatile content creation and publishing environment.

DITA to PowerPoint: Considerations

Creating Microsoft PowerPoint slides from DITA is an advanced functionality.

Be aware of the following considerations before you start configuring the DITA to PowerPoint solution.
  • You should have access to the Microsoft PowerPoint application.

  • You should have familiarity with Microsoft PowerPoint slide creation and master layouts. Any changes to slide appearance or layout are done in master layouts.

  • The map and topic format should be optimized for slide content. (In other words, not too much text!)

  • Only Heretto CCMS Administrators can create a publishing scenario for DITA to PowerPoint.

  • Only Administrators can modify the DITA to PowerPoint plugin.

  • It's helpful to have oXygen available if you want to modify the default DITA to PowerPoint plugin.

  • The plugin works in DITA-OT 2.5.4. You may need to install it if you do not already have this version in your Heretto CCMS instance.

  • Any modifications to the default plugin are not covered by Heretto CCMS Support.

DITA to PowerPoint Tasks

Review the tasks for this implementation before you start updating your configuration.

Using the default DITA to PowerPoint plugin is a quick way to get started making Microsoft PowerPoint slide decks from DITA topics. The following tasks walk you through the entire process.

Verify that DITA-OT 2.5.4 is Installed

Create a PowerPoint-Ready DITA Map

Create PowerPoint-Ready Topics

Publish the Map to Generate the Slide Deck

Note: If you want to update the plugin to use your own set of master slide layouts, see Advanced DITA to PowerPoint Configuration.

Verify that DITA-OT 2.5.4 is Installed

The DITA to PowerPoint plugin requires DITA-OT 2.5.4 to work properly.

If your Heretto CCMS instance already has the DITA-OT version 2.5.4 installed, you can skip uploading it into the system.
Important: Only Administrators can verity toolkit versions.
  1. In Mozilla Firefox, log in to your Heretto CCMS instance.
  2. In the Dashboard, click Plugins.
  3. In the Plugins screen, click DITA Open Toolkit.
  4. In the Available DITA Open Toolkits list, search for dita-ot-2.5.4.

Upload DITA-OT 2.5.4 to Heretto CCMS

You can run any number of DITA Open Toolkits in Heretto CCMS.

The DITA to PowerPoint plugin is optimized to work with the DITA-OT 2.5.4. If it is not already in your Heretto CCMS instance, you need to install it.
  1. Go to the dita-ot.org web site and download the 2.5.4 toolkit.
  2. In the Mozilla Firefoxbrowser, open Heretto CCMS.
  3. In the Dashboard panel, click Plugins.
  4. On the Plugins screen, click DITA Open Toolkit.
  5. Above the Available DITA Open Toolkits list, click New.
  6. In the Upload a new DITA Open Toolkit window, click Browse, and navigate to the downloads folder.
  7. Select the ZIP file of the DITA-OT 2.5.4 and click Open.
    The system uploads the toolkit (which may take a few minutes), and you will see the new toolkit in the list.

Upload the DITA to PowerPoint Plugins to Heretto CCMS

Ensure that the DITA-OT publishing engine can access the DITA to PowerPoint plugins.

Only Administrators can upload DITA-OT plugins.
  1. Download the DITA to PowerPoint plugins to your local system.
    You can find the plugins on GitHub: https://github.com/Jorsek/dita-ot-plugins.
  2. Open Heretto CCMS in the Mozilla Firefox browser.
    Note: The Plugins configuration is available only in Mozilla Firefox.
  3. In the Dashboard menu, click Plugins and then click DITA Open Toolkit.
  4. Above the Plugins list, click New.
  5. Navigate to the local directory where you downloaded the plugins in the first step.
  6. Brows to and select these three plugins:
    • com.jorsek.powerpoint.zip

    • com.jorsek.intermediate.zip

    • com.jorsek.slide-doctype.zip

    Tip: You can upload multiple plugins at once.
  7. Click Done when all three plugins are listed.
    You'll see the three plugins listed in the Plugins list.

Create a PowerPoint-Ready DITA Map

The map structure for the DITA to PowerPoint solution follows specific guidelines.

Create a map that you can use to create PowerPoint slides from DITA topics. The map structure is flat, that is, all child topics are at the first (and same) level.
  1. In the content library, create a new folder for your PowerPoint DITA content.
  2. In the new folder, click the Create New button.
  3. In the Map Types list, select Default Map.
  4. Type a name for the new map, and click Create and Edit.
    The new map opens.
The map is ready for you to add topics.
Important: Be sure to keep the map structure flat, that is, all topics should be at the first level. Don't nest the topics.

Create PowerPoint-Ready Topics

The Publishing engine (Heretto Connector for DITA Open Toolkit) expects a specific topic format to generate PowerPoint slides from DITA topics.

Before you begin, we recommend establishing a naming convention for topics that you are going to use for slides. For example, prepend slides_ to each topic file name so you know exactly which topics are meant to be output as slides.
PowerPoint-ready topics are based on the generic topic information type. They also include specific metadata that ensure the Publishing engine can transform DITA XML into OOXML for PowerPoint.
Important: Create a topic for each slide that you need. You cannot combine or nest slide topics.
  1. In the content library, in the folder you created for the map, create a new folder for your topics and any media or images as needed.
    Tip: Follow your organization's information architecture for Heretto CCMS folder structure.
  2. Navigate to the topics folder, and click the Create New button.
  3. In the Topic Types list, select Topic.
    Important: The DITA to PowerPoint plugin requires that you only use the Topic template to create slide content.
  4. Type a name for the new topic, and click Create and Edit.
    The new topic opens.
  5. Expand the Attributes tab, on the right side of the Content Editor.
  6. In the Element list, select Topic.
  7. For the outputclass attribute, type the slide layout name you want to use for this content.
    example of outputclass for a slide template
    For a list of the default slide layouts and their names, see Default Slide Layouts Reference.
  8. Add your slide content, according to best practices for slides and presentations.
    Tip: The DITA to PowerPoint plugin automatically populates the slide regions and images for a given slide layout. You can see an example of all the default layouts by publishing the DITA to PowerPoint example map (dita-to-powerpoint-example.ditamap).

Set up the PowerPoint Publishing Scenario

Configure a publishing scenario that you can use to generate the PowerPoint slides.

The publishing scenario provides the Heretto Connector for DITA Open Toolkit with the needed parameters to publish the PowerPoint slide output. Only Administrators can configure publishing scenarios.
  1. Open Heretto CCMS in the Mozilla Firefox browser.
    Note: The Plugins configuration is available only in Mozilla Firefox.
  2. In the Dashboard menu, click Plugins and then click DITA Open Toolkit.
  3. In the DITA-OT Plugins list, verify that these three plugins are installed.
    • com.jorsek.powerpoint

    • com.jorsek.intermediate

    • com.jorsek.slide-doctype

  4. Above the Scenarios list, click New.
  5. Type a name for the publishing scenario.
    This is the name you'll see in the Scenarios list once you've created it.
  6. In the toolkit list, select dita-ot-2.5.4.
  7. In the version list, select 2.x.
  8. Specify the build file to use to create the slides output.
    1. In the Select Ant File to Run area, click Change.
    2. In the Pick a File list, find and expand the com.jorsek.powerpoint plugin.
    3. In the plugin folder, select the build.xml file.
      The Pick a File list closes automatically when you select the file.
  9. Set the parameters for the publishing scenario.
    1. Click Add a Parameter.
    2. For the parameter name, type transtype.
    3. For the parameter type, select Simple String Value.
    4. For the value, type jskPowerpoint.
    5. Don't enable the User Settable option.
  10. Click Save.
    The screen refreshes and you'll see your new publishing scenario at the end of the list.

Publish the Map to Generate the Slide Deck

Publishing with Heretto CCMS is a quick and efficient process.

Once you have publishing scenarios created, you can associate them with maps to create output, in this case a PowerPoint slide deck.
  1. In the content library, open the map that you made for the slides.
  2. In the upper right corner, click Publish.
  3. In the Publish list, select the publishing scenario that you created for publishing slides.
  4. Type a description, leave the remaining settings at their default, and click Publish.
    The publishing starts and provides status messages. When the publishing process is complete, you'll see the completed job in the Finished list.
  5. You can open the new slide deck either by opening the publishing job or by downloading the new deck.
When you open the PowerPoint output for the first time, you may get warnings about the slide deck needing to be repaired. Click through the error messages; there's really nothing wrong with the slides. Be sure to save the repaired presentation somewhere on your local system.

After you Publish the Slides

The slide deck that publishes from DITA topics needs a little cleanup to really be a valuable tool for a presentation.

Check that the text boxes are nicely aligned.

You may need to adjust the placement and width of text boxes on the slides so that they aren't overlapping.

Check that images and graphics are properly sized.

You may need to adjust the size and placement of images on the slides.

Add any references or links to charts, tables, or spreadsheets generated from other Microsoft applications.

If you used the chart or spreadsheet slide layout, you'll need to connect the slide to those objects from their respective Microsoft applications. You can also create these objects in the slides, as needed. Follow the guidance from Microsoft.

Delete the title slide that contains the map name.

The DITA to PowerPoint plugin automatically creates a slide that contains the name of the map. You don't need that slide for a presentation so it can be deleted. It's the first slide in the slide deck.

Check the rest of the slides to be sure the templates are properly applied.

If, in the remaining slides, you see any that have the green_title template applied, but should be a different template, that indicates that you probably mis-typed the template name for the outputclass attribute. To resolve quickly, just pick the correct slide layout in PowerPoint. To ensure you don't keep having this issue, be sure to check the outputclass attribute for the affected DITA file. Refer to Create PowerPoint-Ready Topics for a refresher.

Default Slide Layouts Reference

The DITA to PowerPoint plugin contains these default slide layouts.

Slide nameDescriptionValue for outputclass attribute
Title slidesFive different background colors for title slides and a logo. The green_title layout is the default if another slide layout is not specified.green_title, aqua_title, yellow_title, red_orange_title, dark_gray_title
List slideThis layout creates a slide with a title and an ordered or unordered list.list_slide
Chart slideThis layout creates a slide with a title and a placeholder for inserting a chart generated from Microsoft applications.chart_slide
Dark background definition slideThis layout creates a slide with a dark gray background and is meant for presenting definitions. The title is whatever is being defined, and the text in the body is the definition.dark_definition
Light background definition slideThis layout is the same as dark_definition but the background is white.light_definition
Gray tip or exercise slideThis layout creates a slide best suited for providing an exercise or a tip.gray_tip_or_exercise
Light background impact slideThis layout creates a slide with a white background, and large text with no title. The title becomes the text in the output.light_impact
Left image and title text slideThis layout creates a slide with an image on the left, space for text on the right, and a white backgroundleft_image_title_text
Left image and blue background text slideThis layout creates a slide with an image on the left, space for text on the right, and an aqua blue backgroundleft_image_aqua
Blue text background and right image slideThis layout creates a slide with an image on the right, space for text on the left, and a blue backgroundblue_background_right_graphic
White text background and right image slideThis layout creates a slide with an image on the right, space for text on the left, and a white backgroundwhite_background_right_graphic
Full background image and bottom text slideThis layout creates a slide with a full background image and text along the bottom.full_image_text_bottom
Light background, full-size image and titleThis layout creates a slide with a title and full-size image on a white background. The text overlays the image.light_full_image_and_title
Dark background, full-size imageThis layout creates a slide with a title and full-size image on a dark background. The text overlays the image.dark_full_image_and_text
Title and imageThis layout creates a slide with just a title and space for an image. It's good for screenshots.title_and_image
White background with logo for a quote.This layout creates a slide designed to show a quote.white_quote_and_logo
Aqua background with logo for a quoteThis layout creates a slide designed to show a quote.aqua_quote_and_logo
Speaker slideThis layout creates a slide that can include a speaker photo, name, and short biography or other text.speaker
Spreadsheet or table slideThis layout creates a slide with a title and a placeholder for inserting a spreadsheet or table generated from Microsoft applications.spreadsheet_table
Left-aligned heading on a white backgroundThis layout creates a slide with only a left-aligned heading, on a white background.blank_with_left_aligned_header_light
Left-aligned heading on a dark backgroundThis layout creates a slide with only a left-aligned heading, on a dark background.blank_with_left_aligned_header_dark
Thank you This layout creates a slide with a aqua background and the words “Thank You” centered on the slide.thank_you

Advanced DITA to PowerPoint Configuration

The slide layouts included in the Heretto DITA to PowerPoint plugin are suitable for many slide outputs. However, if you want to change the colors or other visual aspects of the slides, you can consider updating the plugin to include your own organization's master layouts.

Major configuration activities to use your own set of master slide layouts

Create a new PowerPoint template with master slide layouts and master notes layouts

Download the default DITA to PowerPoint plugin

Update the mappings.xml file in the plugin

Add your PowerPoint slide template file to the plugin

Update the ppt-build.xml file to use the new PowerPoint template

Upload the Updated Plugin to Heretto CCMS

Create a sample map and topics for testing purposes

Test the modifications

Tools requirements

XML Editor
To modify the DITA to PowerPoint plugin and the XML version of the PowerPoint template, you need access to a full XML editor. The instructions provided in this document are based on using the oXygen editor.
Microsoft PowerPoint
To create a PowerPoint template that you can use in the plugin, you need access to a fully licensed copy of PowerPoint. You cannot make the needed changes in the Office Online version.

Considerations

Making changes to the DITA to PowerPoint plugin and the slide master layouts are advanced actions, and you risk breaking the plugin. Attempt this only if you are comfortable with plugin structure, modifying XSL files, and have some familiarity with PowerPoint master slide layouts.

CAUTION: This activity involves modifying the structure of a DITA-OT plugin and a PowerPoint template. Only make these changes if you have experience with editing DITA-OT plugins, and are comfortable with making changes to XSL files. You also need to update the PowerPoint slides as XML objects.
Remember: Any changes you make to the default plugin are outside of the Heretto support policy.
Restriction: Only Administrators can make changes to the DITA-OT plugins in the system.

Create a New PowerPoint Template for the Plugin

The DITA to PowerPoint plugin uses a default template provided by Heretto. You can add your own template by creating one in Microsoft PowerPoint.

Create a PowerPoint template and modify it so you can use it in the Heretto DITA to PowerPoint plugin.
  1. Open Microsoft PowerPoint.
  2. Create a new template based on one of the default themes.
    Note: If your organization already has a default PowerPoint template, you can start with that.
  3. Save the new template locally, as a *.pptx file.
    Be sure the new file name does not contain any white spaces.You can use either hyphen or underscore characters instead. For example, my_new_pptx_template.pptx.
  4. Update the template as needed.
    1. Change the layouts, colors, fonts as needed.
    2. Delete any layouts you won't use.
    3. Save any changes you make.
  5. When the template updates are complete, click View > Slide Master.
  6. In the Slide Master panel, select a slide template, and click Rename.
    Important: The very first layout in the Slide Master pane is the master for the theme; don't select that one! Start with the layouts immediately following the very first one.
    pptx slide master example
  7. In the Rename Layout box, type a layout name and click Rename.
    Use these conventions to rename the layouts to ensure that the DITA to PowerPoint plugin can use them.
    • Starts with a letter

    • Uses only lowercase letters

    • Contains no spaces (use hyphens or underscores)

    slide master layout name
  8. Repeat the previous step until you've renamed all of the layouts to match this convention.
    Tip: You can check that you've renamed a layout by hovering over it in the Slide Master panel. You'll see the slide name in the hover text.
    check slide master layout name
  9. Save your changes.
  10. Click Close Master.
  11. Click View > Notes Master.
    Important: Don't skip this step even if you don't use a separate notes layout. The plugin expects to find a notes master in the PowerPoint presentation. The build fails without it. Just opening this master is enough to create a notes master for this purpose.
  12. Make any adjustments to the notes layout, as needed.
  13. Save your changes and click Close Master.
You've created a PowerPoint template that you can use in the DITA to PowerPoint plugin. (Give yourself a little pat on the back!)

Add a Matching Name to PowerPoint Slide Layouts

By default, the PowerPoint slide layouts are missing the matching attribute that the DITA to PowerPoint plugin relies on for identifying each layout.

CAUTION: Before you begin this task, be sure that you've closed the PowerPoint template in the Microsoft PowerPoint application. Having the template open in two applications at the same time will corrupt the file.
Update the slide layout XML for each slide template to include the matchingName attribute.
  1. Open the oXygen editor.
  2. From oXygen, navigate to and open (double-click) the PowerPoint template you created.
    oXygen opens the template in the Archive Browser panel.
    pptx in oxygen archive browser
  3. In the Archive Browser, expand the ppt and slideLayouts folders.
    slide layouts folder
  4. Add the matchingName attribute to each slide layout in the slideLayouts folder.
    1. Double-click a slide layout file.
    2. In the open file, format and indent the syntax so you can more easily read the header.
    3. In the second name space declaration (xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"), put your cursor right after the quote mark and press space.
      The attributes menu opens.
      matchingName attribute
    4. Select matchingName.
    5. For the value, type the exact text that is shown in the name attribute in the first line of syntax.
      The names should look familiar from the renaming exercise you performed previously.
      title slide attribute
    6. Save and close the file.
    7. Repeat until you've added a matchingName attribute for all of the slide layout files in the slideLayouts folder.
    Tip: Save often in this process! Also, don't make any other changes in these files or you risk corrupting the template.
  5. Once you've added the matchingName attribute to all of the layouts, click the Close button in the Archive Browser panel.
    archive browser close button

Download the default DITA to PowerPoint Plugin

The default plugin is the foundation for any updates you want to make.

Download the com.jorsek.powerpoint plugin to your local system.
  1. Open Heretto CCMS in the Mozilla Firefox browser.
    Currently you can access the publishing engines only in Mozilla Firefox.
  2. On the Dashboard, click Plugins, and then select DITA Open Toolkit.
  3. In the DITA-OT Plugins list, click com.jorsek.powerpoint.
    In the popup, select Save File to download the plugin locally.
  4. When the download is complete, move the ZIP file to a working directory and unzip it.
Tip: Keep a copy of the original ZIP file in case you need to reinstate it.

Update the mappings.xml File

The mappings.xml file provides the matching mechanism to convert DITA topics to slides.

This task assumes you've renamed all of the PowerPoint slide layouts according to the naming conventions described in Create a New PowerPoint Template for the Plugin.
Update the mappings.xml file to ensure the DITA to PowerPoint plugin can transform your DITA topics to the PowerPoint slide layouts.
  1. Open your PowerPoint template in in the PowerPoint application.
  2. Click View > Slide Master.
  3. Open oXygen, and navigate to the unzipped com.jorsek.powerpoint plugin.
  4. In the config folder, open mappings.xml.
    config mappings in plugin
    This file lists all the slide layout labels for the PowerPoint template. The plugin uses this mapping to convert the DITA topics to PowerPoint.
  5. In PowerPoint, hover over the first layout below the theme master.
    The hover text shows the layout label, and whether it's used by any slides. We only care about the label.slide layout info
  6. In oXygen, type that label into a mapping entry for both the source and the layout.
    For example, in the previous screenshot, the layout name is title_and_caption, so our mapping entry looks like this.
    pptx mappings example syntax
    Important: The mapping entries have to match exactly to the slide layout name. If they don't, you will get unexpected results when you try to publish the PowerPoint output.
  7. Repeat this process until you've created a mapping entry for all of your slide layouts.
  8. At the very top of the mappings.xml file, designate one of your layouts as the default mapping.
    In this example, we designate the title_and_content layout as the default. Don't use the basic title slide as the default; pick a different template instead.
    default mapping in mappings file
    The plugin applies this template if it cannot find a matching template, based on the outputclass you specify on a topic. (Refer to Create PowerPoint-Ready Topics for a reminder on that configuration.)
  9. Delete any extra mapping entries, but leave the stub mapping at the end of the file, for title_slide, alone.
    The publishing process needs this default template to properly create a slide deck.
  10. Save your changes.

Add your PowerPoint Template File to the Plugin

The PowerPoint template you created needs to be a part of the plugin folder structure.

The DITA to PowerPoint plugin has a template folder for PowerPoint template files.
Important: The template folder has several files in it already. Do not delete or remove them.
  1. In Finder (or File Explorer), locate the com.jorsek.powerpoint plugin folder.
  2. Open the template folder, and copy in your PowerPoint slide template.

Update the ppt-build.xml File to Use the New PowerPoint Template

The ppt-build.xml file contains the instructions that the plugin uses to process DITA content into PowerPoint slides, including applying the template you created.

Ensure the DITA to PowerPoint plugin is configured to apply the PowerPoint template you created.
  1. In oXygen, navigate to the unzipped com.jorsek.powerpoint plugin, and open the ppt-build.xml file.
  2. Locate the args.jsk.powerpoint.template property, near line 27 in the file.
  3. Copy the property, and paste it near the one you copied.
  4. In the value string, replace jorsek_deck_master.pptx with the file name of your slide template.
    Important: Be careful not to change anything else in the value string, including the trailing forward slash after the file name.
    template file update
  5. Save and close the file.

Upload the Updated Plugin to Heretto CCMS

Ensure that the DITA-OT publishing engine can access the changes you made to the PowerPoint plugin.

Only Administrators can upload DITA-OT plugins.
Important: This process overwrites the original com.jorsek.powerpoint plugin. You can always reinstate the original by re-downloading it from Github. Refer to Upload the DITA to PowerPoint Plugins to Heretto CCMS for more information.
  1. Create a ZIP file of the updated plugin.
    Plugins must be ZIP files to be uploaded into Heretto CCMS.
    Important: Don't change the name of the plugin folder, com.jorsek.powerpoint.
  2. Open Heretto CCMS in the Mozilla Firefox browser.
    Note: The Plugins configuration is available only in Mozilla Firefox.
  3. In the Dashboard menu, click Plugins and then click DITA Open Toolkit.
  4. Above the Plugins list, click New.
  5. Browse to, and select, the updated plugin ZIP file.
  6. When you see the plugin listed, click Done.
    The updated plugin overwrites the original com.jorsek.powerpoint plugin with your changes.

Create a Sample Map and Topics that use the New Slide Layouts

To see the new PowerPoint template in action, set up a sample DITA map and topics that refer to the layouts.

Create a sample map and topics so you can test the plugin and explore the resulting PowerPoint output.
  1. Create a sample map by following the guidance provided in this topic: Create a PowerPoint-Ready DITA Map.
  2. Create sample topics by following the guidance provided in this topic: Create PowerPoint-Ready Topics.
  3. When you're creating the topics, be sure to use your new slide layout labels for the outputclass attribute.
    Tip: Open the local copy of mappings.xml to see a list of your layout options.
Once you have a sample map and topics, you're ready to test the updated DITA to PowerPoint plugin.

Test the Modifications

Testing the new plugin ensures that you can publish the output you expect.

Any time you add a plugin to the system, you should test that you can achieve successful publishing.
  1. Set up a new publishing scenario that uses your updated plugin.
    Refer to Set up the PowerPoint Publishing Scenario for the specific steps.
  2. Publish your sample map with the new publishing scenario.
    Refer to Publish the Map to Generate the Slide Deck for the specific steps.
  3. Perform any slide clean-up that you may need to do.