Update and fix options in data/micro.json and runtime/help/options.md

[omarelladen]

No description provided.

[JoeKar]

Looks good so far.

Unfortunately this will happen over and over again, since we maintain the options and their order at 4 different places:

• https://github.com/micro-editor/micro/blob/master/internal/config/settings.go
• https://github.com/micro-editor/micro/blob/master/data/micro.json
• https://github.com/micro-editor/micro/blob/master/runtime/help/options.md
• https://github.com/micro-editor/micro/blob/master/runtime/help/options.md#settingsjson-file

Somehow a self made problem, but a unnecessary one.
We should reduce the places or think about generating the stuff from one single point of truth.

[JoeKar]

Unfortunately we have now merge conflicts.

[JoeKar]

@omarelladen:
Will you be so kind and solve the merge conflicts?

[usfbih8u]

We should reduce the places or think about generating the stuff from one single point of truth.

@JoeKar, I’m making a go:generate program to create data/micro.json and runtime/help/options.md from the code in internal/config/settings.go.

But I have a couple of questions before I do anything more.

• Do you want this solution?

• What is the use of micro.json? How sensible is the formatting for change tracking (diff-wise), should I care?

• Questions about the most exotic options:

"autosave": {
"description": "A delay between automatic saves\nhttps://github.com/zyedidia/micro/blob/master/runtime/help/options.md#options",
"type": "integer",
"minimum": 0, // 👀"default": 0
},
// ..."clipboard": {
"description": "A way to access the system clipboard\nhttps://github.com/zyedidia/micro/blob/master/runtime/help/options.md#options",
"type": "string",
"enum": [ // 👀"external",
"terminal",
"internal"
],
"default": "external"
},
// ..."indentchar": {
"description": "An indentation character\nhttps://github.com/zyedidia/micro/blob/master/runtime/help/options.md#options",
"type": "string",
"maxLength": 1, // 👀"default": ""
},
// ..."pluginrepos": {
"description": "Plugin repositories\nhttps://github.com/zyedidia/micro/blob/master/runtime/help/options.md#options",
"type": "array",
"uniqueItems": true, // 👀"items": { // 👀"description": "A pluging repository\nhttps://github.com/zyedidia/micro/blob/master/runtime/help/options.md#options",
"type": "string"
},
"default": []
},
// ..."sucmd": {
"description": "A super user command\nhttps://github.com/zyedidia/micro/blob/master/runtime/help/options.md#options",
"type": "string",
"default": "sudo",
"examples": [ // 👀"sudo",
"doas"
]
},
// ...

• minimum and maxLength are related to validators? minimum seems like a validator (non-negative), right?

• sucmd uses examples, and clipboard uses enum. I see that sucmd does not enforce those values and only suggests them (you can use "whatever" you choose). Maybe examples should not be there and instead be part of the description?

• Should the enum be called choices?

• Should I add a new key scope to indicate that some options are only global or only local based on settings.go::DefaultGlobalOnlySettings and settings.go::LocalSettings, respectively?

• Mismatches between defaults in the source code and the JSON schema (could be more, I didn’t check exhaustively):

  • float64 in code vs integer in the JSON schema: colorcolumn, tabsize, scrollmargin, scrollspeed.
  • Missing in the JSON schema: detectlimit, pageoverlap, reload.

• The description in the markdown file and the description in the JSON file do not match. Should I use the same one (the markdown version) for both? (I can append the URL in the JSON if necessary.) I can also have both in the comment on top of the option in the source code, tagged like @brief and @description (or something like that), but I think having only the long one is easier for me and for new additions.

[Andriamanitra]

What is the use of micro.json? How sensible is the formatting for change tracking (diff-wise), should I care?

• Based on Add config JSON schema #2697 it seems to be intended as a machine-readable schema that 3rd party tools can use to help with editing micro's settings file (eg. Intellisense, MCP). I doubt anyone is actually relying on (our version of) it because @EmilyGraceSeville7cf's stated goal of referring to our micro.json file from SchemaStore never happened, they still have their own copy of micro.json (that is even less up-to-date than ours). (They also have one for micro's syntax files.)

minimum and maxLength are related to validators? minimum seems like a validator (non-negative), right?

• https://json-schema.org/understanding-json-schema/reference/numeric#range
• https://json-schema.org/understanding-json-schema/reference/string#length

Should the enum be called choices?

• No. https://json-schema.org/understanding-json-schema/reference/enum

Should I add a new key scope to indicate that some options are only global or only local based on settings.go::DefaultGlobalOnlySettings and settings.go::LocalSettings, respectively?

• No, you should stick to the fields defined in the specification. Tools that support json-schema would not know what to do with a key we invented.

SchemaStore has some guidelines on authoring schemas that may be relevant (especially the "Avoiding Overconstraint" part): https://github.com/SchemaStore/schemastore/blob/master/CONTRIBUTING.md#schema-authoring

[usfbih8u]

I had in mind extracting most of the info from the source code, but I saw that the scheme (yesterday tried to enter that website and I couldn't) is different from what I was expecting. It will need to spread the data all over the place, and the single source of truth will be multiple sources, but in the same file.

The easiest way I see is (mostly because of the scheme, markdown is more flexible) to embed and tag the data into the comments:

// a list of settings that can be globally and locally modified and their// default valuesvardefaultCommonSettings=map[string]any{
// @markdown// when creating a new line, use the same indentation as the// previous line.// @scheme// {// "description": "Whether to use the same indentation as a previous line\nhttps://github.com/micro-editor/micro/blob/master/runtime/help/options.md#options",// "type": "boolean",// "default": true// }"autoindent": true,
// ...varDefaultGlobalOnlySettings=map[string]any{
// @markdown// automatically save the buffer every n seconds, where n is the// value of the autosave option. Also, when quitting on a modified buffer,// micro will automatically save and quit. Be warned, this option saves the buffer// without prompting the user, so data may be overwritten. If this option is// set to `0`, no autosaving is performed.// @scheme// {// "description": "A delay between automatic saves\nhttps://github.com/micro-editor/micro/blob/master/runtime/help/options.md#options",// "type": "integer",// "minimum": 0,// "default": 0// },"autosave": float64(0),

I am not convinced, to be honest.

[JoeKar]

If you ask @dmaluka¹ and me, then we should drop this micro.json entirely.
Its already maintained out of tree² and therefore I see the burden to maintain the duplicate option description by the people that like to have them integrated in IntelliSense for whatever reason.
For us it makes no sense to keep it in sync with the documentation.

Footnotes

1. https://github.com/micro-editor/micro/pull/3882#discussion_r2575180265↩

2. https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/micro.json↩