Wiki Review Part 2

[maettu-this]

Hi Oleg,

Continuing from review started in #254, I have created branches/maettu_this_review_2 to be reviewed and merged. In general, the Wiki looks very good! I did find some places with room for improvement, and some minors/nice-to-haves which I nevertheless propose to fix. After all, many people likely read the Wiki.

• I have also changed Sum/Product to Add/Multiply (as methods should be named with verbs rather than nouns).
  Feel free to revert if you dislike the change.
  You could even further simplify to always use Add and the very same args.

In addition to the proposed changes in markdown, several things where you will have to decide upon best/right/wrong:

General

• Inconsistent on whether product names are italic or not, e.g. CS-Script vs. CS-Script.
• Inconsistent on whether using abbreviations or not, e.g. "Chocolatey" vs. "Choco".
• Inconsistent on how to quote, e.g. plain-vanilla vs. "plain vanilla" vs. 'plain vanilla' vs. "eval" vs. 'borrowed'.
• I struggle a bit with duplications among Home and Overview. Maybe either could be reduced, or they could be merged.
• Inconsistent on whether CLI or hosted comes first. CLI: Home, top of Overview,... Hosted: Sidebar, bottom of overview,... Proposing to always use CLI then hosted.
• Inconsistent commenting in examples, e.g. ; // IE ICalc implementation vs. ; //clear all ref assemblies, i.e. with/without space after // and lower/upper case.
• Inconsistent on referencing, e.g. "legacy Documentation online" (link @ "Documentation online") vs. "online documentation" (completely with link) vs. "online legacy documentation" (link @ "legacy documentation") as well as "the release page" (link @ "release page") vs. "Releases page" (link @ "Releases") vs. "Releases page" (link @ "Releases page") vs. "release page" (completely with link) vs. "releases page" (completely with link).

Home.md

• "It is also the place where you can ask the questions, make feature requests and report defects."
  Not exactly true, these topics are not in the Wiki, rather the project's Github page.
• The "How-to guide" no longer exists (dead link).
• What does "PM> " mean in "PM> Install-Package CS-Script"?

CS-Script-Overview.md

• "This top-level Wiki documentation"
  What do you mean by "top-level"?
• Should https://www.cs-script.net/ be called legacy documentation?
  Or even better, merge and eliminate? e.g. https://www.cs-script.net/integration is empty.
• "execution by the script engine executable and hosted script (file or in-memory text) execution by the script engine hosted by the user application"
  Something wrong here.
• "in the online legacy documentation" leads to the wrong location (partly dead link).
• "new instance of IEvaluator" doesn't work, an interface cannot be instantiated, only a class implementing that interface.
• Proposing changing order to 1. "strongly typed" 2. dynamic 3. duck-typing as the latter two share the very same code.

Hosted-Script-Execution.md

• "Though if strongly typed delegate is preferred then you can use LoadDelegate instead:"
  Statement seems related to the string[] topic but example is not, somehow confusing.
• Not understanding the <ul style=... inline html, proposing to use markdown instead.
• "Importing other scripts with //css_include" needs more in my opinion:
• Is css_include the preferred way to import other code now? When to better use css_import?
• What exactly are the possibilities and limitations for the available compilers in respect to css_...? I guess this should be answered by https://github.com/oleg-shilo/cs-script/wiki/Choosing-Compiler-Engine but doesn't do so yet (also see Script merger for hosted scripts #254). Remember the various past issues related to multi-module scripting (Change request to support relative paths for css_reference #26, Issue with multiple indirect relative paths #71, Recursive //css_import #83,...).
• I think the AppDomain topic deserves a separate section, which should talk about the pros and cons of using a separate AppDomain.
• "The next article Choosing Compiler Engine" currently isn't correct, as the next article talks about CLI (see CLI - hosted ordering topic further above).
• I think there should be a section talking about error handling, i.e. what happens in case the script cannot be compiled and how to retrieve the compiler errors, as well as how to handle css_* related errors.
• How about adding a section about interaction among script and hosting application? See e.g. TypeLoadException when trying to attach to event of hosting application #109.
• Also think the STA/MTA topic would deserve some notes.

