Wednesday, August 12, 2015

Document Type Extension Sharing

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

Instead of copying an entire framework configuration folder (like DITA or Docbook), then modifying and distributing it, you can choose to extend that framework and distribute the extension. This way, you benefit from new functionality added to the base framework by newer Oxygen versions and you can still use your customizations.

The steps below describe how to construct and share an extension of the DITA framework that removes certain elements from the content completion list:
  1. Somewhere on your local disk (in a place where you have full write access), create a folder structure like: custom_frameworks/dita-extension.
  2. In the Document Type Association / Locations preferences page, add the path to your custom_frameworks folder in the Additional frameworks directories list. Click OK or Apply to save your changes.
  3. In the Document Type Association preferences page, select the DITA document type configuration and use the Extend button to create an extension for it.
  4. Give the extension a custom name (for example, DITA - Custom), then change its Storage to external, and save it to a path like: path/to/.../custom_frameworks/dita-extension/dita-extension.framework.
  5. Make changes to the extension (for example, go to the Author->Content completion tab and add elements that should not be presented to the end users in the Filter - Remove content completion items list).
  6. Click OK to close the dialog box and then either OK or Apply to save the preferences changes.

After you perform the steps above, in the dita-extension folder you will have a fully functioning framework that can be shared with others.

The framework can be shared with others in several ways:
  • Copy it to their [OXYGEN_DIR]/frameworks directory.
  • Somewhere on the local disk, create a custom_frameworks folder, copy the framework there, and then in the Document Type Association / Locations preferences page, add the path to your custom_frameworks folder in the Additional frameworks directories list.
  • Distribute the framework along with a project by following these steps:
    1. On your local drive, create a directory with full write access that contains the project files and a custom_frameworks folder that contains your dita-extension.
    2. Start the application, go to the Project view, and create a project. Save it in the newly created directory.
    3. In the Document Type Association / Locations preferences page, select Project Options at the bottom of the page.
    4. In the Additional frameworks directories list, add an entry like: ${pd}/custom_frameworks.
    5. Add other resources to your project (for example, you can have all of your DITA content located inside the project folder).
    6. You can then share the new project directory with other users. For example, you can commit it to your version control system and have them update their working copy. When they open the customized project file in the Project view, the new document type becomes available in the list of Document Types.
  • Deploy the framework/document type configuration as an add-on.

After your team members install the framework, they can check in the Document Type Association preferences page (in the list of Document Types) to see if the framework is present and if it appears before the bundled DITA framework (meaning that it has higher priority).

No comments:

Post a Comment