search

asciidoctor / asciidoctor-vscode

AsciiDoc support for Visual Studio Code using Asciidoctor
Other
328 stars 97 forks source link

Normalize setting names/keys #577

Closed ggrossetie closed 2 years ago

ggrossetie commented 2 years ago

Currently, setting keys are inconsistent. We are using both camelCase and _ as a separator. Given that the key is used to construct a title, I think we should use a strict convention.

Official documentation

The properties in your configuration will be a dictionary of configuration properties. In the settings UI, your configuration key will be used to namespace and construct a title. Though an extension can contain multiple categories of settings, each setting of the extension must still have its own unique key. Capital letters in your key are used to indicate word breaks. For example, if your key is gitMagic.blame.dateFormat, the generated title for the setting will look like this:

Blame: Date Format

Entries will be grouped according to the hierarchy established in your keys. So for example, these entries

gitMagic.blame.dateFormat
gitMagic.blame.format
gitMagic.blame.heatMap.enabled
gitMagic.blame.heatMap.location

will appear in a single group like this:

Blame: Date Format Blame: Format Blame › Heatmap: Enabled Blame › Heatmap: Location

https://code.visualstudio.com/api/references/contribution-points#contributes.configuration

Present state

Settings in VS code

Proposal

Removed
Renamed
ggrossetie commented 2 years ago

@danyill do you think we should do it as part of the next major version 3.0.0?

danyill commented 2 years ago

I like this proposal. I think the groupings are much clearer.

@danyill do you think we should do it as part of the next major version 3.0.0?

I guess a new major version is the right time to make a compatibility change.

ggrossetie commented 2 years ago

I'm working on asciidoc.pdf.wkhtmltopdfCommand but I can't find a simple way to implement it. I think it would be better to have two settings, one for the binary path and one for the command line arguments. Otherwise, it quickly gets complicated if the path contains spaces:

./dir\ with\ spaces/wkhtmltopdf --arg "foo bar"
"./dir with spaces/wkhtmltopdf" --arg "foo bar"

Arguably, we could rely on the PATH but I guess some users cannot modify the PATH on their corporate machine/laptop. I also think we should simplify the default value to be either wkhtmltopdf (Linux, macOS) or wkhtmltopdf.exe. And as mentioned in another thread, we should remove the download feature and instead ask users to download the latest version from https://wkhtmltopdf.org/downloads.html.

ggrossetie commented 2 years ago

So: