The 1st draft about userdefinedlanguages HOT 14 CLOSED

@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.

from userdefinedlanguages.

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.

from userdefinedlanguages.

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.

from userdefinedlanguages.

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.

from userdefinedlanguages.

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

from userdefinedlanguages.

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

from userdefinedlanguages.

@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.

from userdefinedlanguages.

@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.

from userdefinedlanguages.

@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.

from userdefinedlanguages.

@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.

from userdefinedlanguages.

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.

from userdefinedlanguages.

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.

from userdefinedlanguages.

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

Thanks for your feedback.

from userdefinedlanguages.

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

from userdefinedlanguages.