CLI-Script-Execution.md

• "Note, On Windows you can use..." proposal:
  csws.dll - Windows application assembly. Available on Windows only. You may want to use it when executing the scripts that run as a Windows application without console attached.
  Is this WinForms? Or Win32 native?
• "CS-Script requires .NET 5 or higher..." proposal: Add a link to the Microsoft page that lists which version of .NET is available on which OS. Why? In many cases, users won't need to install anything.
• "Features" section replicates information already found in overview, proposing to have feature overview in a single location, unless it is hosted vs. CLI dependent.
• "C# IntelliSense plugin" broken link.
• "image" broken link, maybe https://github.com/oleg-shilo/cs-script/blob/master/src/wiki/css_logo_codeplex_256x256.png?

CLI---User-Guide.md

• I struggle a bit with what is in CLI-Script-Execution.md and what in CLI---User-Guide.md. I think the first should be an overview and all details in the user guide. But this means, the user guide must not refer to the overview, e.g. for "Deployment > Automated".
• "The whole CLI documentation can..." does not link/refer to CS-Script---Command-Line-Interface.md.

CS-Script---Command-Line-Interface.md

• Duplicated title.
• "Compiles script into Windows application executable."
  Is this WinForms? Or Win32 native?

Choosing-Compiler-Engine.md

• "see this overview" errenously links to Roadmap.md.
• "Note, the CodeDom is mapped" something wrong here.
• "and Roslyn (default)" contradicts with statement a bit above, where "default engine is dotnet for Windows and csc for all other OS".
• The default engine should be marked in the comparison tables.
• "Support for multi-file scripts" should be clarified in terms of:
• Support for css_reference directives? If so, "multi-module" scripting is better suited I think.
• Support for css_include/css_import directives?
• "Caching is disabled by default"? Why is caching disabled by default? Is this new behavior? Thought this was enabled by default in CS-Script v3.
• "to the .NET builder dotnet.exe" don't see why "builder" is italics whereas e.g. "compiler" below isn't.
• "by .NET 5 and higher (e.g.5)" something wrong here.

Broader questions related to hosting:

• Why is the dotnet engine not an option?
• Does the comparison table listed under "CLI" also apply to hosting? I guess so, thus proposing the separate the feature overview (multi-module scripting and the like) before going into details about the differences CLI vs. hosting.
• "Need SDK installed"
  Is there any suggested procedure for deploying the SDK with a hosting application? Consider my case, where the hosting application allows end-users to write and run the own scripts. So far, there is no need to install the SDK on the end-users machine, the .NET runtime is sufficient. But if the SDK is required, how can this easily be achieved? The 136 MB will blow up the size of the application's installer quite significantly...

Script-Syntax.md

• "location:<assm_hash>" is "assm" intended? Or rather "asm"?

CS-Script-Runtime-Environment-(script-reflection).md

• "the CS-Script Runtime here" links to "environment. Is "runtime" or "environment" the better matching name?
• The "ReflectScript sample" seems no longer available.

IDE-and-OS-integration

• There is room for better formatting, e.g. "Shell extensions (Windows only)" is hardly seen as section title, better use ####.

Roadmap.md

• "planned for early 2021" has long passed ;)
• "available ~Jan 2021" same ;)

_Sidebar.md

• I think the (+) can be removed now?
• Some inconsistencies
• "CLI" vs "CS-Script"
• "commands" vs "Command Line" ("Interface")
• [[CLI - commands|CS-Script---Command-Line-Interface]]
• References with/without "-"
• Anyway, why replicating "CS-Script" again and again. After all, we are at CS-Script. Thus proposing to simplify to e.g.
• "Overview"
• "Runtime Environment"

Still in the repo but no longer in the Wiki?

• C#-6-support.md
• Hosting-control.md which answers the STA/MTA topic mentioned earlier.
• NuGet-support.md
• Roslyn-Integration.md
• Using-custom-version-of-Roslyn.md

Uff, that's it, up to you on how to proceed. Let me know in case you'd like me to look at certain content again.

