F# plaintext printing documentation

docs/fsharp/language-reference/fsharp-interactive-options.md

@@ -1,21 +1,18 @@
 ---
-title: Interactive Options
+title: Interactive options
 description: Learn about the command-line options supported by F# Interactive, fsi.exe.
-ms.date: 05/16/2016
+ms.date: 07/22/2020
 ---
-# F# Interactive Options
+# F# Interactive options
 
-> [!NOTE]
-> This article currently describes the experience for Windows only.  It will be rewritten.
+This article describes the command-line options supported by F# Interactive, `fsi.exe`. F# Interactive accepts many of the same command line options as the F# compiler, but also accepts some additional options.
 
-This topic describes the command-line options supported by F# Interactive, `fsi.exe`. F# Interactive accepts many of the same command line options as the F# compiler, but also accepts some additional options.
+## Use F# Interactive for scripting
 
-## Using F# Interactive for Scripting
+F# Interactive, `dotnet fsi`, can be launched interactively, or it can be launched from the command line to run a script. The command line syntax is
 
-F# Interactive, `fsi.exe`, can be launched interactively, or it can be launched from the command line to run a script. The command line syntax is
-
-```console
-> fsi.exe [options] [ script-file [arguments] ]
+```dotnetcli
+dotnet fsi [options] [ script-file [arguments] ]
 ```
 
 The file extension for F# script files is `.fsx`.
@@ -52,8 +49,6 @@ Where lists appear in F# Interactive option arguments, list elements are separat
 |**--quotations-debug**|Specifies that extra debugging information should be emitted for expressions that are derived from F# quotation literals and reflected definitions. The debug information is added to the custom attributes of an F# expression tree node. See [Code Quotations](code-quotations.md) and [Expr.CustomAttributes](https://msdn.microsoft.com/library/eb89943f-5f5b-474e-b125-030ca412edb3).|
 |**--readline**[**+**|**-**]|Enable or disable tab completion in interactive mode.|
 |**--reference:&lt;filename&gt;**<br /><br />**-r:&lt;filename&gt;**|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).|
-|**--shadowcopyreferences**[**+**&#124;**-**]|Prevents references from being locked by the F# Interactive process.|
-|**--simpleresolution**|Resolves assembly references using directory-based rules rather than MSBuild resolution.|
 |**--tailcalls**[**+**&#124;**-**]|Enable or disable the use of the tail IL instruction, which causes the stack frame to be reused for tail recursive functions. This option is enabled by default.|
 |**--targetprofile:&lt;string&gt;**|Specifies target framework profile of this assembly. Valid values are mscorlib, netcore or netstandard.  The default is mscorlib.|
 |**--use:&lt;filename&gt;**|Tells the interpreter to use the given file on startup as initial input.|
@@ -62,7 +57,107 @@ Where lists appear in F# Interactive option arguments, list elements are separat
 |**--warnaserror**[**+**&#124;**-**]|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).|
 |**--warnaserror**[**+**&#124;**-**]:**&lt;int-list&gt;**|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).|
 
-## Related Topics
+## F# Interactive structured printing
+
+F# Interactive (`dotnet fsi`) uses an extended version of [structured plain text formatting](plaintext-formatting.md) to
+report values.
+
+1. All features of `%A` plain text formatting are supported, and some are additionally customizable.
+
+2. Printing is colorized if colors are supported by the output console.
+
+3. A limit is placed on the length of strings shown, unless you explicitly evaluate that string.
+
+4. A set of user-definable settings are available via the `fsi` object.
+
+The available settings to customize plain text printing for reported values are:
+
+```fsharp
+open System.Globalization
+
+fsi.FormatProvider <- CultureInfo("de-DE")  // control the default culture for primitives
+
+fsi.PrintWidth <- 120        // Control the width used for structured printing
+
+fsi.PrintDepth <- 10         // Control the maximum depth of nested printing
+
+fsi.PrintLength <- 10        // Control the length of lists and arrays
+
+fsi.PrintSize <- 100         // Control the maximum overall object count
+
+fsi.ShowProperties <- false  // Control whether properties of .NET objects are shown by default
+
+fsi.ShowIEnumerable <- false // Control whether sequence values are expanded by default
+
+fsi.ShowDeclarationValues <- false // Control whether values are shown for declaration outputs
+```
+
+### Customize with `AddPrinter` and `AddPrintTransformer`
+
+Printing in F# Interactive outputs can be customized by using `fsi.AddPrinter` and `fsi.AddPrintTransformer`.
+The first function gives text to replace the printing of an object. The second function returns a surrogate object to display
+instead. For example, consider the following F# code:
+
+```fsharp
+open System
+
+fsi.AddPrinter<DateTime>(fun dt -> dt.ToString("s"))
+
+type DateAndLabel =
+    { Date: DateTime
+      Label: string  }
+
+let newYearsDay1999 =
+    { Date = DateTime(1999, 1, 1)
+      Label = "New Year" }
+```
+
+If you execute the example in F# Interactive, it outputs based on the formatting option set. In this case, it affects the formatting of date and time:
+
+```console
+type DateAndLabel =
+  { Date: DateTime
+    Label: string }
+val newYearsDay1999 : DateAndLabel = { Date = 1999-01-01T00:00:00
+                                       Label = "New Year" }
+```
+
+`fsi.AddPrintTransformer` can be used to give a surrogate object for printing:
+
+```fsharp
+type MyList(values: int list) =
+    member _.Values = values
+
+fsi.AddPrintTransformer(fun (x:MyList) -> box x.Values)
+
+let x = MyList([1..10])
+```
+
+This outputs:
+
+```console
+val x : MyList = [1; 2; 3; 4; 5; 6; 7; 8; 9; 10]
+```
+
+If the transformer function passed to `fsi.AddPrintTransformer` returns `null`, then the print transformer is ignored.
+This can be used to filter any input value by starting with type `obj`.  For example:
+
+```fsharp
+fsi.AddPrintTransformer(fun (x:obj) ->
+    match x with
+    | :? string as s when s = "beep" -> box ["quack"; "quack"; "quack"]
+    | _ -> null)
+
+let y = "beep"
+```
+
+This outputs:
+
+```console
+val y : string = ["quack"; "quack"; "quack"]
+```
+
+## Related topics
 
 |Title|Description|
 |-----|-----------|

docs/fsharp/language-reference/index.md

@@ -45,6 +45,7 @@ The following table shows reference topics available that describe language conc
 |[Signatures](signature-files.md)|Describes signatures and signature files. A signature file contains information about the public signatures of a set of F# program elements, such as types, namespaces, and modules. It can be used to specify the accessibility of these program elements.|
 |[XML Documentation](xml-documentation.md)|Describes support for generating documentation files for XML doc comments, also known as triple slash comments. You can produce documentation from code comments in F# just as in other .NET languages.|
 |[Verbose Syntax](verbose-syntax.md)|Describes the syntax for F# constructs when lightweight syntax is not enabled. Verbose syntax is indicated by the `#light "off"` directive at the top of the code file.|
+|[Plain Text Formatting](plaintext-formatting.md)|Learn how to use sprintf and other plain text formatting in F# applications and scripts.|
 
 ## F# Types