sublime pml banner

About

Welcome to the user guide of Sublime PML, a package for Sublime Text 4 that adds support for PML (Practical Markup Language).

Sublime PML was created by Tristano Ajmone in 2021, published under the MIT License.

PML was designed by Christian Neumanns around 2019, and since February 2021 the full source code of the PML conversion tool is available on GitHub under GPLv2 license.

Don’t forget to frequently check the package CHANGELOG in order to keep up with the latest package features!

To view the Changelog, use the dedicated Sublime Text menu:

  • Tools  PML  Sublime PML Changelog

Package Features

Here’s a list of the feature currently available in the Sublime PML package.

1. Colour Schemes

The package ships with a default PML Dark colour scheme intended to provide an improved editing experience for PML documents. The scheme is associated to .pml source files via the native package settings.

Default scheme settings in PML.sublime-settings
{
  "color_scheme": "Packages/PML/schemes/PML Dark.sublime-color-scheme",
  "dark_color_scheme": "Packages/PML/schemes/PML Dark.sublime-color-scheme",
}

You can always override it and use a scheme of your choice by editing your syntax-specific User settings for the PML syntax.

The colour scheme is still WIP, incomplete and subject to frequent changes.

2. Build Systems

The package provides some built-in basic build systems:

build name description pmlc command

default

HTML conversion (to output/)

pmlc p2h <file.pml>

Convert in source folder

HTML conversion in same folder as PML source

pmlc p2h <file.pml> -o <path/file.html>

3. Keyboard Shortcuts

Some of the keystrokes combinations indicated below rely on Sublime Text’s default settings, and might vary depending on your custom settings, whereas others are explicitly defined by this package.

key strokes result context

Alt+B

Make selection bold [b…]

Anywhere in PML file, except raw nodes or options.

Alt+I

Make selection italic [i…]

Anywhere in PML file, except raw nodes or options.

Ctrl+Shift+Enter

Inserts new line node [nl]

Anywhere in PML file, except raw nodes or options.

3.1. Comments

The two comment shortcuts Ctrl+/ and Ctrl+Shift+/ share some common behavior:

  • Selected text is commented out: [- <selection> -]

Their behaviour differs when nothing is selected:

key strokes effect without selection

Ctrl+/

Comments out the whole line

Ctrl+Shift+/

Inserts comments delimiters under cursor only

4. Auto-Completions

Sublime PML offers smart auto-completion suggestions, based on the scope context under the cursor, thus avoiding completions pollution (i.e. cluttering the suggestions with unrelated elements).

4.1. Nodes

For commonly used nodes, context-specific suggestions are available.

trigger description output

fnpholder

Footnotes Placeholder

[fnotes]\n

fnref

Footnote Reference

[fnote_ref did=${1:fn_}]

fntref

Footnote Text Reference

[fnote_ref did=${1:fn_} text=\"${2:some text}\"]

nbsp

Non-Breaking Space

[sp]

nl

New Line

[nl]

pget

Get parameter

[u:get pname]

pset

Set parameter

[u:set pname = pvalue]\n

4.2. Tag Attributes

For nodes that support attributes, context-specific suggestions are available within the editing space where tag attributes are allowed.

tag trigger description

[ch

id

Chapter Identifier

[quote

id

Quotation Identifier

4.3. Options

The following completions are available within the special [options node block:

tag trigger description

[options

highlighter

Syntax Highlighter

[options

hljs

Syntax Highlighter: highlight.js

[options

prism

Syntax Highlighter: prism

[options

tocposition

TOC Position

[options

toctitle

TOC Title

5. Snippets

The package provides the following snippets:

trigger description

bkcode

Block Code template, with lang attribute. Wraps selection in fenced delimiters.

bkhtml

Block HTML template, with ID. Wraps selection in fenced delimiters.

bkinput

Block Input template, with ID. Wraps selection in fenced delimiters.

bkoutput

Block Output template, with ID. Wraps selection in fenced delimiters.

fndef

Footnote Definition, with ID. Wraps selection.

fnote

Inline Footnote. Wraps selection.

newch

New Chapter template, with ID and title placeholders. Wraps selection.

newdoc

New PML Document boilerplate, with title placeholder. Wraps selection.

opts

Options Block template.

6. Symbols Indexing

The following syntax elements are being indexed (local symbols list). Some cosmetic transformations are applied to the symbols, either to improve their visual representation or to simplify lookup by adding prefixes that allow filtering down the symbols list by category.

  • Parameters definitions and their inline occurrences are indexed after cosmetic transformations:

    • Parameters definitions are prefixed with [u:set .

    • Parameters occurrences are prefixed with [u:get .

  • Chapter Titles are prefixed with = , after stripping away redundant spaces and font-formatting tag delimiters.

  • Identifier attributes (id) are indexed with a leading #, resembling HTML anchors.

Goto Definition functionality (F12) is also supported, allowing to quickly jump to the definition of any inline parameter.

Appendix A: License

Sublime PML was created by Tristano Ajmone in 2021, released under the MIT License.

MIT License

Copyright (c) 2021-2023 Tristano Ajmone

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.