Best regards,
Matthias

[maettu-this]

PS: Let me know whether and when I shall delete branches/maettu_this_review_1 and branches/maettu_this_review_2. You may also delete them once merged.

[oleg-shilo]

Thank you Matthias, Excellent review. Not sure how you managed to do so much work. :) Will absolutely process it all. It will take time but I will definitely do it. txs.

[maettu-this]

Yepp, took me a while. Compared to the time you spent on CS-Script and the Wiki though almost nothing. Thanks for that!

[maettu-this]

PS: Have you ever taken a closer look to my profile's picture I recently changed? Was almost a year ago, in the meantime winter is here again at my side of the globe.

[oleg-shilo]

Looked at your avatar... I envy you. :)
Normally I go skiing every year (so have my snow experience/fix) but because of COVID have to pause now for two seasons...

BTW I have completely processed the PR so will be closing this issue. Thank you for your help.

[oleg-shilo]

Sorry, just realized that I only processed the PR but not your notes yet.
Reopening....

[oleg-shilo]

I decided to keep your very first post as is and use the list below for tracking the progress and the resolution status:

General

• Inconsistent on whether product names are italic or not, e.g. CS-Script vs. CS-Script.
• Inconsistent on whether using abbreviations or not, e.g. "Chocolatey" vs. "Choco".
• Inconsistent on how to quote, e.g. plain-vanilla vs. "plain vanilla" vs. 'plain vanilla' vs. "eval" vs. 'borrowed'.
• I struggle a bit with duplications among Home and Overview. Maybe either could be reduced, or they could be merged.
  [Oleg: agree. the content distribution between Home, Overview, and CLI and Hosted Execution is completely reworked.]
• Inconsistent on whether CLI or hosted comes first. CLI: Home, top of Overview,... Hosted: Sidebar, bottom of overview,... Proposing to always use CLI then hosted.
• Inconsistent commenting in examples, e.g. ; // IE ICalc implementation vs. ; //clear all ref assemblies, i.e. with/without space after // and lower/upper case.
• Inconsistent on referencing, e.g. "legacy Documentation online" (link @ "Documentation online") vs. "online documentation" (completely with link) vs. "online legacy documentation" (link @ "legacy documentation") as well as "the release page" (link @ "release page") vs. "Releases page" (link @ "Releases") vs. "Releases page" (link @ "Releases page") vs. "release page" (completely with link) vs. "releases page" (completely with link).

Home.md

• "It is also the place where you can ask the questions, make feature requests and report defects."
  Not exactly true, these topics are not in the Wiki, rather the project's Github page.
• The "How-to guide" no longer exists (dead link).
• What does "PM> " mean in "PM> Install-Package CS-Script"? [Oleg: This is the package manager prompt in the VS package management console. But I have removed it as it confused the reader.]

CS-Script-Overview.md

• "This top-level Wiki documentation"
  What do you mean by "top-level"? [Oleg: historically wiki was quite lean on documentation and the bulk of the information was captured by what is today "legacy online documentation". Fixed now.]
• Should https://www.cs-script.net/ be called legacy documentation? [Oleg: not exactly. It is not a documentation but a portal-like entry p[age for all CS-Script family products. I have also updated it. Still trying to make my mind about having an alternative to the removed 'Integration' page.]
  Or even better, merge and eliminate? e.g. https://www.cs-script.net/integration is empty.
• "execution by the script engine executable and hosted script (file or in-memory text) execution by the script engine hosted by the user application"
  Something wrong here.
• "in the online legacy documentation" leads to the wrong location (partly dead link).
• "new instance of IEvaluator" doesn't work, an interface cannot be instantiated, only a class implementing that interface.
• Proposing changing order to 1. "strongly typed" 2. dynamic 3. duck-typing as the latter two share the very same code. [Oleg: I left the order as is (it expresses the desired preference in the choice of the technique) but provided the explanation of the differences.]

Hosted-Script-Execution.md

• "Though if strongly typed delegate is preferred then you can use LoadDelegate instead:"
  Statement seems related to the string[] topic but example is not, somehow confusing.
