PML Changelog

New Features

• Footnotes have been added, after this discussion.

  For instructions and examples, please refer to the following links in the PML Nodes Reference Manual:

  • Inline Footnote

  • Footnotes Placeholder

  • Footnote Definition

  • Footnote Reference

  Note

  Footnotes are in an incubating state. This means that the nodes and their attributes might change in future versions, based on user feedback.

Deprecated Features

• The Text Block Syntax used to define text in raw text blocks is now deprecated and will be removed in an upcoming major version.

  For example, instead of writing:

  [code
      int i = 1;
  code]

  ... you need to use the Delimited Text Syntax and write:

  [code
      ~~~
      int i = 1;
      ~~~
  ]

Bug Fixes

Some minor bugs have been fixed.

Backwards-Incompatible Changes

• The PMLC command line interface (CLI) has changed.

  Please refer to the Commands Reference Manual to see the updated list of commands and arguments.

  Most important breaking change:

  • The convert command has been renamed to PML_to_HTML (shortcut: p2h) and is used as follows:

    pmlc PML_to_HTML article.pml
    or:
    pmlc p2h article.pml

    The following old (no more supported) syntax:

    pmlc convert -i article.pml -o output

    ... has been replaced by:

    pmlc p2h article.pml -o output/article.html

    Note that the old -o option specified an output directory, while the new option specifies an output file.

  • The help and tag_info commands haven't yet been re-implemented.

• The source attribute name for image nodes is now required. Instead of writing:

  [image flower.png]

  ... you need to write:

  [image source=flower.png]

• The ! node-name prefix, deprecated in version 2.3.0, is no longer supported. For example, instead of writing [!ins-file ...] you need to write [u:ins_file ...].

• The caption attribute for nodes image, audio, video, youtube_video and table is no longer supported. Please use the new caption node instead.

• User-defined nodes have been temporarily disabled.

  They will be reintroduced in a future version. Their definition, however, will probably differ significantly from their first (experimental) implementation.

• The PMLC GUI (graphical user interface) is no longer supported. PMLC is now a command line tool only, to be used in a terminal emulator (shell or CMD). The GUI might be reintroduced again in a future version.

• Windows/Linux installers are no longer supported. They have been replaced by OS-specific standalone binary executables or, alternatively, a cross-platform Java jar executable that can be run on Windows, Linux, and MacOS systems where the JavaRuntime Environment (JRE) has been installed. PMLC can also be build from source code (works on Windows, Linux, and MacOS).

• The following two fields have been removed from the pml_tags.json file (created by the export_tags command): default_attribute_id and closing_tag.

  The position field has been added to attributes as a replacement for default_attribute_id, which is more versatile for future improvements.

New Features

• Besides defining options via the command line, it is now also possible to define them inside the PML document, or in a shared options file. Please read Options for more information.

• The following PMLC commands have been added:

  • info

  • PDML_to_XML

  • PDML_to_standalone

  • create_commands_manual

  Please refer to the Commands Reference Manual for more information.

  Note

  The PDML_to_XML and PDML_to_standalone commands cannot be used to convert PML documents (only PDML documents are supported). Commands PML_to_XML and PML_to_standalone will be added later.

• Custom CSS files are now supported.

• The location of media assets is no longer restricted to specific URLs. Any URL that is valid in the browser can now be specified.

• PMLC is now available as:

  • A single, standalone binary executable for Windows or Linux.

  • A single zip file containing Java jar files and an OS script file to launch PMLC. This requires the Java runtime version 17 or later to be installed on the PC. Hence, PMLC can now be be executed on Windows, Linux, and MacOS.

  • Java source code that can be compiled and build into jar files that can be executed by a JVM (works on Windows, Linux, and MacOS).

  Note

  As stated already, Windows/Linux installers are no longer supported.

• There is now an auto-generated Commands Reference Manual describing all PMLC commands.

• Semantic node validation is now implemented (but not yet applied to all nodes).

  For example, list nodes can only contain el nodes, and each el node must be a child of a list node.

• The PMLC source code (a complete rewrite in Java) is now more modular, featuring many under-the-hood improvements that will be beneficial in the future. PMLC is now much more time and space efficient, and everything has been set up to evolve as an open-source project.

