Skip to content

For udl-list.json attribute description, make required/optional more clear #375

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pryrt merged 1 commit into from
Feb 17, 2026
Merged

For udl-list.json attribute description, make required/optional more clear #375

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 42 additions & 24 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<UserLang name="...">` 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 `<UserLang name="...">` 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 `<UserLang name="...">` as well.
- If the JSON's `autoCompletion` value is a string, that string **must** match the `<UserLang name="...">`.
- 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 `<UserLang name="...">` 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 <mailto:email@url.example>`
- 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 `<UserLang name="...">` 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 `<UserLang name="...">` as well.
- If the JSON's `autoCompletion` value is a string, that string **must** match the `<UserLang name="...">`.
- `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.
Expand Down