• Not understanding the <ul style=... inline html, proposing to use markdown instead. [Oleg: that was the only way to cheat MD and shift paragraph right, but it does not work anymore. Fixed with a less effective but more reliable > shift]
• "Importing other scripts with //css_include" needs more in my opinion:
• Is css_include the preferred way to import other code now? When to better use css_import?
• What exactly are the possibilities and limitations for the available compilers in respect to css_...? I guess this should be answered by https://github.com/oleg-shilo/cs-script/wiki/Choosing-Compiler-Engine but doesn't do so yet (also see Script merger for hosted scripts #254). Remember the various past issues related to multi-module scripting (Change request to support relative paths for css_reference #26, Issue with multiple indirect relative paths #71, Recursive //css_import #83,...).
  [Oleg: the only //css_* limitation imposed by the compiler choice are only related to Roslyn engine(Script merger for hosted scripts #254) and is described directly in the same section "Thus, Roslyn API...". I have also added the same description to the limitations link. Though the rest of the issues you mentioned are not related to the compiler engines but were just issues with //css_*.]
• I think the AppDomain topic deserves a separate section, which should talk about the pros and cons of using a separate AppDomain.
  [Oleg: I have added the explanation why this technique is no longer adequate and provided the link so users can still use it if they choose to.]
• "The next article Choosing Compiler Engine" currently isn't correct, as the next article talks about CLI (see CLI - hosted ordering topic further above).
  [Oleg: not sure about this one. Leaving it as is and "the next article" talked about both CLI and hosted scenarios.]
• I think there should be a section talking about error handling, i.e. what happens in case the script cannot be compiled and how to retrieve the compiler errors, as well as how to handle css_* related errors.
• How about adding a section about interaction among script and hosting application? See e.g. TypeLoadException when trying to attach to event of hosting application #109.
• Also think the STA/MTA topic would deserve some notes.

CLI-Script-Execution.md

• "Note, On Windows you can use..." proposal:
  csws.dll - Windows application assembly. Available on Windows only. You may want to use it when executing the scripts that run as a Windows application without console attached.
  Is this WinForms? Or Win32 native?
  [Oleg: I added a few words there to make it clear but the answer to the question is the same as in the "CS-Script---Command-Line-Interface.md" section feedback.]
• "CS-Script requires .NET 5 or higher..." proposal: Add a link to the Microsoft page that lists which version of .NET is available on which OS. Why? In many cases, users won't need to install anything.
• "Features" section replicates information already found in overview, proposing to have feature overview in a single location, unless it is hosted vs. CLI dependent.
  [Yes it is CLI vs Hosted feature list. This page is a description of the complete feature set and the overview only lists some of them. I have updated the overview page to make it more obvious.]
• "C# IntelliSense plugin" broken link.
• "image" broken link, maybe https://github.com/oleg-shilo/cs-script/blob/master/src/wiki/css_logo_codeplex_256x256.png?

CLI---User-Guide.md

• I struggle a bit with what is in CLI-Script-Execution.md and what in CLI---User-Guide.md. I think the first should be an overview and all details in the user guide. But this means the user guide must not refer to the overview, e.g. for "Deployment > Automated".
  [Agree. It was a messy soup of information bits. Reworked. Now the root page is describing the distro, features, concept of directives and tools for scripting. And the user guide, well it guides the user how to keep it all together :)]

• "The whole CLI documentation can..." does not link/refer to CS-Script---Command-Line-Interface.md.

CS-Script---Command-Line-Interface.md

• Duplicated title.
• "Compiles script into Windows application executable."
  Is this WinForms? Or Win32 native?
  [Oleg: .NET applications are compiled on Windows as either "Console" or "Windows" application type. Thus when answering your "Schrödinger's cat" question :) the answer is:
  • it is not a native Win32 app but an assembly (even though it is a valid PE format)
  • it is not WinForms as it may popup no windows at runtime. And it can also be a WPF application.
    The most accurate description is that it is a Windows executable that does not attach a console window at startup.]

Choosing-Compiler-Engine.md