• The meaning of the PMLC acronym has been changed from PML to HTML Converter to PML Companion.

Bug Fixes

All known bugs have been fixed.

New Features

• Script Nodes have been added. Script nodes enable you to embed source code in a PML document, and execute it when the document is parsed. For more information please refer to Script Nodes.

• Node table_data: Besides using a comma or tab as cell separator, a vertical bar (|) or a semicolon (;) can now also be used.

Deprecated Features

• The syntax for nodes whose name is prefixed with ! has changed, as shown in the following table:

  Old Syntax	New Syntax
  [!ins-file ...]	[u:ins_file ...]
  [!get ...]	[u:get ...]
  [!set ...]	[u:set ...]

  The old syntax will no more be supported in a future version.

• The method to define user-defined-nodes will probably change in the future, as explained here.

New Features

• User-defined nodes have been added. They allow you to create your own, customized PML nodes (in addition to PML's standard nodes) and use them in your documents.

  For more information please refer to chapter User-Defined Nodes.

• Unicode escape sequences above FFFF are now supported. This is useful to insert emoticons and some Asian characters.

  The existing syntax for 4 hex digits Unicode escapes is \uhhhh.

  The new (additional) syntax for 8 hex digits Unicode escapes is \Uhhhhhhhh. Note the uppercase U which is used to denote that 8 hex digits are used.

  Examples are shown in chapter Escape Characters of the user manual.

• Field child_nodes_allowed has been added in the JSON file created with command export_tags.

Bug Fixes

• When Unicode characters above FFFF are inserted into a PML document with copy/paste, they are now correctly written into the HTML target file.

Bug Fixes

• The id attribute for nodes title and subtitle is now correctly rendered in HTML.

• All errors are now displayed in OS err.

Improvements

• File CHANGELOG.txt in the converter's directory has been replaced by by an online document written in PML. The PML source code is available in Github repository.

Backwards-Incompatible Changes

• The title of a chapter is now defined with a separate node following the ch node. The title can no longer be defined with an attribute. Instead of writing:

  [ch (title="My Title")
      text
  ]

  ... we have to write:

  [ch [title My Title]
      text
  ]

  Note

  While the title attribute was limited to plain text, any inline markup can now be used in title nodes, e.g.

  [title A [i nice] side effect]

• The following attributes have been removed from the doc (document) node: title, authors, and date.

  Instead of a title attribute, a title node must be used (as for chapters), e.g.

  [doc [title My Title]
      text
  ]

  Instead of authors and date attributes, these information can simply be written as text, e.g.:

  [doc [title My Title]
      Author: your name
  
      Published: 2021-09-03
  ]

  In a future version there will be a dedicated meta node that will hold data like author, date, version, abstract, etc., as well as other, user-defined meta-data

• The title attribute has been removed from all nodes. Please refer to the previous two items for doc and ch nodes. For all other nodes, the new header node (see below) should be used instead of the old title attribute.

  Example:

  Old code:

  [el (title = "List element header")
      ...
  ]

  New code:

  [el [header List element header]
      ...
  ]

• Lenient parsing is now supported differently:

  • Attributes must be enclosed in parentheses, except for nodes that have only attributes (no child-nodes)

    Example: [foo (a1=v1 a2=v2) ... ]

  • The attribute continuation character \ at the end of a line is no more necessary and therefore no more supported.

  • Attribute values that contain spaces must be enclosed in quotes.

    Example: path = "name with spaces.png"

    For more information please refer to the user manual.

• The syntax for using constants has changed

  The syntax for declaring a constant changed from:

  [const name = value]

  ... to:

  [!set name = value]

  Using a constant changed from:

  <<value>>

  ... to:

  [!get name]

  For more information please refer to the user manual

• The syntax for inserting a file has changed from:

  [insert file=sub-chapter.pml]

  ... to:

  [!ins-file path=sub-chapter.pml]

  For more information please refer to the user manual

  Note

  ins-url and ins-env (OS environment variable) will be added in a future version.

• Command line parameter tag_start_stop_symbols has been removed. A node must start with [, and end with ].

New Features

• New parameter open_file_cmd for command convert.

  This argument enables you to automatically open an editor for the first file in which an error was detected.

  For more information, type the following command in a terminal, and look for parameter open_file_cmd:

  pmlc command_info -command convert

• Better format for error messages displayed in the terminal.

• If there are several errors, they are all displayed in the terminal (not just the first one)

• Distinction between canceling errors, non-canceling errors, and warnings

• Customizable error handler (by providing a specific Java class)

• title: A title for a chapter (can include markup, included in the table of contents)

  This node replaces the chapter's title attribute, which is no more supported.

• subtitle: A subtitle for a chapter (can include markup, not included in the table of contents)

• header: A header (small title) above text (can include markup, not included in the table of contents)

[title A [i nice] side effect]

Please refer to the reference manual for more information.

Text parameters are no more limited to text snippets. They can define markup code to be used repetitively. Example:

[!set reused_image="[image source=my-image.png width=600 height=400]"]
...
[!get reused_image]
...
[!get reused_image]

For more information please refer to the user manual.

Bug Fixes

Some minor bugs have been fixed.

Improvements

• Parser

  The previous PML parser (written in PPL) has been replaced by the pXML parser (written in Java). This important change makes PML totally compatible with pXML, and provides a powerful foundation for exciting new features in the future, such as:

  • converting PML to XML, or XML to PML/HTML

  • using XML technology for PML documents (e.g. querying, modifying, transforming and validating a PML AST)

  • using new, future pXML features in PML too (e.g. creating standalone documents, inserting PML snippets retrieved from a URL, etc.)

  For more information on pXML please visit its website.

• User manual

  • Updated to the changes in version 2.0.0

  • Chapter Text processing has been completely rewritten, and the following chapters have been added:

    • Lenient Parsing

    • Whitespace Handling

    • Escape Characters

New Features

New inline nodes:

• sub: Subscript text

• sup: Superscript text

• strike: Strikethrough text

Backwards-Incompatible Changes

Each tag and each attribute have one single identifier. Alternative identifiers are no more supported. This change makes PML documents look more uniform and reduces complexity for editor plugins, tools, etc. Please consult PML's reference manual if you have PML documents created with a previous version and which use identifiers that are no more valid anymore.

New Features

• Command export_tags has been added.

  This command creates a JSON file containing structured data about PML tags and attributes. The JSON file can be used by editor plugins and tools that depend on PML tags and attributes. For more information type pmlc command_info -command export_tags in a terminal.

• The PML user manual and reference manual are now deployed into directory docs of the PML installation directory.

Bug Fixes

The table of contents is now displayed correctly on devices with small screens.

Backwards-Incompatible Changes

• The tag's open/close symbols have changed from {} to []

  Example:

  Old version: {i great}

  New version: [i great]

  If you want to keep {} you can run the converter with the parameter --tag_start_stop_symbols "{}".

• The open/close symbols for embedding variables have changed from [[]] to <<>>

  Example:

  Old version: [[name]]

  New version: <<name>>

New Features

• A new CSS file, named pml-print-default.css, has been added.

  This file has specific styles defined for documents printed in a browser. These styles are also applied when a document is sent to a PDF writer, such as 'Microsoft Print to PDF' in Windows. You can use CSS's full printing support to adapt printed document to your specific needs, such as printing two columns on a page.

• Attribute TOC_title has been added to node document

  It defines the title displayed for the table of contents.

  The default value is "Table of Contents".

• Argument tag_start_stop_symbols has been added.

  It allows you to define which symbols you want to use to start/stop tags. Currently supported values are {} and []

Improvements

• The Javascript code for expanding/collapsing the table of contents has been removed.

  The HTML <details> tag is used instead.

• The Javascript code for sliding the separator between the table of contents and the text has been removed.

New Features

• The PML to HTML Converter is now open-sourced under the GPL 2.

• Development is supported on Linux, macOS, and Windows.

• Support for the Gradle build tool has been added.

• The prism source code syntax highlighter is now supported, as an alternative to lightjs. Please refer to the documentation of nodes document, code, and insert_code for more information.

New Features