D 2018-07-04T14:02:48.205
L Plugin\sMeta\sData
N text/x-markdown
P f549cf9c87f5e92f78752f4acf27902c87d8c5e10a8fc30b8f5f19acf9560d94
U mario
W 3387
# Plugin meta data

Plugin meta data is a comment scheme for scripting languages. It's meant for
application-level feature and config management. And typically looks like this:

    # encoding: utf-8
    # api: appname
    # title: My Plugin
    # description: Lists all the things
    # type: feature
    # version: 1.0
    # state: stable
    # category: ui
    # license: MITL
    # config: { name: myconf, value: 1, type: boolean, description: enable foo }
    #
    # And here goes a longer doc/comment.

Most `key:` names are fairly standard. Some fields are classifiers or hooks
for the application API. Others are mostly descriptions for end users.  
<acronym title="Plugin Meta Data">PMD</acronym> is meant to be rather obvious,
easy to extract, and reusable across languages.


## Common fields

| key           | usage                                                     |
-----------------------------------------------------------------------------
| [api](wiki/api)           | Application identifier                        |
| [type](wiki/type)         | Primary plugin "hook" or general classifier   | 
| [title](wiki/title)       | Title                                         |
| [description](wiki/description) | Summary or description of plugin        |
| [category](wiki/category)         | UI classification / menu hook                 |
| [version](wiki/version)   | Script-specific version                       |
| [state](wiki/state)       | stable/beta/etc                               |
| [license](wiki/license)   | license identifier                            |
| [author](wiki/author)     | author or contributor list                    |
| [config](wiki/config)     | List of config options (JSOL struct)          |


Custom properties are encouraged for further project or tool requirements.


## Comment syntax

The preferred comment scheme is a cohesive `#` hash block - because that's supported
with most scripting languages (and aligns best with an optional shebang).

  *  Implementations might support `/* … */` or `//`-blocks or `<# … #>` and whatever
     alternative the language offers though.

  *  It's however important that this meta block is the topmost comment in a script.
     (See Rationale)

  *  All `# key: value` entries occupy consecutive comment lines with coherent formatting.

  *  Key names should be interpreted case-insensitively. Rfc/message-style,
     no spaces allowed.

  *  Typically they carry just plain strings, because that's easiest to process
     for trivial regex lexing.

  *  Longer field values might be multi-line by indenting wrapped text at least
     two spaces beyond other key: comment lines.

  *  The [config](wiki/config) field is one of the few structured entries, and often spans
     multiple lines.

  *  Whereas e.g. [author](wiki/author) or [depends](wiki/depends) are sometimes comma-separated lists.
     Though the plugin meta extraction might still just read them as strings;
     and leave list handling for later.

Overall it's a bit like YAML; just in a comment block.

Notably an empty line in the comment section separates plugin meta data from
a more detailed description section. Albeit this would often pertain application
end users, more than code implementation details or technical minutae.


Z 6e20d89a4f4fc7575f63d5e4338bd60b