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: |
Package Features
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.
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 |
|
Convert in source folder |
HTML conversion in same folder as PML source |
|
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 |
Anywhere in PML file, except raw nodes or options. |
Alt+I |
Make selection italic |
Anywhere in PML file, except raw nodes or options. |
Ctrl+Shift+Enter |
Inserts new line node |
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 |
|---|---|---|
|
Footnotes Placeholder |
|
|
Footnote Reference |
|
|
Footnote Text Reference |
|
|
Non-Breaking Space |
|
|
New Line |
|
|
Get parameter |
|
|
Set parameter |
|
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 |
|---|---|---|
|
|
Chapter Identifier |
|
|
Quotation Identifier |
4.3. Options
The following completions are available within the special [options node block:
| tag | trigger | description |
|---|---|---|
|
|
Syntax Highlighter |
|
|
Syntax Highlighter: highlight.js |
|
|
Syntax Highlighter: prism |
|
|
TOC Position |
|
|
TOC Title |
5. Snippets
The package provides the following snippets:
| trigger | description |
|---|---|
|
Block Code template, with |
|
Block HTML template, with ID. Wraps selection in fenced delimiters. |
|
Block Input template, with ID. Wraps selection in fenced delimiters. |
|
Block Output template, with ID. Wraps selection in fenced delimiters. |
|
Footnote Definition, with ID. Wraps selection. |
|
Inline Footnote. Wraps selection. |
|
New Chapter template, with ID and title placeholders. Wraps selection. |
|
New PML Document boilerplate, with title placeholder. Wraps selection. |
|
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.