docs(README): Update example code and add example outputs

Author: nokome

README.md

@@ -12,7 +12,7 @@
 
 We wanted to have a unified, consistent mechanism for emitting log event data across Javascript/Typescript projects. We wanted to decouple log event emission from log event consumption. We wanted something lightweight.
 
-For example, `encoda` and `dockta` are two Typescript projects that use `logga` which we combine in the `stencila` command line tool. In the future, we'll also combine them into the `stencila` desktop Electron-based application. We want users of `encoda` and `dockta` to be able to use them as standalone tools, at the command line, and get feedback at the command line. But we also want to be able to handle log events from these packages in apps that integrate them and which may use a fancier CLI display (e.g. [Ink](https://github.com/vadimdemedes/ink)) or a HTML UI display (e.g. in Electron).
+For example, `encoda` and `dockta` are two Typescript projects that use `logga`. We want users of these projects to be able to use them as standalone tools and have log events printed at the command line. Both projects are also integrated into the `stencila` command line tool, and in the future, we'll also combine them into the `stencila` desktop Electron-based application. For each of these apps, we want to handle log events from both packages in a consistent way and display them in a way that is appropriate for the platform e.g. HTML messages when in Electron, log files when running as a server.
 
 ## Approach
 
@@ -26,31 +26,41 @@ npm install --save @stencila/logga
 
 ## Usage
 
-Create a new logger by calling `getLogger` with a unique tag to identify your app and/or module. Then emit log events using the `debug`, `info`, `warn` or `error` function (you can pass them a message string or a `LogInfo` object).
+Create a new logger by calling `getLogger` with a unique tag to identify your app and/or module. Then emit log events using the `debug`, `info`, `warn` and `error` functions. You can pass them a message string or a `LogInfo` object.
 
-```ts
-import { getLogger } from '@stencila/logga'
+```js
+const { getLogger } = require('@stencila/logga')
 
-const logger = getLogger('app:module')
+const log = getLogger('example')
 
-function doSomething() {
-  logger.debug('A debug message')
+log.debug('This is line five.')
+log.info('Everything is just fine.')
+log.warn('Oh, oh, not no much.')
+log.error('Aaargh, an error!')
 
-  try {
-    // ...
-  } catch (error) {
-    const { message, stack } = error
-    logger.error({
-      message: 'Woaaah something bad happened! ' + message,
-      stack
-    })
-  }
+try {
+  throw new Error('I am an error object.')
+} catch (error) {
+  const { message, stack } = error
+  log.error({
+    message: 'Woaaah something bad happened! ' + message,
+    stack
+  })
 }
 ```
 
-The default log handler prints log data to `stderr`:
+The default log handler prints log data to `stderr`. If `stderr` is TTY log data is formatted for human consumption with emoji, colours and stack trace (for errors):
 
-- with emoji, colours and stack trace (for errors) if `stderr` is TTY (for human consumption)
-- as JSON, with a time stamp, if `stderr` is not TTY (for machine consumption e.g. log files)
+![](screenshot.png)
 
-You can register a new handler by calling `addHandler` with a handling function. Or use `replaceHandlers` to replace any existing log handlers (including the default) with your custom handler.
+If `stderr` is not TTY log data os formatted for machine consumption (e.g. for log files) as [ndjson](http://ndjson.org/), with a time stamp, if `stderr` (for machine consumption e.g. log files):
+
+```json
+{"time":"2019-07-02T21:19:24.872Z","tag":"example","level":3,"message":"This is line five.","stack":"Error\n    at Object.<anonymous> (/home/nokome/stencila/source/logga/example.js:21:5)\n    at Module._compile (internal/modules/cjs/loader.js:689:30)\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)\n    at Module.load (internal/modules/cjs/loader.js:599:32)\n    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)\n    at Function.Module._load (internal/modules/cjs/loader.js:530:3)\n    at Function.Module.runMain (internal/modules/cjs/loader.js:742:12)\n    at startup (internal/bootstrap/node.js:266:19)"}
+{"time":"2019-07-02T21:19:24.875Z","tag":"example","level":2,"message":"Everything is just fine.","stack":"Error\n    at Object.<anonymous> (/home/nokome/stencila/source/logga/example.js:22:5)\n    at Module._compile (internal/modules/cjs/loader.js:689:30)\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)\n    at Module.load (internal/modules/cjs/loader.js:599:32)\n    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)\n    at Function.Module._load (internal/modules/cjs/loader.js:530:3)\n    at Function.Module.runMain (internal/modules/cjs/loader.js:742:12)\n    at startup (internal/bootstrap/node.js:266:19)"}
+{"time":"2019-07-02T21:19:24.875Z","tag":"example","level":1,"message":"Oh, oh, not no much.","stack":"Error\n    at Object.<anonymous> (/home/nokome/stencila/source/logga/example.js:23:5)\n    at Module._compile (internal/modules/cjs/loader.js:689:30)\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)\n    at Module.load (internal/modules/cjs/loader.js:599:32)\n    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)\n    at Function.Module._load (internal/modules/cjs/loader.js:530:3)\n    at Function.Module.runMain (internal/modules/cjs/loader.js:742:12)\n    at startup (internal/bootstrap/node.js:266:19)"}
+{"time":"2019-07-02T21:19:24.875Z","tag":"example","level":0,"message":"Aaargh, an error!","stack":"Error\n    at Object.<anonymous> (/home/nokome/stencila/source/logga/example.js:24:5)\n    at Module._compile (internal/modules/cjs/loader.js:689:30)\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)\n    at Module.load (internal/modules/cjs/loader.js:599:32)\n    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)\n    at Function.Module._load (internal/modules/cjs/loader.js:530:3)\n    at Function.Module.runMain (internal/modules/cjs/loader.js:742:12)\n    at startup (internal/bootstrap/node.js:266:19)"}
+{"time":"2019-07-02T21:19:24.875Z","tag":"example","level":0,"message":"Woaaah something bad happened! I am an error object.","stack":"Error: I am an error object.\n    at Object.<anonymous> (/home/nokome/stencila/source/logga/example.js:27:9)\n    at Module._compile (internal/modules/cjs/loader.js:689:30)\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)\n    at Module.load (internal/modules/cjs/loader.js:599:32)\n    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)\n    at Function.Module._load (internal/modules/cjs/loader.js:530:3)\n    at Function.Module.runMain (internal/modules/cjs/loader.js:742:12)\n    at startup (internal/bootstrap/node.js:266:19)\n    at bootstrapNodeJSCore (internal/bootstrap/node.js:596:3)"}
+```
+
+You can register a new handler by calling `addHandler` with a handling function. Or use `replaceHandlers` to replace any existing log handlers (including the default).

example.js

@@ -0,0 +1,34 @@
+/**
+ * Example usage to generate example outputs.
+ *
+ * For pretty output run using,
+ *
+ * ```bash
+ * node example.js
+ * ```
+ *
+ * For machine readable output run using,
+ *
+ * ```bash
+ * node example.js 2> log.json
+ * ```
+ */
+
+const { getLogger } = require('./dist')
+
+const log = getLogger('example')
+
+log.debug('This is line five.')
+log.info('Everything is just fine.')
+log.warn('Oh, oh, not no much.')
+log.error('Aaargh, an error!')
+
+try {
+  throw new Error('I am an error object.')
+} catch (error) {
+  const { message, stack } = error
+  log.error({
+    message: 'Woaaah something bad happened! ' + message,
+    stack
+  })
+}