make docs more consistant; lint markdown (#43)

README.md

@@ -7,7 +7,7 @@
 
 ![Loba is "write" in Zulu](readme/zulu.png)
 
-Easy tracing for debugging: handy methods for adding trace lines to output or Rails logs.
+Easy tracing for debugging: handy methods for adding trace lines to output (or Rails logs).
 
 (Installation is pretty much what you'd expect for a gem, but read Environment Notes below first.)
 
@@ -56,7 +56,7 @@ You can read [more detail](readme/ts.md) on this command.
 
 #### Variable or method return inspection:  `Loba.val`
 
-Inserts line to Rails.logger.debug (or to STDOUT if Rails.logger not available) showing value with method and class identification
+Writes line to STDOUT (or optionally to Rails.logger.debug if available) showing value with method and class identification.
 
 ```ruby
 Loba.val :var_sym   # the :var_sym argument is the variable or method name given as a symbol
@@ -107,7 +107,7 @@ The expectation is that Loba statements are just for development or test trace s
 
 `Loba.ts` and `Loba.val` try to protect against timestamp or value notice requests being accidentally left in the code by checking for the Rails environment Loba is being invoked under. If in production, `Loba.ts` and `Loba.val` will normally just return immediately without attempting to render anything to help minimize any impact on production code.
 
-However, that behavior can be overridden by using the options hash with `:production => true` as an additional last argument to output a notice even when in the production environment. Note also behavior of the `log` option which defaults to `false` (introduced in v2.0.0). In general, enabling in production should be avoided. We're consenting adults.
+However, that behavior can be overridden by using the options hash with `:production => true` as an additional last argument to output a notice even when in the production environment. Note also behavior of the `log` option which defaults to `false` (introduced in v2.0.0). In general, enabling in production should be avoided, but we're consenting adults.
 
 WARNING: this gem depends on the [binding_of_caller gem](https://rubygems.org/gems/binding_of_caller) -- use `:production => true` with their warning in mind:
 > **Recommended for use only in debugging situations. Do not use this in production apps.**

readme/ts.md

@@ -1,57 +1,66 @@
 #### Timestamp notices:  `Loba.ts`
+
 Outputs a timestamped notice, useful for quick traces to see the code path and easier than, say, [Kernel#set_trace_func](http://ruby-doc.org/core-2.2.3/Kernel.html#method-i-set_trace_func).
 Also does a simple elapsed time check since the previous timestamp notice to help with quick, minimalist profiling.
 
 For example,
 
-```
+```text
 [TIMESTAMP] #=0002, diff=93.478016, at=1451444972.970602    (in=/home/usracct/src/myapp/app/models/target.rb:55:in `some_calculation')
 ```
 
 To invoke,
 
-```
+```ruby
 Loba.ts    # no arguments
 ```
 
 `Loba.timestamp` is an alias for `Loba.ts`.
 
 The resulting notice output format is
 
-```
+```text
 [TIMESTAMP] #=nnnn, diff=ss.ssssss, at=tttttttttt.tttttt    (in=/path/to/code/somecode.rb:LL:in 'some_method')
 ```
 
 where
-*   `nnn` ("#=") is a sequential numbering (1, 2, 3, ...) of timestamp notices,
-*   `ss.ssssss` ("diff=") is number of seconds since the last timestamp notice was output (i.e., relative time),
-*   `tttttttttt.tttttt` ("at=") is Time.now (as seconds) (i.e., absolute time),
-*   `/path/to/code/somecode.rb` ("in=") is the source code file that invoked `Loba.ts`,
-*   `LL` ("in=...:") is the line number of the source code file that invoked `Loba.ts`, and
-*   `some_method` is the method in which `Loba.ts` was invoked.
+
+* `nnn` ("#=") is a sequential numbering (1, 2, 3, ...) of timestamp notices,
+* `ss.ssssss` ("diff=") is number of seconds since the last timestamp notice was output (i.e., relative time),
+* `tttttttttt.tttttt` ("at=") is Time.now (as seconds) (i.e., absolute time),
+* `/path/to/code/somecode.rb` ("in=") is the source code file that invoked `Loba.ts`,
+* `LL` ("in=...:") is the line number of the source code file that invoked `Loba.ts`, and
+* `some_method` is the method in which `Loba.ts` was invoked.
 
 ##### Options
 
 The following keyword argument may be specified when calling:
-*   `production`: true if this timestamp notice is to be enabled when running in :production environment (see ["Environment Notes"](README.md#environment-notes)) \[_default: `false`_\]
-*   `log`: `true` true if output is to be sent to both $STDOUT and to the Rails.logger (when available)
+
+* `production`: true if this timestamp notice is to be enabled when running in :production environment (see ["Environment Notes"](README.md#environment-notes)) \[_default: `false`_\]
+* `log`: `true` true if output is to be sent to both STDOUT and to the Rails.logger (when available) \[_default: `false`_\]
 
 ###### Examples using options
+
 ```ruby
 Loba.ts production: true
 ```
+
 ```ruby
 Loba.ts(production: true)
 ```
+
 ```ruby
 Loba.ts log: true
 ```
+
 ```ruby
 Loba.ts(log: true)
 ```
+
 ```ruby
 Loba.ts production: true, log: true # may result in double logging
 ```
+
 ```ruby
 Loba.ts(production: true, log: true # may result in double logging)
 ```

readme/val.md

@@ -1,32 +1,33 @@
 #### Value notices:  `Loba.val`
 
-Inserts line to Rails.logger.debug (or to STDOUT if Rails.logger not available) showing value with method and class identification
+Writes line to STDOUT (or optionally to Rails.logger.debug if available) showing value with method and class identification.
 
-```
+```ruby
 Loba.val :var_sym         # the :var_sym argument is the variable or method name given as a symbol (see below)
 ```
 
 or
 
-```
+```ruby
 Loba.val some_identifier  # directly give a variable or method name instead of a symbol (see below)
 ```
 
 or
 
-```
+```ruby
 Loba.val some_identifier, label: "My label:"  # same as direct variable, but allows a custom label
 ```
 
 Will produce a notice similar to the following:
 
-```
+```text
 [Target.some_calculation] my_var: 54       (in /home/usracct/src/myapp/app/models/target.rb:55:in `some_calculation')
 ```
 
 `Loba.value` is an alias for `Loba.val`.
 
 ###### Example 1: Using simple Symbol as argument
+
 ```ruby
 class HelloWorld
   def hello(name)
@@ -40,6 +41,7 @@ HelloWorld.new.hello("Charlie")
 ```
 
 ###### Example 2: Using more complex Symbol as argument
+
 ```ruby
 class HelloWorld
   def hello(name)
@@ -55,6 +57,7 @@ HelloWorld.new.hello("Charlie")
 ```
 
 ###### Example 3: Using a non-Symbol as argument without a label
+
 ```ruby
 class HelloWorld
   def hello(name)
@@ -68,6 +71,7 @@ HelloWorld.new.hello("Charlie")
 ```
 
 ###### Example 4: Using a non-Symbol as argument with a label
+
 ```ruby
 class HelloWorld
   def hello(name)
@@ -80,45 +84,50 @@ HelloWorld.new.hello("Charlie")
 #=> Hello, Charlie!
 ```
 
-##### Notice format:
+##### Notice format
 
 The resulting notice output format is
 
-```
+```text
 [ccccc.mmmmm] vvvvv: rrrrr         (in /path/to/code/somecode.rb:LL:in 'some_method')
 ```
 
 where
-*   `ccccc` is the name of the class from where `Loba.val` was invoked,
-*   `mmmmm` is the name of the method from where `Loba.val` was invoked,
-*   `vvvvv` is generally the name of the variable for which `Loba.val` is inspecting, or any custom label given,
-*   `rrrrr` is the result of inspecting what `Loba.val` was invoked against,
-*   `/path/to/code/somecode.rb` is the source code file that invoked `Loba.val`,
-*   `LL` is the line number of the source code file that invoked `Loba.val`, and
-*   `some_method`is the method in which `Loba.val` was invoked.
 
+* `ccccc` is the name of the class from where `Loba.val` was invoked,
+* `mmmmm` is the name of the method from where `Loba.val` was invoked,
+* `vvvvv` is generally the name of the variable for which `Loba.val` is inspecting, or any custom label given,
+* `rrrrr` is the result of inspecting what `Loba.val` was invoked against,
+* `/path/to/code/somecode.rb` is the source code file that invoked `Loba.val`,
+* `LL` is the line number of the source code file that invoked `Loba.val`, and
+* `some_method`is the method in which `Loba.val` was invoked.
 
 Notes:
-*   `ccccc`:  Ruby supports anonymous classes (e.g., `= Class.new`).  If an anonymous class, "<anonymous class>" will be output here.
-*   `mmmmm`:  Ruby supports anonymous methods, procs, and lambdas.  If an anonymous method, et al, "<anonymous method>" will be output here.
-*   `vvvvv`:  This depends on the argument being provided:  if a symbol, then this field will use that symbol to determine the name and present it here.  If not, nothing will appear for this field (and so the `label` option will be useful).
-*   `rrrrr`:  The value of the variable given to `Loba.val`. `inspect` may be used to control its behavior (see [options](#options) below).
+
+* `ccccc`:  Ruby supports anonymous classes (e.g., `= Class.new`).  If an anonymous class, "<anonymous class>" will be output here.
+* `mmmmm`:  Ruby supports anonymous methods, procs, and lambdas.  If an anonymous method, et al, "<anonymous method>" will be output here.
+* `vvvvv`:  This depends on the argument being provided:  if a symbol, then this field will use that symbol to determine the name and present it here.  If not, nothing will appear for this field (and so the `label` option will be useful).
+* `rrrrr`:  The value of the variable given to `Loba.val`. `inspect` may be used to control its behavior (see [options](#options) below).
 
 ##### Options
 
 The following options may be provided via keywords:
-*   `label`: give a string to explicitly provide a label to use in the notice (see sample above) \[_default: attempts to infer a label from the first argument]_\]
-*   `inspect`: true if this value notice is to use #inspect against the content being evaluated; occasionally, `inspect: false` can give a more useful result \[_default: `true`_\]
-*   `production`: true if this value notice is to be enabled when running in :production environment (see ["Environment Notes"](README.md#environment-notes)) \[_default: `false`_\]
-*   `log`: `true` true if output is to be sent to both $STDOUT and to the Rails.logger (when available)
+
+* `label`: give a string to explicitly provide a label to use in the notice (see sample above) \[_default: attempts to infer a label from the first argument]_\]
+* `inspect`: true if this value notice is to use #inspect against the content being evaluated; occasionally, `inspect: false` can give a more useful result \[_default: `true`_\]
+* `production`: true if this value notice is to be enabled when running in :production environment (see ["Environment Notes"](README.md#environment-notes)) \[_default: `false`_\]
+* `log`: `true` true if output is to be sent to both STDOUT and to the Rails.logger (when available) \[_default: `false`_\]
 
 ###### Example 5: Using special options
+
 ```ruby
 Loba.val name, label: "Name:", inspect: false
 ```
+
 ```ruby
 Loba.val :name, production: true
 ```
+
 ```ruby
 Loba.val :name, label: "Name:", log: true
 ```