• "see this overview" errenously links to Roadmap.md.
• "Note, the CodeDom is mapped" something wrong here.
• "and Roslyn (default)" contradicts with statement a bit above, where "default engine is dotnet for Windows and csc for all other OS".
  [Oleg: Actually it's a contradiction. The previous section is for CLI and indeed dotnet is the default engine there. But for Hosted script execution (this very section) it is Roslyn.]
• The default engine should be marked in the comparison tables.
• "Support for multi-file scripts" should be clarified in terms of:
• Support for css_reference directives? If so, "multi-module" scripting is better suited I think.
• Support for css_include/css_import directives?
• "Caching is disabled by default"? Why is caching disabled by default? Is this new behavior? Thought this was enabled by default in CS-Script v3.
  [Oleg: yes it is changed as the result of migration to .NET Core. This is due to the fact that it is much harder to check if the script is changed since the last execution.]
• "to the .NET builder dotnet.exe" don't see why "builder" is italics whereas e.g. "compiler" below isn't.
• "by .NET 5 and higher (e.g.5)" something wrong here.

Broader questions related to hosting:

• Why is the dotnet engine not an option?
  [Oleg: It is an option for CLI but not for hosting script engine. The reason is that dotnet.exe is extremely slow. It is a heavy but acceptable price (e.g. it can run WPF scripts) for CLI but there is no good justification nor true benefit hosted scripting.]
• Does the comparison table listed under "CLI" also apply to hosting? I guess so, thus proposing the separate the feature overview (multi-module scripting and the like) before going into details about the differences CLI vs. hosting.
  [Oleg: no it does not. Both CLI and hosting are separate independent sections with their own tables. I have placed a special disclaimer emphasising this fact.]
• "Need SDK installed"
  Is there any suggested procedure for deploying the SDK with a hosting application? Consider my case, where the hosting application allows end-users to write and run their own scripts. So far, there is no need to install the SDK on the end-users machine, the .NET runtime is sufficient. But if the SDK is required, how can this easily be achieved? The 136 MB will blow up the size of the application's installer quite significantly...
  [Oleg: 6 - Deployment of SDK is beyond CS-Script project/product scope. If SDK is needed then one needs to use .NET resources for finding the best way of achieving this. This wiki only describes the prerequisites. BTW, with the latest improvements in Roslyn engine you will almost never need to use other than compiler engine for hosting cs-script other than Roslyn]

Script-Syntax.md

• "location:<assm_hash>" is "assm" intended? Or rather "asm"?

CS-Script-Runtime-Environment-(script-reflection).md

• "the CS-Script Runtime here" links to "environment. Is "runtime" or "environment" the better matching name?
• The "ReflectScript sample" seems no longer available.

IDE-and-OS-integration

• There is room for better formatting, e.g. "Shell extensions (Windows only)" is hardly seen as section title, better use ####.

Roadmap.md

[Oleg: the very first sentence on the page explains that the roadmap has been achieved already and the page is only kept as a historical record. But I made it now even more clear by changing the title to "Transition from .NET Framework to .NET"]

• "planned for early 2021" has long passed ;)
• "available ~Jan 2021" same ;)

_Sidebar.md

• I think the (+) can be removed now?
• Some inconsistencies [Oleg: I have addressed major inconsistencies but in one case I left it a is as the title 'Command-Line-Interfac' is a part of the URL that is being referenced externally.]
• "CLI" vs "CS-Script"
• "commands" vs "Command Line" ("Interface")
• [[CLI - commands|CS-Script---Command-Line-Interface]]
• References with/without "-"
• Anyway, why replicating "CS-Script" again and again. After all, we are at CS-Script. Thus proposing to simplify to e.g.
• "Overview"
• "Runtime Environment"

Still in the repo but no longer in the Wiki?

[Oleg: all of thame are no longer needed. Now removed.]

• C#-6-support.md
• Hosting-control.md which answers the STA/MTA topic mentioned earlier.
• NuGet-support.md
• Roslyn-Integration.md
• Using-custom-version-of-Roslyn.md

[oleg-shilo]

