added wrap mode detect via line sampling; now ignores wm

README.markdown

@@ -16,9 +16,9 @@ smooth the path to writing prose.
 
 * For editing files in _text_, _markdown_, _textile_, and other
   prose-oriented file types
-* Agnostic on soft line wrapping _versus_ hard line breaks, supporting
+* Agnostic on soft line wrap _versus_ hard line breaks, supporting
   both
-* Auto-detects wrap mode via modeline if present
+* Auto-detects wrap mode via modeline and sampling
 * Adjusts navigation key mappings to suit the wrap mode
 * Creates undo points on common punctuation
 * When using hard line breaks, enables autoformat while inserting text
@@ -61,7 +61,7 @@ the basics of Vim._
 
 ## Configuration
 
-### Hard line breaks or soft line wrapping?
+### Hard line breaks or soft line wrap?
 
 Coders will have the most experience with the former, and writers the
 latter. But whatever your background, chances are that you must contend
@@ -82,16 +82,16 @@ augroup END
 ```
 
 In the example above, for files of type `markdown` and `textile`, this
-plugin will auto-detect the wrapping approach, with `hard` as the default.
-But for files of type `text`, it will *always* initialize with hard line 
-break mode.
+plugin will auto-detect the line wrap approach, with `hard` as the
+default. But for files of type `text`, it will *always* initialize with
+hard line break mode.
 
 ### Commands
 
 Because auto-detect might not work as intended, you can invoke a command
 to set the behavior for the current buffer:
 
-* `SoftPencil` - mode for soft line wrapping
+* `SoftPencil` - mode for soft line wrap
 * `HardPencil` - mode for hard line breaks
 * `DropPencil` - removes navigation mappings and restores buffer to global settings
 * `TogglePencil` - if off, enables with detection; if on, turns off
@@ -111,7 +111,7 @@ _This ‘autoformat’ feature affects **HardPencil** mode only._
 
 When in **HardPencil** mode, Vim’s autoformat feature will be enabled by
 default in Insert mode and can offer many of the same benefits as soft
-line wrapping. But autoformat will cause havoc when editing anything but
+line wrap. But autoformat will cause havoc when editing anything but
 paragraphs of words, such as a code block or table. In these cases you
 will need to disable it, at least temporarily, via a command:
 
@@ -198,42 +198,73 @@ a hard break. If you wish to retain the default Vim behavior, set the
 let g:pencil#cursorwrap = 1     " 0=disable, 1=enable
 ```
 
-## Auto-detection via modeline
+## Auto-detecting wrap mode
 
-Will the wrapping mode be detected accurately? Maybe. But you can improve
-its chances by giving it a hint.
+If you provided no explicit wrap mode during initialization, _pencil_ will
+attempt to automatically detect the wrap mode.
 
-At the bottom of this document is a strange code:
+It will first look for a `textwidth` (or `tw`) specified in a modeline.
+Failing that _pencil_ will then sample lines from the start of the file.
+
+### Detect via modeline
+
+Will the wrap mode be detected accurately? Maybe. But you can improve its
+chances by giving it an explicit hint.
+
+At the bottom of this document is a odd-looking code:
 
 ```
 <!-- vim: set tw=74 :-->
 ```
 
 This is a ‘modeline’ that tells Vim to run the following command upon
-loading this file into a buffer:
+loading the file into a buffer:
 
 ```vim
 :set textwidth=74
 ```
 
-That’s a strong hint to this plugin that we should assume hard line
-endings, regardless of whether or not soft wrapping is the default editing
-mode for files of type ‘markdown’.
-
-If it’s `0`, then pencil assumes you want soft line wrapping.
+That’s a strong hint to _pencil_ that it should assume hard line breaks,
+regardless of whether or not soft line wrap is the default editing mode
+for files of type ‘markdown’.
 
 ```
 <!-- vim: set tw=0 :-->
 ```
 
-For more details:
-
-```vim
-:help modeline
-```
+If textwidth is `0` as shown above, then _pencil_ assumes you want soft
+line wrap.
 
 Note that even if the modelines feature is disabled (such as for security
-reasons) the textwidth may nevertheless be set by this plugin.
+reasons) the textwidth will still be set by this plugin.
+
+### Detect via sampling
+
+If no modeline with a textwidth is found, _pencil_ will sample the initial
+lines from the file looking for excessively-long lines.
+
+There are two settings you can add to your `.vimrc` to tweak this behavior.
+
+The maximum number of lines to sample from the start of the file:
+
+```vim
+let g:pencil#softDetectSample = 10
+```
+
+Set that value to `0` to disable detection via line sampling.
+
+When the number of bytes on a sampled line per exceeds this next value,
+then _pencil_ assumes soft line wrap. 
+
+```vim
+let g:pencil#softDetectThreshold = 130
+```
+
+If no such lines found, _pencil_ falls back to the default:
+
+```vim
+let g:pencil#wrapModeDefault = 'hard'   " or 'soft'
+```
 
 ## See also
 
@@ -241,7 +272,6 @@ reasons) the textwidth may nevertheless be set by this plugin.
 * [Vim Training Class - Basic motions and commands](https://www.youtube.com/watch?v=Nim4_f5QUxA) - video tutorial by Shawn Biddle
 * [Vim for Writers](http://therandymon.com/woodnotes/vim-for-writers/vimforwriters.html) - guide to the basics geared to writers
 * [Vim-related books](http://iccf-holland.org/click5.html) - collection of books on learning Vim
-
 * [pencil at vim.org](http://www.vim.org/scripts/script.php?script_id=4824)
 
 If you like this plugin, you might like these others from the same author: