PDML Extensions User Manual

Single-line Comment

A single-line comment starts with ^// and ends at the end of line. It can start at any position in a line:

^// Single-line comment covering the whole line

text text ^// Trailing single-line comment

The line break at the end of the comment (i.e. LF on Unix/Linux; CRLF on Windows) is part of the comment. If you want the line break to be excluded from the comment (needed rarely), you can use ^/ (instead of ^//) to start the comment:

^// Line break included in comment
^/  Line break excluded from comment

Multi-line Comment

A multi-line comment starts with ^/* and ends with */:

^/*
multi
line
comment
*/

It can start at any position in a line, and it ends at any subsequent position in the same line or in a subsequent line:

This is a ^/* nice */ huge advantage.

text ^/* this text is
commented out */ text

You can nest multi-line comments. In other words, a comment can contain another comment:

^/* comment ^/* nested comment */ comment */

They can be nested to any level:

^/* level 1 (not nested)
    ^/* level 2
        ^/* level 3 */
    */
*/

If a multi-line comment contains */, then it must be embedded in ^/** ... **/ (i.e. two stars to start and end the comment):

^/**
    This comment contains */ which would end
    it if it used only one star to start it
**/

You can use as many stars as needed, but the number of stars to start and end the comment must be the same:

^/***
    This comment contains **/
***/

You can also use plenty of stars to emphasize comments:

^/*********************************************
  Important!
  To avoid rotten tomatoes being thrown at you,
  you MUST ...
  *********************************************/

Rationale

Unicode Escape Sequences provide a practical solution for the following potential challenges:

• Some characters (i.e. Unicode code points) are cumbersome or even impossible to type, depending on the user's input device (keyboard, tablet, phone, etc.), OS, and software setup.

  For example, Unicode emoticons (such as 😀, U+1F600) are not present on a standard keyboard. Depending on your device and its setup, you might be able to copy/paste the character, or use a dedicated method or tool (e.g. Alt code, emoji picker, character map) to insert the character. If a PDML implementation supports Unicode escape sequences, you can simply type \u{1F600}.

• Some characters might be invisible or not displayed correctly on the user's output device (e.g. monitor or printer).

  Unicode escape sequences allow you to represent these characters explicitly using only ASCII characters.

  For example, you can insert a Zero Width Space (U+200B) by writing \u{200B}.

• The PDML specification requires documents to be encoded in UTF-8. However, it is sometimes necessary to use other text encodings for storing whole PDML documents or just parts of it.

  Unicode escape sequences ensure that characters are represented consistently, regardless of encoding settings (even if the encoding supports only ASCII characters).

  Example: If text is encoded in UTF-16 then code points beyond U+FFFF must be encoded using UTF-16 surrogate pairs. For instance, U+1F600 must be encoded as U+D83D U+DE00 (two 16-bit code points). To avoid having to deal with surrogate pairs you can simply write \u{1F600}.

• As stated in the Core PDML specification, some control characters cannot by typed directly into a PDML document, for reasons explained in Invalid Characters.

  Unicode escape sequences allow you to insert these control characters without causing readability, interpretation, and security issues. For example, you can insert a backspace (U+0008) by typing the Unicode escape sequence \u{8}.

• Unicode escape sequences increase clarity and avoid misinterpretations when dealing with invisible, similar, or special characters.

  For example, Unicode defines multiple code points representing Regular and Unusual Space Characters. Imagine the confusion that could arise if these characters were mixed in the same document. In such cases, Unicode escape sequences help to clarify which specific variation is used at each location in the document.

In a nutshell, Unicode escape sequences provide a reliable, portable, and clear way to represent characters that might be difficult or error-prone to insert directly in PDML documents.

Examples

The hexadecimal value for the Unicode code point ∞ (infinity) is 221E (as can be seen here). Thus, you can insert ∞ by typing the Unicode escape sequence \u{221E}:

\u{221E} → ∞

You can insert Unicode code points beyond FFFF using the same syntax:

\u{1F600} → 😀

Leading zeros are optional:

\u{41}, \u{0041}, \u{000041} → A, A, A

You can write the hex digits A to F in uppercase or lowercase:

\u{1F4AA}, \u{1f4aa} → 💪, 💪

Instead of specifying just one character between the curly braces, you can specify a sequence of several characters separated by whitespace (spaces, tabs, and/or line breaks):

\u{41 42 43}        → ABC
\u{2669 2C 20 266A} → ♩, ♪

The following escape sequence:

\u{2764 2764 A 2764 2764}

... would be rendered like this:

❤️❤️
❤️❤️

The line break in the rendered text is caused by code point A in the escape sequence (U+000A, End of Line).

Instead of using single spaces to separate the hex values, you can use several whitespace characters, including line breaks. Thus, you can also write the above escape sequence in a more readable way, without affecting the result:

\u{2764 2764 A
   2764 2764}

You can use Unicode escape sequences in tags and in text leaves:

  [\u{1F4AC} Hi]
→ [💬 Hi]

  [b Some math symbols: \u{221A} \u{221E} \u{222B}]
→ [b Some math symbols: √ ∞ ∫]

You can also use them in attribute names and values:

Attribute name:
  [food ^(\u{1F44C}=yes) ...]
→ [food ^(👌=yes) ...]

Attribute name and value:
  [product ^("\u{1F44D} or \u{1F44E}" = \u{1F44D}) ...]
→ [product ^("👍 or 👎" = 👍) ...]

Contrived:
  [\u{1F34E} ^(\u{1F44C}=\u{1F44D}) \u{1F4AA 1F4AA 1F4AA}]
→ [🍎 ^(👌=👍) 💪💪💪]