Done!!!

Finally, I managed to process your feedback. The most obvious problem was the excessive fragmentation of the content as the result of frequent but less systematic updates of Wiki.

Now I have merged quite a few articles and created a more consistent documentation structure that most likely will be more helpful compared to the old documentation, which is btw still available on "https://github.com/oleg-shilo/cs-script.net-framework"

Really appreciate your help. Without it would be close to impossible to achieve that much improvement.

Now I can focus on the release for .NET6. It's ready for the last ~3 days. Was delaying the release until I fix the documentation.

[maettu-this]

Wow! I did fly over your comments and the wiki, well-done! And I feel honored to get this done before such major release!

Please go ahead with the release. After, let's talk again about...

Does the comparison table listed under "CLI" also apply to hosting? I guess so, thus proposing to separate the feature overview (multi-module scripting and the like) before going into details about the differences CLI vs. hosting.
[Oleg: no it does not. Both CLI and hosting are separate independent sections with their own tables. I have placed a special disclaimer emphasising this fact.]

...as I do not understand why there is no equal comparison for hosting, i.e. why the hosting table...

• only covers performance, namespaces and SDK but not WinForms, WPF, NuGet and //css_*.
• uses a different sequence (performance-NS-SDK) than the CLI table (performance-SDK-NS-...).

Why am I insisting?

with the latest improvements in Roslyn engine you will almost never need to use other than compiler engine for hosting cs-script other than Roslyn

This may be true for most users of CS-Script. But from all the information I now have not for me (= the mentioned "you"). Because my hosting application heavily relys on multi-module scripting and namespaces. So Roslyn unfortunately still looks like a non-option. Resulting in the fact that my hosting application will have to deploy the SDK in the future (after moving away from FX).

I fully understand that moving away from FX is the future of anything on .NET. And I fully understand that CS-Script could not chose the set of features and restrictions of Roslyn. But please also understand that, in case of my hosting application, the impacts of moving away from FX are not neglectable unfortunately.

So far, there is no defined end date for FX support by Microsoft. So I play with the idea of continuing on FX for the next few years, at the cost of not being able to move further than C# 5. As always, there's no free lunch ;)

[oleg-shilo]

...as I do not understand why there is no equal comparison for hosting, i.e. why the hosting table...

Because criteria like NuGet, WinForm or WPF scripting are not really applicable for hosted scripting scenarios. Though since you are asking this question I have matched both tables layout and indicated non applicable cells.

Because my hosting application heavily relys on multi-module scripting and namespaces. So Roslyn unfortunately still looks like a non-option.

I am not sure we are on the same page here.
Hosted CS-Script can use two compiler engines: Roslyn and csc.
Roslyn offers limited support for multi-module scripts. And csc supports multi-module scripting fully. If dotnet engine was available for hosted scripting the only advantage it would bring is XAML compilation (WPF). That's it. See this table.

Thus it is important to note that there are some limitations associated with the compiling engines and there are some other limitations associated with the scenarios these engines are used in.

To truly summarise it I have put a summary table before describing the engines in the CLI and Hosted ssections.

[maettu-this]

Very good, the summary table was what I initially proposed to give an overview of the engine's capabilities. The hosted scenarios though may be quite different:

criteria like NuGet, WinForm or WPF scripting are not really applicable for hosted scripting scenarios

Give me another year and you'll see that they actually are in my hosted scenario (users can write their own scripts, including simple to medium UIs that pop up when running the script or integrate into the hosting application (that's where the AppDomain discussion comes into play).

The information I now have is sufficient for the moment. I will now focus on finalizing the hosted scenario and making it open-source. I can then later decide on how to move towards .NET 5/6/... I think integrating the SDK (in order to support csc instead of Roslyn) should be achievable. I might provide separate installers, with and without the SDK, i.e. with and without scripting capabilities.

There is just one minor thing I noted in the wiki:

• Footnotes 2, 3, 4, 5 of "Hosting" are not nicely aligned after each other.

Then I think this issues can be closed :-)

[oleg-shilo]

Of course. Txs. Done 😄