Advanced PML Features

Introduction

This document describes advanced PML features.

Advanced features aim to simplify and automate the writing/publishing process as far as possible. As a result they can significantly increase productivity, reliability, and maintainability, especially in professional environments where documents change often, content depends on external resources, or parts of the document must be created and updated automatically.

For example, advanced features enable you to:

• embed Javascript source code in PML documents, to dynamically generate PML code and resources (e.g. graphical components like diagrams) at build-time, and to execute external OS commands and scripts that can create content or do anything else related to the PML document

• create user-defined nodes which you can then use in all your PML documents, in addition to the standard nodes provided by PML

• convert a PML document to an XML document (or vice versa) and apply XML technologies to PML documents (e.g. validate, query, modify, or transform documents)

• use a Java API to configure and execute PML commands programmatically

The setup/configuration of advanced features requires some technical knowledge. However, once configured by skilled people, these features are often easy to use by non-tech-savvy document creators. This potentially eliminates the need for complex tool chains that must be installed, configured, and maintained.

Warnings

This document is a work in progress.

Advanced features are first published as an experimental feature. This means that you can try out the feature, but you need to be aware that:

• The feature is not fully developed yet, and may contain bugs. You might encounter limitations and malfunctions.

• The feature is not guaranteed to be backwards-compatible. Anything can change in future versions, although this is avoided as far as possible.

• The documentation might be incomplete and change in future releases.

Experimental features are tagged by the suffix (Experimental) in their title.

If you encounter a bug or miss an important functionality, then please submit an issue.

If you have a question or want to discuss anything (e.g. an idea or enhancement), then please create a discussion.

Script Nodes (Experimental)

'Script Nodes' is arguably the most powerful PML feature. They allow you to embed Javascript source code in a PML document. The code is executed when the PML document is parsed.

Script Nodes can help to considerably simplify and automate the writing process, especially in case of big, complex, or frequently changing documents.

Here are just a few examples of what you can do:

• Automatically update text or data snippets in a document.

  Example: Update the last updated date field each time a document is re-generated.

• Retrieve text and data from external resources like files, URLs, databases, etc.

  Example: Retrieve a version number stored in a JSON file, and insert it in the document.

• Generate text and data programmatically.

  Example: Insert compound interest tables that are generated by an embedded Javascript function.

• Use a calculator to compute values to be inserted in the document.

  Example: Calculate, round, and format product prices to be inserted in the document, using an arithmetic expression.

• Conditionally include/exclude parts of the document, depending on the target audience.

  Example: An exam paper printed for students contains only questions, while the teachers' edition also contains the answers.

• Dynamically generate and insert graphical components like diagrams into a PML document.

  Example: Insert PlantUML source code into a document, and render it as a MindMap diagram in the target document.

• Ask the user for input on the console or in a GUI dialog.

  Example: Ask the user if all graphic files should be re-generated.

• Execute external programs and OS scripts to generate PML code on-the-fly, or to do whatever else can be done on the machine.

  Example: Execute an external program (written in any programming language) to retrieve some real-time data from an Excel sheet, a database, or from the cloud, and then generate the PML markup code for some tables to be inserted in the PML document. Moreover, send an email to inform managers about the update. And add an entry in a log file located on the company's headquarter server.

Script Nodes is a feature of the Practical Data and Markup Language (PDML). But since PML uses PDML under the hood, Script Nodes, as well as all other PDML features, are supported in PML too. All documentation related to Script Nodes is available on PDML's website. Please refer to the following links for more information:

• Chapter Script Nodes in the PDML Extensions User Manual

• Chapter Scripting API in the PDML Extensions Reference Manual

• PDML Scripting Examples

User-Defined Nodes (Experimental)