Polish documentation

Author: NeilMacMullen

README.md

@@ -2,7 +2,7 @@
 
 ## Give a Star! :star:
 
-If you like or are using this project please give it a star or leave some feedback in the [discussions](https://github.com/NeilMacMullen/Textrude/discussions/categories/send-a-smile) section. Thanks!
+If you like or are using this project please give it a star or leave some feedback in the [discussions](https://github.com/NeilMacMullen/Textrude/discussions/categories/send-a-smile) section. A little feedback goes a long way - thanks!
 
 ## What is it?
 
@@ -28,19 +28,25 @@ Let's face it, there are any number of code-generation technologies you might co
 
 Get pre-built binaries from the [Releases](https://github.com/NeilMacMullen/Textrude/releases) area or build yourself from source.
 
+You may need to install [.Net 5.0](https://dotnet.microsoft.com/download/dotnet/5.0) if it is not already on your machine.
 
-##Known issues...
+The binaries are provided in the form of a zip which includes single-file executables as well as example projects and library scripts. 
+
+
+## Known issues...
 - YAML and CSV deserialisers will always attempt to force strings that look like numbers or booleans into that format rather than leaving them as strings.  Most of the time this does not matter but please raise an issue if this causes particular problems
 - TextrudeInteractive does not warn when closing if project is dirty.
 - Textrude.exe is untested on Linux - please raise an issue if you run into problems
 
 ## Documentation
 - [Getting started with template generation](doc/gettingStarted.md) 
-- Built in functions and helpers
-- Creating your own library of functions and templates
-- Using Textrude in a build system
-- advanced usage - multiple models and/or output files
-- use the exportInvocation
+- [Built in functions and helpers](doc/builtIns.md)
+- [Evironment variables and user-definitions](doc/environmentAndDefinitions.md)
+- [Multiple models and/or output files](doc/multiModel.md)
+
+- [Creating and using library functions](doc/userlibrary.md)
+- [Using Textrude in a build system](doc/buildSystemIntegration.md)
+
 
 ## Credits
 
@@ -49,34 +55,32 @@ Textrude makes heavy use of the following components:
 - [CsvHelper](https://github.com/JoshClose/CsvHelper) for command-line parsing
 - [YamlDotNet](https://github.com/aaubry/YamlDotNet) for YAML deserialisation
 - [Json.Net](https://www.newtonsoft.com/json) for Json deserialisation
-
-## Contributors guide
-Adding new model deserialisers...
-Architecture...
-
-"Quick and dirty" - use jsonserialiser for new format types ... BUT can lose type information - particularly with numbers
-
-file -> [Deserialiser] -> JObject -> ScriptObject
+- [Humanizr](https://github.com/Humanizr/Humanizer) for useful text-processing
+- [MaterialDesignToolkit](https://github.com/MaterialDesignInXAML/MaterialDesignInXamlToolkit),   [MaterialDesignExtensions](https://spiegelp.github.io/MaterialDesignExtensions) and [Ookii Dialogs](https://github.com/augustoproiete/ookii-dialogs-wpf)to make the UI a bit less clunky
+  
 
 
-[Templatetext]
-[modelText] 
 
-[definionsText] -> 
-[envs] 
+## Help wanted 
 
-Extensions
---binding custom dotnet functions- build your own version
+If you fancy making Textrude better, I'd be happy to have help! Some ideas for improvement...
 
-Help wanted 
-TextrudeInteractive has a UI only a developer could love and is very much a "scratch" project.  Help make it better....
-Contribute to library methods
-Test on linux
-Documentation
+- UI
+    - Change the current scratch code to a more formal MVVM architecture
+    - Improve the text-edit boxes to show line numbers, syntax-hightlighting etc (maybe use AvalonEdit?)
+    - Intellisense for template editing (we should be able to walk the models and suggest sensible dot completions)
+- Documentation and example projects
+- Library methods and helpers
+  - More library functions for common tasks
+  - Suggestions for 3rd party helper packages such as Humanizr
+- Distribution
+  - Chocolately package?  
+- General usage
+  - Bug-reporting, real-world usability, Linux testing
 
 
 ## What's with the name 
 It's short for Text-extrude but if you can't stop seeing it as Text-Rude you are not alone.
 
-It is unrelated to the rather cool (but apparently abandoned project) [Textruder](https://github.com/arrogantrobot/textruder) or to plastics company [Tex-Trude](http://www.tex-trude.com/)
+It is unrelated to both the rather cool (but apparently abandoned project) [Textruder](https://github.com/arrogantrobot/textruder) and the plastics company [Tex-Trude](http://www.tex-trude.com/)
 

Tests/Tests.csproj

@@ -11,7 +11,7 @@
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.8.3" />
     <PackageReference Include="MSTest.TestAdapter" Version="2.1.2" />
     <PackageReference Include="MSTest.TestFramework" Version="2.1.2" />
-    <PackageReference Include="coverlet.collector" Version="1.3.0">
+    <PackageReference Include="coverlet.collector" Version="3.0.0">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>

doc/buildSystemIntegration.md

@@ -1,4 +1,56 @@
 # Build system integration
 
-use textrude.exe --help to get a list of command
-textrude.exe help command to get detailed help
+TextrudeInteractive is useful for prototyping and developing models and templates but integration with a build-system requires use of the *textrude.exe* command-line tool.  This version can do everythng that TextrudeInteractive does and has a few extra features:
+
+## Getting help
+- use ```textrude.exe --help``` to get a list of command
+- use ```textrude.exe help``` *command* to get detailed help
+
+## Basic rendering
+
+```textrude.exe render --models model.yaml --template template.sbn --output out.txt```
+
+If no *--output* is specified, the output will be written to stdout.
+
+## Multiple input/output
+
+```textrude.exe render --models "model0.Yaml" "model1.Json" "model2.Csv" --template "template.sbn" --output "out.txt" "out1.txt"```
+
+## Definitions
+
+```textrude.exe render --models model.yaml --template template.sbn --output out.txt --definitions "LANGUAGE=ENGLISH" "COUNTRY=UK"
+```
+
+## Include-paths
+
+```textrude.exe render --models model.yaml --template template.sbn --output out.txt --include "d:\work\slib" "d:\work\lib2"
+```
+## Dependency checking
+
+By default, the render pass is always run.  However, if the *--lazy* flag is supplied the Textrude will only render the output files if:
+- any of the output files are missing
+- any of the model files or the template file is newer than any of the output files.
+
+Textrude is NOT able to perform dependency checking of library files include via the *include* directive.
+
+## Return codes
+
+0 - successful render or render skipped due to **lazy** flag 
+1 - fault
+
+## RenderFromFile
+
+Sometimes it can be useful to be able to provide arguments from a file. The **renderFromFile** command allows the argument set to be passed in as a YAML or JSON structure.
+
+```textrude.exe renderFromFile --arguments args.yaml```
+
+You can easily generate example argument files by using the *project->export as invocation* option from TextrudeInteractive.
+
+
+
+
+
+
+
+
+

doc/builtIns.md

@@ -0,0 +1,43 @@
+# Built-in functions and helpers
+
+
+## Debug
+
+*debug.dump* generates a representation of the object.  For example:
+```
+{{debug.dump model}}
+```
+
+## Humanizr
+
+Textrude provides all the methods of the [Humanizr](https://github.com/Humanizr/Humanizer) library via the *humanizr* namespace.  These are particularly useful for enforcing naming-conventions in generated code.  For example
+
+```
+The standard C naming for camel-cased strings looks like...
+
+{{"CamelCasedFunctionName" | humanizr.underscore}}
+```
+
+*Humanizr* has manyother useful functions - see the home page for more information.
+
+See the *humanizr.txtproj* project in the examples folder for more examples
+
+
+## Misc
+
+*misc.new_guid* generates a new GUID 
+
+See the *misc.txtproj* project in the examples folder for more examples
+
+
+## Libraries 
+
+### warnings
+The *autogenwarning* function provides a useful warning block at the beginning of the output.
+```
+{{include "lib/warnings.sbn}}
+{{autogenwarning}}
+```
+See the *includeExample* project in the examples folder. 
+
+

doc/environmentAndDefinitions.md

@@ -0,0 +1,7 @@
+# Environment Variables and User-definitions
+
+It's common when automating code-generation to want to pass in information that is not part of the model.  Textrude *automatically* imports the environment variables from the current process and makes these available in the *env* namespace.  
+
+You can also supply *definitions* which appear in the *def* namespace.  Definitions can be added from the "other->definitions" tab in TextrudeInteractive.
+
+See the *enviromentAndDefinitions.texproj* project in the examples folder

doc/multiModel.md

@@ -0,0 +1,9 @@
+# Using multiple models and/or multiple output files
+
+It's sometimes useful to be able to combine information from multiple models and to render output to more than one file.  For example, you might want to use a single template to render both a .h header file and a .cpp source file.
+
+Textrude allows multiple models to be referenced as *model0*, *model1*, *model2* etc.   There is no limit on the number of models that can be supplied although the UI of TextrudeInteractive current only supports 3.
+
+By default, all output is rendered to the main output window but the SCRIBAN *capture* keyword can be used to redirect output to *output1*, *output2* etc.  Currently only 10 output streams are supported.
+
+The *multiInOut.texproj* project in the examples folder demonstrates this feature.

doc/userLibrary.md

@@ -0,0 +1,16 @@
+# Creating a library of functions
+
+Textrude supports reuse of code and templates via the SCRIBAN *include* function.
+You can set up additional include paths in the *other->include paths* section of the UI.
+
+**IMPORTANT** 
+You should use unix-style slashes for path separators
+
+Example:
+
+```
+{{include "customlib/myfunctions.sbn"}}
+```
+
+
+

examples/enumtest.texproj

@@ -0,0 +1,25 @@
+{
+  "Description": "",
+  "EngineInput": {
+    "Definitions": [
+      "LANGUAGE=ENGLISH",
+      "COUNTRY=United Kingdom"
+    ],
+    "IncludePaths": [],
+    "Models": [
+      {
+        "Format": 2,
+        "Text": ""
+      },
+      {
+        "Format": 2,
+        "Text": ""
+      },
+      {
+        "Format": 2,
+        "Text": ""
+      }
+    ],
+    "Template": "Access environment variables via the \u0027env\u0027 namespace:\r\n\r\n{{env.USERNAME}}\r\n\r\n\r\nAdd definitions from the other-\u003Edefintions tab and \r\naccess them via the \u0027def\u0027 namespace:\r\n\r\n{{def.LANGUAGE}} / {{def.COUNTRY}}\r\n\r\nYou can easily list all environment variables like this:\r\n\r\n{{debug.dump env}}\r\n"
+  }
+}

examples/environmentAndDefinitions.texproj

@@ -0,0 +1,22 @@
+{
+  "Description": "",
+  "EngineInput": {
+    "Definitions": [],
+    "IncludePaths": [],
+    "Models": [
+      {
+        "Format": 1,
+        "Text": "text\r\na variable\r\nNameOfThing\r\nThe title of this book is\r\n\u0022  with spaces   \u0022"
+      },
+      {
+        "Format": 2,
+        "Text": ""
+      },
+      {
+        "Format": 2,
+        "Text": ""
+      }
+    ],
+    "Template": "{{for v in model}}\r\n \r\n\u0027{{v.text}}\u0027\r\n   PASCALIZE:   \u0027{{v.text | humanizr.pascalize}}\u0027\r\n   CAMEL:       \u0027{{v.text | humanizr.camelize}}\u0027\r\n   UNDERSCORE:  \u0027{{v.text | humanizr.underscore}}\u0027\r\n   TITLE:       \u0027{{v.text | humanizr.titleize}}\u0027\r\n   KEBAB:       \u0027{{v.text | humanizr.kebaberize}}\u0027\r\n\r\n{{end}}"
+  }
+}

examples/ex1_error_codes.texproj

@@ -17,6 +17,6 @@
         "Text": ""
       }
     ],
-    "Template": ""
+    "Template": "{{include \u0022lib/warnings.sbn\u0022}}\r\n\r\n{{autogenwarning}}"
   }
 }

examples/humanizr.texproj

@@ -0,0 +1,22 @@
+{
+  "Description": "",
+  "EngineInput": {
+    "Definitions": [],
+    "IncludePaths": [],
+    "Models": [
+      {
+        "Format": 0,
+        "Text": "{\r\n\u0022top\u0022 : {\r\n \u0022number\u0022: 1,\r\n \u0022string\u0022: \u0022a string\u0022,\r\n \u0022array\u0022: [ 1,2,3,4]\r\n}\r\n}"
+      },
+      {
+        "Format": 2,
+        "Text": ""
+      },
+      {
+        "Format": 2,
+        "Text": ""
+      }
+    ],
+    "Template": "Here\u0027s a fresh guid...\r\n\r\n{{misc.new_guid}}\r\n\r\nHere\u0027s what your model looks like:\r\n\r\n{{debug.dump model}}\r\n"
+  }
+}

examples/test.texproj renamed to examples/includeExample.texproj

@@ -0,0 +1,22 @@
+{
+  "Description": "",
+  "EngineInput": {
+    "Definitions": [],
+    "IncludePaths": [],
+    "Models": [
+      {
+        "Format": 2,
+        "Text": "name: yaml"
+      },
+      {
+        "Format": 0,
+        "Text": "{\r\n \u0022name\u0022:\u0022json\u0022\r\n}"
+      },
+      {
+        "Format": 1,
+        "Text": "name\r\ncsv"
+      }
+    ],
+    "Template": "Model 0 is {{model0.name}}\r\nModel 1 is {{model1.name}}\r\nModel 2 is {{model2[0].name}}\r\n\r\n\u0027model\u0027 is synonymous with \u0027model0\u0027...\r\n\r\n\u0027{{model.name}}\u0027 shoud be the same as \u0027{{model0.name}}\u0027\r\n\r\nTo write to another output, use the capture keyword...\r\n\r\n{{-capture output1}}\r\nYou won\u0027t see this in the output window. \r\nCheck the \u0022output1\u0022 window instead\r\n{{end}}\r\n\r\n\r\n{{-capture output2}}\r\nCapture scopes are temporary.\r\n{{end}}\r\n\r\nThat\u0027s all!\r\n"
+  }
+}