bootstrap-vue
diff --git a/‎src/components/table/README.md
Lines changed: 68 additions & 32 deletions b/‎src/components/table/README.md
Lines changed: 68 additions & 32 deletions
@@ -273,7 +273,9 @@ The following field properties are recognized:
 | Property | Type | Description
 | ---------| ---- | -----------
 | `key` | String | The key for selecting data from the record in the items array. Required when setting the `fields` from as an array of objects.
-| `label` | String | Appears in the columns table header (and footer if `foot-clone` is set). Defaults to the field's key (in humanized format) if not provided. It's possible to use empty labels by assigning an empty string `""`
+| `label` | String | Appears in the columns table header (and footer if `foot-clone` is set). Defaults to the field's key (in humanized format) if not provided. It's possible to use empty labels by assigning an empty string `""` but be sure you also set `headerTitle` to provide non-sighted users a hint about the column contents.
+| `headerTitle` | Text to place on the fields header `<th>` attribute `title`. Defaults to no `title` attribute.
+| `headerAbbr` | Text to place on the fields header `<th>` attribute `abbr`. Set this to the unabbreviated version of the label (or title) if label (or title) is an abbreviation. Defaults to no `abbr` attribute.
 | `class` | String or Array | Class name (or array of class names) to add to `<th>` **and** `<td>` in the column.
 | `formatter` | String or Function | A formatter callback function, can be used instead of (or in conjunction with) slots for real table fields (i.e. fields, that have corresponding data at items array). Refer to [**Custom Data Rendering**](#custom-data-rendering) for more details.
 | `sortable` | Boolean | Enable sorting on this column. Refer to the [**Sorting**](#sorting) Section for more details.
@@ -486,9 +488,8 @@ export default {
 <!-- table-responsive.vue -->
 ```
 
->**Responsive table notes:**
-> - _Possible vertical clipping/truncation_. Responsive tables make use of `overflow-y: hidden`, which clips off any content that goes beyond the bottom or top edges of the table. In particular, this can clip off dropdown menus and other third-party widgets.
-> - When in responsive mode the table will lose it's width of 100%. This is a known issue with bootstrap V4 css and placing the `table-responsive` class on the `<table>` element as recommended by Bootstrap.
+**Responsive table notes:**
+- _Possible vertical clipping/truncation_. Responsive tables make use of `overflow-y: hidden`, which clips off any content that goes beyond the bottom or top edges of the table. In particular, this may clip off dropdown menus and other third-party widgets.
 
 
 ## Stacked tables
@@ -680,12 +681,12 @@ The slot's scope variable (`data` in the above sample) will have the following p
 | `toggleDetails` | Function | Can be called to toggle the visibility of the rows `row-details` scoped slot. See section [**Row details support**](#row-details-support) below for additional information
 
 
->**Notes:**
->- _`index` will not always be the actual row's index number, as it is
+**Notes:**
+- _`index` will not always be the actual row's index number, as it is
 computed after pagination and filtering have been applied to the original
 table data. The `index` value will refer to the **displayed row number**. This
 number will align with the indexes from the optional `v-model` bound variable._
->- _When placing inputs, buttons, selects or links within a data cell scoped slot,
+- _When placing inputs, buttons, selects or links within a data cell scoped slot,
 be sure to add a `@click.stop` (or `@click.native.stop` if needed) handler (which can
 be empty) to prevent the click on the input, button, select, or link, from triggering
 the `row-clicked` event:_ 
@@ -698,8 +699,8 @@ the `row-clicked` event:_
 ```
 
 #### Displaying raw HTML
-By default `b-table` escapes HTML tags in items, if you need to display raw HTML code in `b-table`, you should use 
-`v-html` directive on an element in a in scoped field slot
+By default `b-table` escapes HTML tags in items data and results of formatter functions, if you need to display
+raw HTML code in `b-table`, you should use `v-html` directive on an element in a in scoped field slot
 
 ```html
 <template>
@@ -727,8 +728,8 @@ export default {
 <!-- table-html-data-slots.vue -->
 ```
 
-**Note:** Be  cautious of using this to display user supplied content, as script
-tags could be injected into your page!
+**Warning:** Be cautious of using this to display user supplied content, **as script
+tags could be injected into your page!**
 
 
 ### Formatter callback
@@ -952,7 +953,7 @@ based on the current sort critera. See the
 [Vue docs](http://vuejs.org/v2/guide/components.html#sync-Modifier) for details
 on the `.sync` prop modifier
 
->**Note:** _The built-in `sort-compare` routine **cannot** sort virtual columns, nor
+**Note:** _The built-in `sort-compare` routine **cannot** sort virtual columns, nor
 sort based on the custom rendering of the field data (formatter functions and/or
 scoped slots are used only for presentation only, and do not affect the underlying data).
 Refer to the [**Sort-compare routine**](#sort-compare-routine) section below for details on
@@ -1054,7 +1055,8 @@ function toString (value) {
 ### Disable local sorting
 If you want to handle sorting entirely in your app, you can disable the local
 sorting in `<b-table>` by setting the prop `no-local-sorting` to true, while
-still maintaining the sortable header functionality.
+still maintaining the sortable header functionality (via `sort-changed` or
+`context-changed` events as well as syncable props).
 
 You can use the syncable props `sort-by.sync` and `sort-desc.sync` to detect
 changes in sorting column and direction.
@@ -1079,20 +1081,50 @@ See the [Complete Example](#complete-example) below for an example of using this
 
 ## Filtering
 Filtering, when used, is applied to the **original items** array data, and hence it is not
-possible to filter data based on custom rendering of virtual columns. The items row data
-is stringified and the filter searches that stringified data (excluding any properties
-that begin with an underscore `_`).
+currently possible to filter data based on custom rendering of virtual columns.
+
+### Built in filtering
+The items row data values are stringified (see the sorting section above for how
+stringification is done) and the filter searches that stringified data (excluding 
+any of the special properties that begin with an underscore `_`). The stringification
+also includes any data not shown in the presented columns.
+
+With the default built-in filter function, The `filter` prop value can either be a string or
+a `RegExp` object (regular expressions should _not_ have the `/g` global flag set).
+
+If the stringified row contains the provided string value or matches the RegExp expression
+then it is inclded in the displayed results.
+
+Set the `filter` prop to `null` or the empty string to clear the current filter.
+
+### Custom filter function
+You can also use a custom filter function, by setting the prop `filter-function` to a
+reference of custom filter test function. The filter function will be passed two arguments:
+- the original item row record data object. **Treat this argument as read-only.**
+- the content of the `filter` prop (could be a string, RegExp, array, or object)
+
+The function should return `true` if the record matches your criteria or `false` if
+the record is to be filtered out. 
 
-The `filter` prop value can be a string, a `RegExp` or a `function` reference. If
-a function is provided, the first argument is the original item record data object. The
-function should return `true` if the record matches your criteria or `false` if
-the record is to be filtered out.
+For proper reactive updates to the displayed data, when not filtering you should set the
+`filter` prop to `null` or an emtpy string (and not an empty object or array).
+The filter function will not be called when the `fitler` prop is a falsey value.
 
+The display of the `empty-filter-text` relies on the truthyness of the `filter` prop.
+
+**Deprecation Notice:** Passing a filter function via the `filter` prop is deprecated
+and should be avoided. Use the `filter-function` prop instead.
+
+### Filter events
 When local filtering is applied, and the resultant number of items change, `<b-table>`
-will emit the `filtered` event, passing a single argument which is the complete list of
-items passing the filter routine. **Treat this argument as read-only.**
+will emit the `filtered` event with a two arguments:
+- an array reference which is the complete list of items passing the filter routine. **Treat this argument as read-only.**
+- the number of records that passed the filter test (the length of the first argument)
 
-Setting the prop `filter` to null or an empty string will disable local items filtering.
+Setting the prop `filter` to null or an empty string will clear local items filtering.
+
+### Filtering notes
+You can disable local filtering competely by setting the `no-local-filtering` prop to `true`.
 
 See the [Complete Example](#complete-example) below for an example of using the
 `filter` feature.
@@ -1121,7 +1153,7 @@ the original `items` array (except when `items` is set to a provider function).
 Deleting a record from the v-model will **not** remove the record from the
 original items array.
 
->**Note:** _Do not bind any value directly to the `value` prop. Use the `v-model` binding._
+**Note:** _Do not bind any value directly to the `value` prop. Use the `v-model` binding._
 
 
 ## Using Items Provider Functions
@@ -1144,6 +1176,7 @@ following five properties:
 | `filter` | String or RegExp or Function | the value of the `Filter` prop
 | `sortBy` | String | The current column key being sorted, or `null` if not sorting
 | `sortDesc` | Boolean | The current sort direction (`true` for descending, `false` for ascending)
+| `apiUrl` | String | the value providedd to the `api-url` prop. `null` if none provided.
 
 The second argument `callback` is an optional parameter for when using the callback asynchronous method.
 
@@ -1197,7 +1230,7 @@ function myProvider (ctx) {
 a `busy` prop that can be used either to override inner `busy`state, or to monitor
 `<b-table>`'s current busy state in your application using the 2-way `.sync` modifier.
 
->**Note:** _in order to allow `<b-table>` fully track it's `busy` state, custom items
+**Note:** _in order to allow `<b-table>` fully track it's `busy` state, custom items
 provider function should handle errors from data sources and return an empty
 array to `<b-table>`._
 
@@ -1236,10 +1269,10 @@ methods: {
 }
 ```
 
->**Notes:**
->- _If you manually place the table in the `busy` state, the items provider will
+**Notes:**
+- _If you manually place the table in the `busy` state, the items provider will
 __not__ be called/refreshed until the `busy` state has been set to `false`._
->- _All click related and hover events, and sort-changed events will __not__ be
+- _All click related and hover events, and sort-changed events will __not__ be
  emitted when in the `busy` state (either set automatically during provider update,
  or when manually set)._
 
@@ -1259,12 +1292,12 @@ following `b-table` prop(s) to `true`:
 When `no-provider-paging` is `false` (default), you should only return at
 maximum, `perPage` number of records.
 
->**Notes:**
->- _`<b-table>` needs reference to your pagination and filtering values in order to
+**Notes:**
+- _`<b-table>` needs reference to your pagination and filtering values in order to
 trigger the calling of the provider function. So be sure to bind to the `per-page`,
 `current-page` and `filter` props on `b-table` to trigger the provider update function call
 (unless you have the respective `no-provider-*` prop set to `true`)._
->- _The `no-local-sorting` prop has no effect when `items` is a provider function._
+- _The `no-local-sorting` prop has no effect when `items` is a provider function._
 
 ### Event based refreshing of data
 You may also trigger the refresh of the provider function by emitting the
@@ -1283,7 +1316,8 @@ Or by calling the refresh method on the table reference
     this.$refs.table.refresh();
 ```
 
-These refresh event/methods are only applicable when `items` is a provider function.
+**Note:** If the table is in the `busy` state, refresh event/methods will silently be ignored.
+
 
 ### Detection of sorting change
 By listening on `<b-table>` `sort-changed` event, you can detect when the sorting key
@@ -1318,6 +1352,8 @@ Special care must be taken when using server side rendering (SSR) and an `items`
 function. Make sure you handle any special situations that may be needed server side
 when fetching your data!
 
+When `b-table` is mounted in the document, it will automatically trigger a provider update call.
+
 
 ## Complete Example