Add short descriptions to options.lua #6288
Conversation
|
Nice.
|
scripts/genoptions.lua
Outdated
| if name == "scope" then | ||
| -- print("SCOPE") | ||
| append = toCSV(opt[name]) | ||
| else |
There was a problem hiding this comment.
2-space indent. In general, these scripts should follow the typical guidelines.
|
Maybe it is time to add some templating engine as a dependency? Various generators could be far more readable with good engine. I do not think that avoiding templates is a good idea: when I was checking whether it would be easy to add varargs I wished to rewrite gendispatch.lua with something: proper template engine allows to
Also it would not require making generated dispatch file be |
|
In this case at least (and I suspect many future ones seeking to use template rather than "obvious"), template makes things worse. Now we have a missing |
runtime/doc/quickref_00.tpl
Outdated
| @@ -0,0 +1,598 @@ | |||
| *quickref.txt* For neovim version 0.2. Last change: 2017 Mar 13 | |||
There was a problem hiding this comment.
The docs always mention "Nvim" or "nvim" only. Should stay consistent.
|
Just because |
Right now it's offline, plugin need to embed their own listing of descriptions. I chose csv but it could be anything. I wish users could query nvim for setting descriptions but I couldn't find how to justify nvim advertising option descriptions except for my use case so I left that out. I am open to suggestions if you think advertising (via msgpack) the short descriptions is ok. I agree with @ZyX-I for templating. I am not happy with my solution but I see other parts of the doc that could be generated and I see value in using some templating (with rules that make it understandable). |
|
It's similar use-case as #6123, right? The data generated from This will be a messagepack blob, any plugin can load it and inspect it via To generate the messagepack data, |
|
Yes, this is some of the exact type of things I was looking to do. Once we have the descriptions for some of the mappings, we could use the same process to generate mpack items for that. I definitely think JSON is a much stronger candidate than CSV. Also, it makes sense to use JSON as justinmk says so that we could dump it into mspack. Once you have these options available, people will find ways to use them introspectively. |
|
I've added dkjson as a dependancy (it exists on luarocks) to export the lua table to json. Then I generate an options.mpack but do you want one per language ? translations are available in the mo files already so that may be redundant but on the other hand, one mpack per lang is more straightforward (I have no opinion there). Also in the first case plugins would need to know the gettext path, aka |
|
Jinja requires python. Adding python as a build dependency for non-CI tasks is too much. We already have too many dependencies. |
|
Why genoptions.lua should emit json and feed it somewhere? We already have msgpack generator dependency. About jinja: this adds Python as a required build time dependency and requires to rewrite some scripts in Python. Better find something based on lua, though I did not find a generic (non-HTML) templating engine which is not stagnating. And note that templates should be used not only for documentation: there are files like I would actually be happier if help files alongside with docstring comments were replaced with sphinx documentation (it is even possible to create a sphinx target which will generate Vim help files out of rst files): unlike doxygen html documentation from sphinx does not look like crap and is more configurable and sphinx itself is easier to extend: up to writing the functions which will generate documentation like we want now with templates or creating vimhelp target. But that would be too much work and not too much benefit. Linux kernel started moving towards documenting everything with sphinx though. |
|
Python is already there on most *nix systems. It would be OK if we did not already have everything in lua. BTW, if we were using sphinx I could suggest to keep options.lua, etc in the documentation itself. But vim help files do not allow even comments, not to mention custom markup constructs. |
|
Forget about the template engine, I will generate the help "by hand" or leave it as is (does it matter that much anyway ?!).
What do you mean ? we pull a lua-msgpack already (could not find 'lua-MessagePack' ) ? or use the nvim binary to generate the mpack ? Btw what about the question of generating one mpack per language vs just generate the US mpack and let plugins deal with gettext ? |
|
@teto We pull in |
|
About mpack per language/US mpack: on first iteration I would suggest to just use US mpack. If somebody needs localized descriptions he may ask us for it. Maybe by the time there will be access to gettext through VimL: currently you could not easily use gettext to localize your plugins. |
|
To sum up the changes:
When trying to update pos |
|
It would be neat if a US native & longstanding vimmer could check & update the short_desc in options.lua. |
6078ad4 to
882451d
Compare
|
Just as a precision, I reverted it from RDY to WIP because even though the .mpack is generated, it can be impractical to work with as for example the scope is typically dumped as strings ("buffer", "window" ). For instance in https://github.com/teto/nvim-palette, I do some preprocessing on it (and as I don't saved the cached product, the plugin ends up being slow). Might be best postponed to 0.2.2 |
|
I am ready to resume work on this and the associated plugin. With the recent lua advances (type validation etc), I thought we could envision something more comprehensive aka having plugins describe their own settings in an optional spec and vim capable of exporting this. Example of a spec (json or csv may be simpler or we could just) |
|
@tjdevries @sunjon (the telescope team) that's what I used for my palette if you wanna play with it :p |
ah great, I'd not thought exactly how I was going to scrape this info. This is very helpful. |
|
@sunjon made me realize I did not share my source of truth, which is https://github.com/neovim/neovim/blob/master/runtime/optwin.vim . |
|
would you be ok with just merging the descriptions without the rest ? |
|
As a consequence of merging this can we officially untruth https://github.com/neovim/neovim/blob/master/runtime/optwin.vim ? because no one who does options in neovim has the time (nor should need the time) to care about that file. |
add one-liner option descriptions in src/nvim/options.lua They are taken from optwin.vim and should be easier to use in a programmatic manner, for instance in a "palette", like in telescope `:Telescope vim_options`.
add one-liner option descriptions in src/nvim/options.lua They are taken from optwin.vim and should be easier to use in a programmatic manner, for instance in a "palette", like in telescope `:Telescope vim_options`.
add one-liner option descriptions in src/nvim/options.lua They are taken from optwin.vim and should be easier to use in a programmatic manner, for instance in a "palette", like in telescope `:Telescope vim_options`.
In order to generate a "palette" (https://github.com/teto/nvim-palette ; related issue #6240), I moved the one-liner option descriptions from quickref.txt to options.lua so that it can be reused more easily.
In order not to have duplicated strings across the source, I generate the incriminated quickref help from options.lua.
As a summary of changes:
short_desc=member.cat quickref_*.tpl > quickref.txt. That was the only thing I could think with my skillset (apart from using jinja templates). This leaves the tpl files in the runtime folder but I wanted to know if you had another idea in mind before cleaning that up. There could be value in generating other parts of the doc so if we could standardize the process that might be nice.