The 1st draft

[donho]

The goal of this repository is to provide a UDL center for users who need the programming languages which are not supported directly by Notepad++. Any UDL author can submit their UDL (with an explicit name - "id-name") in UDLs directory so users can find what they want from UDLs directory very easily. However, it's possible that some UDL authors prefer to keep files in their repository rather than submitting files into official User Defined Languages repository (https://github.com/notepad-plus-plus/userDefinedLanguages/UDLs/). They can still submit the URL of their UDL in question.

This repository could be the reference of UDL Admin (todo) in Notepad++ (in the 2nd step). udl-list.json is for such purpos. In the JSON file, "id-name" is the descriptive & uniq ID which should be controlled by the team. The value of "id-name" should be the same of file name without file extension. "repository" is the URL of UDL that Notepad++ (or user) can download. If the UDL is hosted in this repository, "repository" should be an empty string, then Notepad++ (or user) will find file with its id-name + .xml in https://github.com/notepad-plus-plus/userDefinedLanguages/UDLs/ directory.

So the first thing we should define IMO is the rule of "id-name": it should be descriptive and uniq but not contain only the language name like autocad or markdown (there could be several UDLs for the same programming language).

Feel free to discuss about not only the rule of "id-name", but also the structure of the repo, the structure/content of udl-list.json or anything else regarding UDL repository. It's just a draft and everything can be in the other way - with the concensus of members in the team.

[pryrt]

Mostly, I'm glad that the repo exists, and cannot wait to start directing people here

Sorry that I hadn't responded yet to the #1 discussion; I had been thinking about it over the weekend.

id-name / filename rules

• I agree that we need a unique identifier ("id-name"), and that filenames in this repository must obviously be unique. There is some argument (I deleted my original ramble to that effect before posting) that a separate repo should be able to keep a name, even if it conflicts with a name in this repo, since we could still assign a unique "id-name"; but since name collision causes confusion (and makes it more complicated to implement, I'll agree that requiring unique "id-name" = filename-base seems reasonable.
• in the old days, when UDL xml files were just exported/imported, it made sense for them to have udl in the filename; now that they're primarily going in the subdirectory, I don't think we need that as a requirement. However, if someone wants to keep UDL in the filename
• I don't think we should be too strict about what's required -- whether it goes "language" then "dod UDL" then "dot xml", or whether someone prefers "udl underscore language name" shouldn't really matter, as long as it's unique.
• I understand the reasoning behind saying "but not contain only the language name", because we need to be able to distinguish variants. But sometimes it's hard to come up with a second term to include (other than the submitter's username). Maybe the rule should be

  Try to give your UDL filename something more than just the language name, because yours might not be the only UDL for that language; possibilities include what theme the color scheme was chosen to be compatible with, or some variant of the language (like DaringFireball vs CommonMark vs GithubFlavored), or your username if nothing else. As examples:

  • Markdown_DaringFireball_ThemeChoco.udl.xml
  • Markdown_CommonMark_ThemeVimDarkBlue.udl.xml
  • Markdown.STL.UDL.byPryrt.xml

other "rules" discussion / questions

• should we recommend (or require) that each submitted UDL file only contain one language? I know that the files in the sub-directory can still technically contain more than one language (and I even make use of that for some of my proprietary languages that are closely associated, but not the same syntax), but for publicly accessible, is it usually (or always?) better to keep languages in separate files, even if closely related?
  • one possible reason would be if someone wanted to do a bundle for related languages, all made to fit the color of one StyleConfigurator theme; for example, maybe 3dModeling_bundle_forChocoTheme_includes_STL_OBJ_3DS.udl.xml: there are three filetypes, but they are all closely related (3d modeling filetypes), and all for the same theme.
• is the json "display-name" attribute just meant to match what's going to be displayed in whatever download tool is eventually used? Or should we recommend (or require) that it also match the <UserLang name="..."> name attribute in the UDL definition, so that the download tool and the eventual Languages menu entry will match? (if required, that means that each UDL file must also only contain one language)

I'm not a fan of too many requirements -- I like giving users options/flexibility -- so I'd vote for making both of those "recommend" rather than "require".

repo structure

I think that having the README and json in the top level, and just one UDLs subfolder for containing all the xml files makes sense. If it has too much higherarchy, then people will get lost in the depth. We want this to be simple for people to submit pull requests to add files.

[chcg]

