Bring the README quality into line with the rolling file sink's

Author: nblumhardt

README.md

@@ -1,49 +1,189 @@
 # Serilog.Sinks.File [![Build status](https://ci.appveyor.com/api/projects/status/hh9gymy0n6tne46j?svg=true)](https://ci.appveyor.com/project/serilog/serilog-sinks-file) [![Travis build](https://travis-ci.org/serilog/serilog-sinks-file.svg)](https://travis-ci.org/serilog/serilog-sinks-file) [![NuGet Version](http://img.shields.io/nuget/v/Serilog.Sinks.File.svg?style=flat)](https://www.nuget.org/packages/Serilog.Sinks.File/) [![Documentation](https://img.shields.io/badge/docs-wiki-yellow.svg)](https://github.com/serilog/serilog/wiki) [![Join the chat at https://gitter.im/serilog/serilog](https://img.shields.io/gitter/room/serilog/serilog.svg)](https://gitter.im/serilog/serilog)
 
-Writes [Serilog](https://serilog.net) events to a text file.
+Writes [Serilog](https://serilog.net) events to one or more text files.
+
+### Getting started
+
+Install the [Serilog.Sinks.File](https://nuget.org/serilog/serilog-sinks-file) package from NuGet:
+
+```powershell
+Install-Package Serilog.Sinks.File -Pre
+```
+
+To configure the sink in C# code, call `WriteTo.File()` during logger configuration:
 
 ```csharp
 var log = new LoggerConfiguration()
-    .WriteTo.File("log.txt")
+    .WriteTo.File("log.txt", rollingInterval: RollingInterval.Day)
     .CreateLogger();
 ```
 
+This will append the time period to the filename, creating a file set like:
+
+```
+log20180631.txt
+log20180701.txt
+log20180702.txt
+```
+
+> **Important**: By default, only one process may write to a log file at a given time. See _Shared log files_ below for information on multi-process sharing.
+
+### Limits
+
 To avoid bringing down apps with runaway disk usage the file sink **limits file size to 1GB by default**. The limit can be increased or removed using the `fileSizeLimitBytes` parameter.
 
 ```csharp
     .WriteTo.File("log.txt", fileSizeLimitBytes: null)
 ```
 
-> **Important:** By default only one process may use a log file at a given time. See _Shared log files_ below if multi-process logging is required. 
+For the same reason, only **the most recent 31 files** are retained by default (i.e. one long month). To change or remove this limit, pass the `retainedFileCountLimit` parameter.
+
+```csharp
+    .WriteTo.RollingFile("log.txt", rollingInterval: RollingInterval.Day, retainedFileCountLimit: null)
+```
+
+### Rolling policies
+
+To create a log file per day or other time period, specify a `rollingInterval` as shown in the examples above.
+
+To roll when the file reaches `fileSizeLimitBytes`, specify `rollOnFileSizeLimit`:
+
+```csharp
+    .WriteTo.File("log.txt", rollOnFileSizeLimit: true)
+```
+
+This will create a file set like:
+
+```
+log.txt
+log_001.txt
+log_002.txt
+```
+
+Specifying both `rollingInterval` and `rollOnFileSizeLimit` will cause both policies to be applied, while specifying neither will result in all events being written to a single file.
+
+Old files will be cleaned up as per `retainedFileCountLimit` - the default is 31.
+
+### XML `<appSettings>` configuration
+
+To use the file sink with the [Serilog.Settings.AppSettings](https://github.com/serilog/serilog-settings-appsettings) package, first install that package if you haven't already done so:
+
+```powershell
+Install-Package Serilog.Settings.AppSettings
+```
+
+Instead of configuring the logger in code, call `ReadFrom.AppSettings()`:
+
+```csharp
+var log = new LoggerConfiguration()
+    .ReadFrom.AppSettings()
+    .CreateLogger();
+```
+
+In your application's `App.config` or `Web.config` file, specify the file sink assembly and required path format under the `<appSettings>` node:
+
+```xml
+<configuration>
+  <appSettings>
+    <add key="serilog:using:File" value="Serilog.Sinks.File" />
+    <add key="serilog:write-to:File.pathFormat" value="log.txt" />
+```
+
+The parameters that can be set through the `serilog:write-to:File` keys are the method parameters accepted by the `WriteTo.File()` configuration method. This means, for example, that the `fileSizeLimitBytes` parameter can be set with:
+
+```xml
+    <add key="serilog:write-to:File.fileSizeLimitBytes" value="1234567" />
+```
+
+Omitting the `value` will set the parameter to `null`:
 
-### `<appSettings>` configuration
+```xml
+    <add key="serilog:write-to:File.fileSizeLimitBytes" />
+```
 
-The sink can be configured in XML [app-settings format](https://github.com/serilog/serilog/wiki/AppSettings) if the _Serilog.Settings.AppSettings_ package is in use:
+In XML and JSON configuration formats, environment variables can be used in setting values. This means, for instance, that the log file path can be based on `TMP` or `APPDATA`:
 
 ```xml
-<add key="serilog:using:File" value="Serilog.Sinks.File" />
-<add key="serilog:write-to:File.path" value="log.txt" />
-<add key="serilog:write-to:File.fileSizeLimitBytes" value="" />
+    <add key="serilog:write-to:File.path" value="%APPDATA%\MyApp\log.txt" />
 ```
 
-### JSON formatting
+### JSON `appsettings.json` configuration
+
+To use the file sink with _Microsoft.Extensions.Configuration_, for example with ASP.NET Core or .NET Core, use the [Serilog.Settings.Configuration](https://github.com/serilog/serilog-settings-configuration) package. First install that package if you have not already done so:
+
+```powershell
+Install-Package Serilog.Settings.Configuration
+```
 
-To emit JSON, rather than plain text, a formatter can be specified:
+Instead of configuring the file directly in code, call `ReadFrom.Configuration()`:
 
 ```csharp
-    .WriteTo.File(new JsonFormatter(), "log.txt")
+var configuration = new ConfigurationBuilder()
+    .AddJsonFile("appsettings.json")
+    .Build();
+
+var logger = new LoggerConfiguration()
+    .ReadFrom.Configuration(configuration)
+    .CreateLogger();
+```
+
+In your `appsettings.json` file, under the `Serilog` node, :
+
+```json
+{
+  "Serilog": {
+    "WriteTo": [
+      { "Name": "File", "Args": { "path": "log.txt", "rollingInterval": "Day" } }
+    ]
+  }
+}
 ```
 
-To configure an alternative formatter in XML `<appSettings>`, specify the formatter's assembly-qualified type name as the setting `value`.
+See the XML `<appSettings>` example above for a discussion of available `Args` options.
+
+### Controlling event formatting
+
+The file sink creates events in a fixed text format by default:
+
+```
+2018-07-06 09:02:17.148 +10:00 [INF] HTTP GET / responded 200 in 1994 ms
+```
+
+The format is controlled using an _output template_, which the file configuration method accepts as an `outputTemplate` parameter.
+
+The default format above corresponds to an output template like:
+
+```csharp
+    .WriteTo.File("log.txt",
+        outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{u3}] {Message:lj}{NewLine}{Exception}")
+```
+
+##### JSON event formatting
+
+To write events to the file in an alternative format such as JSON, pass an `ITextFormatter` as the first argument:
+
+```csharp
+    .WriteTo.File(new JsonFormatter(), "log.txt")
+```
 
 ### Shared log files
 
-Multiple processes can concurrently write to the same log file if the `shared` parameter is set to `true`:
+To enable multi-process shared log files, set `shared` to `true`:
 
 ```csharp
     .WriteTo.File("log.txt", shared: true)
 ```
 
+### Auditing
+
+The file sink can operate as an audit file through `AuditTo`:
+
+```csharp
+    .AuditTo.File("audit.txt")
+```
+
+Only a limited subset of configuration options are currently available in this mode.
+
 ### Performance
 
 By default, the file sink will flush each event written through it to disk. To improve write performance, specifying `buffered: true` will permit the underlying stream to buffer writes.