Options Node: Questions and Thoughts

[tajmone]

@pml-lang, I've just implemented support for the [options node in Sublime PML — although mostly undocumented, it's already merged on main so you should see it in the package update next time you launch ST.

Because there are quite a lot of CLI options available, and since only some of them seem to make sense within a document, I've hand-picked a limited number of options so far:

• [highlighter
• [TOC_max_level
• [TOC_position
• [TOC_title

(for more details, see PACKAGE_STATUS.md)

The PML Nodes Ref Manual doesn't really provide much details on the [options node (and, BTW, all example options are misspelled, lacking underscores), I wanted to ask you to share some thoughts on which options the editor should support, and which should be left out.

By play-editing with [options you'll notice that some validation is also done in the background: those options that expect fixed values will scope as "invalid" any inconsistent values, but can handle letter casing insensitively where required, and correctly support parameters and comments (tested against real use cases).

I haven't yet got to add smart-completions because I still need to make up my mind on how to handle some details, but once they are in place I'll also update the documentation.

In the meantime, please tell me which CLI options don't apply (or make sense) within documents sources, or if any CLI opt is indeed valid, and do share some thoughts on how to make the most out of this node within the package.

[pml-lang]

you should see it in the package update next time you launch ST

Yes, I just checked it out.

The PML Nodes Ref Manual doesn't really provide much details on the [options node

All options (including CLI-specific parameters) are documented in chapter Convert PML to HTML of the PMLC Commands Reference Manual.

BTW, all example options are misspelled, lacking underscores

Now fixed in the develop branch. Thanks for pointing out.

please tell me which CLI options don't apply

I've added the following note in the documentation of the options node:
"The following parameters are only valid in the CLI, not in the options node: input, output, open_file_cmd, and verbosity."

some thoughts on which options the editor should support, and which should be left out.

To avoid frequent manual updates of your plugin, I would suggest to currently not do any validation within the options node, because (1) the set of options is likely to change in the future, and (2) the options are currently not documented in the JSON file created by the export_tags command. IMO options should only be checked in plugins if the plugin can be updated automatically by reading a PML meta file that provides all info in a reliable way. IMO the same applies to nodes and attributes (as discussed already in another discussion).

If you need the options meta data added to the existing JSON file, we can agree on the format first, and then implement it in a future version.

[tajmone]

To avoid frequent manual updates of your plugin, I would suggest to currently not do any validation within the options node,

The only validation I'm currently doing is checking for wrong letter-casing spelling of supported options — i.e. the correctly cased option is captured first (case sensitively) and immediately after the same option is captured case-insensitively as invalid, so that if the user accidentally types it with wrong letter casing there's immediate feedback — but unimplemented options are just captured as unknown options via a generic fallback scope, so if a new option node is added the syntax handles it somewhat gracefully.

IMO options should only be checked in plugins if the plugin can be updated automatically by reading a PML meta file that provides all info in a reliable way. IMO the same applies to nodes and attributes (as discussed already in another discussion).

I've tried that approach, but with ST is unlikely to work due to the complexity of its syntax files. Probably it would viable with other TextMate syntaxes in JSON format, or simpler syntax formats, e.g. using mustache templates. As for ST, partly due to YAML's format complexity, partly to the complexity of how the Sublime PML syntax has evolved in terms of handling edge cases on a per-node basis, it would probably require more work to maintain a mustache template approach then the actual time saved, and it would also become much harder to read.

But I still use the JSON tags file quite often when working on the syntax, via the intermediate mustache templates of the PML Playground, which provide me various reference documents to work with, which are autogenerated and always up to date.

If you need the options meta data added to the existing JSON file, we can agree on the format first, and then implement it in a future version.

That might be actually be useful. I'm not sure about the format or how to store them, since the options node is somewhat unique in its own way. Probably it would make sense to list the various option nodes and their possible values as sub-elements of the options node itself, like attributes are for other nodes. I think that mustache should be able to extract the option nodes and their values by filtering them out via the parent options node, but I need to check that.

Alternatively, they could be stored at the root level, but that would require a boolean key to distinguish between options and non-options nodes, which would result in them being scattered all over the file due to asciibetical sorting, rather then be kept together under the options node. And since they don't have attributes but possible values, they would differ from other nodes too, which might add structural complexity to the generated JSON file.

So, I'm not sure which would be the best solution, really.