I think we could take over the json checking from https://github.com/notepad-plus-plus/nppPluginList. What are the requirements for the UDL files regarding file format? UTF-8 with or without BOM? Probably that one could be also checked against some xml schema file.

[rddim]

1st – Thank you @donho that you initialize this repo with my UDLs 2nd – What about the autoCompletion files and the folder structure when they are available for the UDL? Will it be acceptable something like:

\userDefinedLanguages\AutoCAD\autoCompletion\AutoCAD.xml \userDefinedLanguages\AutoCAD\AutoCAD.npp.udl.xml \userDefinedLanguages\Markdown_DaringFireball_ThemeChoco.udl.xml \userDefinedLanguages\Markdown_CommonMark_ThemeVimDarkBlue.udl.xml \userDefinedLanguages\Markdown.STL.UDL.byPryrt.xml

[FlatAssembler]

What are your criteria for which language to add? I've made a UDL for a simple (and mostly useless) programming language I've made: https://github.com/FlatAssembler/ArithmeticExpressionCompiler/blob/master/NppSyntaxHighlightingScript.xml

[donho]

@pryrt

Try to give your UDL filename something more than just the language name, because yours might not be the only UDL for that language; possibilities include what theme the color scheme was chosen to be compatible with, or some variant of the language

I would say it should be mandatory - to avoid people monopolize the language name as I said. OTOH, it should be unique - it's important if we decide to deploy with Notepad++.

I'm not a fan of too many requirements -- I like giving users options/flexibility -- so I'd vote for making both of those "recommend" rather than "require". repo structure

I agree - the idea is provide a collection to the users who needs any UDL, and make easier for the authors to encourage them upload their file.

I think that having the README and json in the top level, and just one UDLs subfolder for containing all the xml files makes sense. If it has too much higherarchy, then people will get lost in the depth. We want this to be simple for people to submit pull requests to add files.

So we are on the same page.

[donho]

@chcg

I think we could take over the json checking from https://github.com/notepad-plus-plus/nppPluginList. What are the requirements for the UDL files regarding file format? UTF-8 with or without BOM? Probably that one could be also checked against some xml schema file.

Good idea. I let you implement this feature.

[donho]

@rddim

What about the autoCompletion files and the folder structure when they are available for the UDL?

You're pointed out another issue - about auto-completion file. That needs a solution as well definitely. But let's keep focusing on UDL here - I don't think it's a good idea to mix with other types of file.

[donho]

@FlatAssembler

What are your criteria for which language to add?

You have pointed out a good question. I think it's rather for the languages used by a community. So author should provide a link of the language in question, and a sample of this language to prove his/her UDL is working in the PR. I would even say that we should add a UDL samples folder for such purpose. The files in this folder should have the id-name of UDL, plus its own extension.

[FlatAssembler]

@FlatAssembler

What are your criteria for which language to add?

You have pointed out a good question. I think it's rather for the languages used by a community. So author should provide a link of the language in question, and a sample of this language to prove his/her UDL is working in the PR. I would even say that we should add a UDL samples folder for such purpose. The files in this folder should have the id-name of UDL, plus its own extension.

Well, I think my UDL works well, here is a rather long piece on that language exported from Notepad++ into RTF: https://github.com/FlatAssembler/ArithmeticExpressionCompiler/blob/master/HybridSort/hsort.aec.rtf The line numbers were added in RichEd. Here is the original source code: https://github.com/FlatAssembler/ArithmeticExpressionCompiler/blob/master/HybridSort/hsort.aec And the code blocks generally work, except for the macros. But the macros don't really belong to that language, they are in inlined assembly.

[pryrt]

Since the conversation had died down, I made a PR for a second draft, with our Submission guidelines codified in the README.md. Feel free to continue discussing here, or in the PR.

[pryrt]

Speaking of more discussion here: one thing I found slightly unclear from the conversation: 1) were we expecting each author to update the json file themselves? or 2) would we always do that ourselves based on their PR (to prevent errors)? or 3) would we allow either, and just check any JSON edits they submitted before merging into the repo?

My vote would be 3.

[donho]

For me it's always from the author's PR then we should do minimum of control for checking the validity of UDL (also control the functionality by using the examples they provide, if it's possible). Don't forget control the entry they add in udl-list.json. So I vote for 3 as well.

[pryrt]

Okay, I've updated the wording to allow for #3.

Thanks for your feedback.

[pryrt]

Please see PR #6 and comment on practical issues regarding our naming rules and linking to UDL in external repos. Thanks