PML Changelog

Version 4.0.0 2023-02-23

PMLC 4.0.0 is a major update including breaking syntax changes, all known bugs fixed, but no new features.

All planned breaking changes have been implemented, so that fewer breaking changes will appear in future versions.

Before upgrading, please be aware of the breaking changes described below.

Note

The next PMLC version will possibly provide a PML document updater. This updater will enable you to automatically update your PML documents written with a previous PMLC version, so that you don't need to update your documents manually. If you have a lot of documents to update, you might want to wait for the next version before upgrading.

Backwards-Incompatible Changes

Attributes Containing Text Replaced With Child-Nodes

All attributes that were used to define text rendered in the document have been removed. Instead of using attributes, child nodes must now be used. The advantage is that you can now use formatted/styled content, which was not possible with attributes.

The following nodes are affected: link, xref, quote, admon.

Node `link`

Attribute text has been removed. The text for the link must be contained in the node.

Hence, this code:

[link url=http://example.com text="an example"]

... must be replaced by:

[link (url=http://example.com) an example]

Note that the url attribute must now be enclosed in parenthesis.

The text can now be formatted/styled by using inline nodes:

[link (url=http://example.com) a [i striking] example]

If no text is specified, then the URL will be used as text:

[link (url=http://example.com)]

Note

If you have a lot of link nodes to update, you might want to use a regex like the following one in your editor:

 Search field: \[link\s*url\s*=\s*([^\s]*)\s*text\s*=\s*"?(.*?)"?\]
Replace field: [link (url=$1) $2]

I used this to update all PDML/PML docs. Note that the above regex might or might not work in your environment. You might need to adapt it. Test well and verify each replacement whenever using regexes to replace text!

Node `xref`

Attribute text has been removed. The text must be contained in the node.

Moreover attribute node_id has been renamed to ref_id.

Hence, this code:

[xref node_id=intro text="chapter Introduction"]

... must be replaced by:

[xref (ref_id=intro) chapter Introduction]

Note that the ref_id attribute must be enclosed in parenthesis.

The text can now be formatted/styled by using inline nodes:

[xref (ref_id=H2O) H[sub 2]O]

In case of a reference to a chapter, the chapter's title will be used as text if no text is explicitly specified:

[ch (id=intro) [title Introduction]
    This article ...
]
...
As said in chapter [xref (ref_id=intro)], ...

Text used for the above link: Introduction.

Node `quote`

Attribute source has been removed. A new node named qsource is used within node quote to define the source of the quote.

Hence, this code:

[quote (source="Scott Adams")
    Simplicity transforms ordinary into amazing.
]

... must be replaced by:

[quote
    Simplicity transforms ordinary into amazing.
    [qsource Scott Adams]
]

Inline nodes can be used in qsource to style the source, add links, etc.

The em-dash (— Unicode U+2014) that was previously rendered in front of every source (using CSS selector .pml-quote-source::before) has been removed, because it is not always desired.

If you want to prefix the source with a simple hyphen, or a real em-dash, you can write:

[qsource - name]
[qsource \u2014 name]

Note: A future PML version might provide a specific em-dash node, so that you can write:

[qsource [emdash] name]

Alternatively you could also use a modified CSS file to always render an em-dash.

Node `admon`

Attribute label has been removed. A new node named alabel is used within node admon to define the label of the admonition.

Hence, this code:

[admon (label=Tip)
    You can also ...
]

... must be replaced by:

[admon [alabel Tip]
    You can also ...
]

Inline nodes can be used in alabel to style it.

Additional Breaking Changes

Node options must now be defined before node doc (not inside node doc). Hence this code:

[doc
    [options
        [TOC_title Aperçu]
    ]
    text
]

... must be replaced by:

[options
    [TOC_title Aperçu]
]
[doc
    text
]

Node table_data has been renamed to sim_table (simple table).

Hence this code:
```
[table_data
    ~~~
    cell 1.1, cell 1.2
    cell 2.1, cell 2.2
    ~~~
]
```
... must be replaced by:
```
[sim_table
    ~~~
    cell 1.1, cell 1.2
    cell 2.1, cell 2.2
    ~~~
]
```
Note

In the future, node sim_list will be added (as a counterpart of sim_table). This will allow you to define simple, non-nested lists with a much more succinct syntax.
The so-called Text Block Syntax used to define raw text blocks was deprecated in version 3.1.0. and has now been removed.

For example, instead of writing:
```
[code
    int i = 1;
code]
```
... you need to use the Delimited Text Syntax and write:
```
[code
    ~~~
    int i = 1;
    ~~~
]
```
The following nodes are affected by this change: code, input, output, html, sim_table.
Command export_tags has been renamed to export_meta_data.

The default output file name has changed from pml_tags.json to PML_meta_data.json.

The content of the JSON file has changed as follows:
- Field pml_tags has been renamed to pml_meta.
- Field tags has been renamed to nodes.
The behavior of CLI argument CSS_files (command PML_to_HTML) has changed.

When a directory is specified then only files with extension .css will be copied.

The behavior remains unchanged if a file is specified. The file will be copied into the target directory, regardless of its extension.

This change has been discussed here.
The individual repositories for PML documentation (e.g. user manual, reference manuals, etc.) have been removed, and their content has been transferred into a single pml-website repository.

All issues and discussion have been transferred too.
The PMLC source code has been substantially refactored to make it more modular and maintainable. PMLC also uses the latest version of the PDML parser, as well as the latest version of GraalVM to create standalone OS binaries.

New Logo

The following new PML logo is now used:

The 'm' within the square brackets stands for 'markup'.

The above logo is a variation of the following PDML logo (many thanks for this contribution by Shelby Landen).

The 'dm' within the square brackets stands for 'data and markup'.

Bug Fixes

All known bugs have been fixed, including the following ones: #86, #87, #90, #91, #93, #96, #98)

Version 3.1.0 2022-10-03

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:
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.

Version 3.0.0 2022-08-19

PMLC 3.0.0 is a major update.

The tool has been completely rewritten in Java (PPL is no longer used). Some features are therefore no longer available, some will be added again later.

However, there are only 3 minor changes related to the PML syntax: the ! symbol and the caption attribute are no longer supported, and the source attribute name in image nodes must be specified explicitly, as explained below.

Before deciding to upgrade to version 3.0.0, have a look at the changes described below.

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.

Version 2.3.0 2022-02-11

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.

Version 2.2.0 2021-12-14

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.

Version 2.1.0 2021-09-09

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.

Version 2.0.0 2021-09-03

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

Better error handling

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)

New block nodes

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)

Note

Inline markup can be used in title, subtitle, and header nodes, e.g.

[title A [i nice] side effect]

Please refer to the reference manual for more information.

More powerful text parameters

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

Version 1.5.0 2021-06-08

New Features

New inline nodes:

sub: Subscript text
sup: Superscript text
strike: Strikethrough text

Version 1.4.0 2021-04-16

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.

Version 1.3.0 2021-03-09

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.

Version 1.2.0 2021-02-10

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.

Version 1.1.0 2021-01-14

New Features

New Nodes

table_data: Simple table data defined as plain CSV text, and rendered as a table.
table: A table layout composed of rows and columns.

Besides just text, each cell in the table can have complex content, including nested tables. Conceptually similar to a HTML table.
monospace: A paragraph in which whitespace is preserved, and a monospace font is used.
division: A division or section in the document. Similar to a div tag in HTML.
span: An inline node typically used to render a HTML <span>...</span> inline element with a specific set of HTML attributes.

New Attributes

caption: A small text displayed below the node. Available for the following tags: image, audio, video, youtube_video, and table

New Command Line Arguments

Added command line arguments HTML_header and HTML_footer to the PML to HTML Converter. Allows you to:

Provide a custom HTML header/footer for each document, or generate only the HTML body code (no header/footer).
Customize the style of the resulting HTML by providing your specific CSS file(s), in addition to PML's default CSS file, or as a replacement.

Latest Update	2023-02-23
First Published	2021-01-14
License	CC BY-ND 4.0
Author	Christian Neumanns
Website	https://pml-lang.dev/
PML Markup Code	Github

PML Changelog

Version 4.0.0 2023-02-23

Backwards-Incompatible Changes

Attributes Containing Text Replaced With Child-Nodes

Node link

Node xref

Node quote

Node admon

Additional Breaking Changes

New Logo

Bug Fixes

Version 3.1.0 2022-10-03

New Features

Deprecated Features

Bug Fixes

Version 3.0.0 2022-08-19

Backwards-Incompatible Changes

New Features

Bug Fixes

Version 2.3.0 2022-02-11

New Features

Deprecated Features

Version 2.2.0 2021-12-14

New Features

Bug Fixes

Version 2.1.0 2021-09-09

Bug Fixes

Improvements

Version 2.0.0 2021-09-03

Backwards-Incompatible Changes

New Features

Bug Fixes

Improvements

Version 1.5.0 2021-06-08

New Features

Version 1.4.0 2021-04-16

Backwards-Incompatible Changes

New Features

Bug Fixes

Version 1.3.0 2021-03-09

Backwards-Incompatible Changes

New Features

Improvements

Version 1.2.0 2021-02-10

New Features

Version 1.1.0 2021-01-14

New Features

New Nodes

New Attributes

New Command Line Arguments

Node `link`

Node `xref`

Node `quote`

Node `admon`