diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2d07eba..6137f66 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,31 +45,49 @@ To be accepted, your submission _must_ meet the following **requirement**s and _ **Do _not_ edit [udl-list.md](https://github.com/notepad-plus-plus/userDefinedLanguages/blob/master/udl-list.md): that file is auto-generated from the JSON to save effort and maintain consistency.** When you make a submission, you should edit the [udl-list.json](https://github.com/notepad-plus-plus/userDefinedLanguages/blob/master/udl-list.json) file, following these definitions: -- The `id-name` attribute will match the name of the UDL file, without the `.xml`. -- The `display-name` attribute will match the `` from the submitted UDL file, if possible. - - Please note that autoCompletion file names must match this `name="..."` attribute from the UDL, so that attribute needs to be a valid filename. -- The `version` attribute can have a `v1.00`-style version or just a last-edited date like `2020-Jan-12`. -- The `repository` attribute will be left blank for UDL files uploaded to this repository; if the UDL resides in an external repository (or if you want to add a link to the original source file, but still keep a copy in this repository), use this attribute to hold the full URL of the external file -- The `description` attribute is an optional description of the UDL language (it could be the based on the `id-name` or `display-name`, but with spaces instead of underscores, hyphens, and/or periods). -- The `author` attribute should be your name or GitHub username or email address. -- The `homepage` attribute could be a link to your GitHub repository for the UDL language or your GitHub user page. -- The `autoCompletion` attribute should be included if you are supplying an autoCompletion file. It can either be a Boolean (`true` or `false`), or it can be a string. - - If it's `true`, then it will use the same file name as the UDL's .xml, but in the `autoCompletion\` directory instead of the `UDLs\` directory. - - If it's a string, it can either be the name of the autoCompletion file (without the `.xml`, similar to the `id-name` entry), or the URL to the external file (similar to the `repository` attribute). - - If it is `false` or not supplied, then it indicates there is no autoCompletion file in the submission. - - **Requirement**: The filename for the autoCompletion must match the the `` from the submitted UDL (and thus _should_ match the `display-name` in the JSON) - - If the JSON's `autoCompletion` value is `true`, then the `id-name` **must** match the `` as well. - - If the JSON's `autoCompletion` value is a string, that string **must** match the ``. -- The `autoCompletionAuthor` attribute should be set to the name of the author of the autoCompletion definition, if it's a different author than the UDL. - - For example, the [RenderMan UDL](./UDLs/RenderMan-RSL_byStefanGustavson.xml) was written by Stefan Gustavson, but the [RenderMan autoCompletion](./autoCompletion/RenderMan-RSL_by-focus_gfx.xml) was supplied by focus_gfx, so `autoCompletionAuthor` is set in order to give proper credit to both. -- The `functionList` attribute should be included if you are supplying a functionList definition file. It can either be a Boolean (`true` or `false`), or it can be a string. - - If it's `true`, then it will use the same file name as the UDL's .xml, but in the `functionList\` directory instead of the `UDLs` directory. - - If it's a string, it can either be the name of the functionList file (without the `.xml`, similar to the `id-name` entry), or the URL to the external file (similar to the `repository` attribute). - - If it is `false` or not supplied, then it indicates there is no functionList definition file in the submission. -- The `functionListAuthor` attribute should be set to the name of the author of the functionList definition, if it's a different author than the UDL. +- Required Attributes + - `id-name`: + - **requirement**: Attribute must match the name of the UDL file, without the `.xml`. + - `display-name`: + - **recommendation**: Attribute should match the `` from the submitted UDL file, if possible. + - **requirement**: Please note that autoCompletion file names **must** match this `name="..."` attribute from the UDL (with `.xml` appended), so this attribute **must** only include characters valid for a Windows filename. + - `version`: + - Attribute can have a `v1.00`-style version or just a last-edited date like `2020-Jan-12`. + - `repository`: + - **requirement**: Attribute must be left blank for UDL files uploaded to this repository (`"repository": ""`) + - If the UDL resides in an external repository (or if you want to add a link to the original source file, but still keep a copy in this repository), use this attribute to hold the full URL of the external file (`"repository": "https://url.example/blah"`) + - `description`: + - Attribute is a description of the UDL language (it could be the based on the `id-name` or `display-name`, but with spaces instead of underscores, hyphens, and/or periods). + - **requirement**: If there is no description, attribute must be left blank (`"description": ""`) rather than being omitted. + - `author`: + - Attribute should be your name or GitHub username or email address + - Can include both, using mailto syntax: `Name ` +- Optional Attributes + - `homepage`: + - Attribute could be a link to your GitHub repository for the UDL language or your GitHub user page. + - `autoCompletion`: + - Attribute should be included if you are supplying an autoCompletion file. + - It can either be a Boolean (`true` or `false`), or it can be a string. + - If it's `true`, then it will use the same file name as the UDL's .xml, but in the `autoCompletion\` directory instead of the `UDLs\` directory. + - If it's a string, it can either be the name of the autoCompletion file (without the `.xml`, similar to the `id-name` entry), or the URL to the external file (similar to the `repository` attribute). + - If it is `false` or not supplied, then it indicates there is no autoCompletion file in the submission. + - **Requirement**: The filename for the autoCompletion must match the the `` from the submitted UDL (and thus _should_ match the `display-name` in the JSON) + - If the JSON's `autoCompletion` value is `true`, then the `id-name` **must** match the `` as well. + - If the JSON's `autoCompletion` value is a string, that string **must** match the ``. + - `autoCompletionAuthor`: + - Attribute should be set to the name of the author of the autoCompletion definition, if it's a different author than the UDL. + - For example, the [RenderMan UDL](./UDLs/RenderMan-RSL_byStefanGustavson.xml) was written by Stefan Gustavson, but the [RenderMan autoCompletion](./autoCompletion/RenderMan-RSL_by-focus_gfx.xml) was supplied by focus_gfx, so `autoCompletionAuthor` is set in order to give proper credit to both. + - `functionList` + - Attribute should be included if you are supplying a functionList definition file. It can either be a Boolean (`true` or `false`), or it can be a string. + - If it's `true`, then it will use the same file name as the UDL's .xml, but in the `functionList\` directory instead of the `UDLs` directory. + - If it's a string, it can either be the name of the functionList file (without the `.xml`, similar to the `id-name` entry), or the URL to the external file (similar to the `repository` attribute). + - If it is `false` or not supplied, then it indicates there is no functionList definition file in the submission. + - `functionListAuthor`: + - Attribute should be set to the name of the author of the functionList definition, if it's a different author than the UDL. - The `functionListAuthor` is set in order to give proper credit to both, even if they are made to work together. -- The `sample` attribute maybe be included if you have submitted a file in the `UDL-samples\` directory. - - **Requirement**: if you have submitted a `functionList`, you _MUST_ also submit a `sample` file. + - `sample`: + - **Requirement**: Attribute must be included if you have submitted a file in the `UDL-samples\` directory. + - **Requirement**: If you have submitted a `functionList`, you _MUST_ also submit a `sample` file. - If the attribute value is `true`, then the filename in `UDL-samples\` directory must exactly match the `id-name` (so the file will have no extension). - If the attribute is a string, then the filename in `UDL-samples\` directory must exactly match that string. - If the attribute value is `false` or the attribute is not supplied, then you are not mapping this UDL to a sample file. This will flag as an error if a `functionList` is defined for this UDL.