Standalone documentation for addon-info.json format

[dbarnett]

Projects like maktaba and vimdoc have adopted the addon-info.json format as the canonical place to declare name, version, and other metadata. When mentioning the addon-info.json format in documentation and discussions, I've been linking to https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-additional-documentation.txt so people can search on that page for addon-info.json, but that's a little awkward.

I believe that the addon-info.json format isn't necessarily VAM-specific (as with vim-pi) and that you folks would be glad to see it adopted in every plugin manager and other relevant vim technologies. Would it make sense to create a standalone page somewhere to document the format and the meanings of different fields?

[MarcWeber]

Hi dbarnet, vim-pi means to "serve" everyone and tries to allow discussions. Anyway, you're right. I've tried to put up a summary here: http://vim-wiki.mawercer.de/wiki/topic/addon-info.json.html

[dbarnett]

Thanks, Marc!

One thing: I was hoping for a reference listing the different fields and their usage, so I could say "Add an addon-info.json file with 'name', 'description', 'version', and any other relevant fields, see THIS PAGE for details" and it would be pretty self-explanatory from there. Maybe as a stopgap it could just link to the VAM help file for details for now.

[Shougo]

I think this documentation should be distributed in vim-pi repository. The full documentation is in VAM repository. But it is not VAM specific.

[MarcWeber]

@dbarnett It could make sense if you talked about your use case. I intentionally only added the important fields to the wiki indicating operational value. Having too much to read is a problem, too.

I think its the wrong time to work on any standard unless we know about how neovim evolves.

If you feel differenly: The wiki is open, you can just add your notes.

[dbarnett]

For my needs, it would be perfect just having the whole |VAM-addon-info| section moved/copied into the wiki page. It would also be fine having that page be a short landing page as long as it links to a full spec.

I have a few specific use cases in mind. For vimdoc, we want to pick up any relevant info from addon-info.json and include it where appropriate in the generated help docs. For instance, in https://github.com/google/maktaba/blob/master/doc/maktaba.txt (which was generated by vimdoc) the addon "name", "description", and "author" on the two header lines came directly from those fields in the addon-info.json file. So for the vimdoc manual, amidst all the directives for controlling vimdoc's output, I'd like to mention the relevant addon-info.json fields and link to more info.

For maktaba, it's mostly the "name" and (indirectly) "dependencies" that matter so far: maktaba assumes dependencies are handled by the plugin manager (or the user, manually), and we just want to recommend in some documentation that you list dependencies in this format.

[MarcWeber]

Plaese think about the "whole thing". a) Its documented @ VAM and it can be found easily. Devs are smart enough to open two text files and use a browser search. b) why not start documenting vimdoc? c) Ask Bram about why we cannot switch hosting, sf sucks (eg because we cannot extend the plugin section so that it gets script info from github repositories, because PHP cannot connect to github (for security reasons).

We don't need yet another hack. We need a new page which is patchable by everyone, which understands all the README flavours (for github) etc.

And here Bram should speak up and tell about which features to preserve. And we should wait for NeoVim. At least I'm not going to spend any more time right now. It just doesn't make sense.

If I google "vimdoc" I find http://vimdoc.sourceforge.net/, if I click on an arbitrary link like "Vim Help format" its dead. So start with b) Eg just put your draft here http://vim-wiki.mawercer.de/wiki/topic/vim-doc (I'll reference it in the dev section then)

[dbarnett]

Devs are smart enough to open two text files and use a browser search.

Okay, I'll just keep linking to the VAM help, then. It's not ideal, but as I said all the details are somewhere in there.

The vimdoc I'm referring to is the 3rd or 4th Google result for me (also linked in the original message above). It's unfortunately not a very unique name, but as it's analogous to javadoc/jsdoc/pydoc/etc., "vimdoc" is the only name that really made sense.

I don't understand what you mean about "yet another hack" and sourceforge. Maybe that's in reference to the other "vimdoc".

[MarcWeber]

I don't understand what you mean about "yet another hack" and sourceforge. Maybe that's in reference to the other "vimdoc". I thought you were about creating a web page listing "documentation of plugins" online. The next generation plugin page should be able to run vimdoc like tools on its own - however in order to do so it should be able to access the plugin source - which cannot be done by sourceforge right now (one could implement HTTP and or SSH bridges delaying work). That's what I'd call a "hack".

I've referenced vimdoc @ vim-wiki (developing a plugin) page.