docs

readme.md

@@ -2,11 +2,9 @@
 
 # Razor Blade v1.0 stable
 
-A library of common functions for Razor, to lighten Razor templates and make work easier.
+A library of common functions for Razor, to lighten Razor templates and make work easier. Some examples:
 
-The goal is to provide helpers for very common code snippets or functions, which would lighten the load. Here some common examples...
-
-_Sometimes you need the first 100 characters followed by an ellipsis (if truncated), but umlauts like `ü` will mess up your count or might even be cut off. This is automatically handled by:_
+_You need the first 100 characters followed by an ellipsis (if truncated), but umlauts like `ü` will mess up your count or might even be cut off. This is automatically handled by:_
 
 ```razor
   @* just cut it off at the visible character count, not splitting words *@
@@ -19,27 +17,26 @@ _Sometimes you need the first 100 characters followed by an ellipsis (if truncat
   @Text.Ellipsis(Tags.Strip(longText), 100)
 ```
 
-_Or sometimes you need a value, but if it's empty, you need another one. So instead of writing:_
+_You need a value, but if it's empty (null, spaces, line-breaks, ` ` etc.), you need another one:_
 
 ```razor
+  @* Do this *@
+  @Text.First(firstName, "nothing found");
+
+  @* instead of this *@
   @if(String.IsNullOrWhiteSpace(firstName as string)) {
     @"nothing found"
   } else {
     @firstName
   }
 ```
 
-_You can write this, or below it the example with even more values:_
+_Note that HTML whitespace like ` ` will also be treated as empty, unless you add `false` as a last parameter. But RazorBlade does more than just skip empty texts, here some more examples:_
 
 ```razor
-  @Text.First(firstName, "nothing found");
-
+  @* First non-empty of many possible values *@
   @Text.First(nameFromDb, nameFromProfile, defaultNameForThisCountry, "unknown")
-```
 
-_Note that HTML whitespace like ` ` will also be treated as empty, unless you add `false` as a last parameter. But RazorBlade does more than just skip empty texts, here some more examples:_
-
-```razor
   @* remove html from a wysiwyg-string *@
   @Tags.Strip(formattedText)