merge_ordered documentation invokes a different function, and output is not correct
The documentation for `pandas.merge_ordered` at https://pandas.pydata.org/pandas-docs/stable/generated/pandas.merge_ordered.html#pandas.merge_ordered presents an example in which the output is not consistent with the input.

In addition, the example for `merge_ordered` invokes `ordered_merge`, which is a deprecated function.

#### Code Sample

This code shows the actual output for the dataframes `A` and `B` listed in the example.

```
In [1]: import pandas

In [4]: A = pandas.DataFrame({'key': list('aceace'), 'lvalue': [1, 2, 3, 1, 2, 3], 'group': list('aaabbb')})[['key', 'lvalue', 'group']]

In [5]: A
Out[5]:
  key  lvalue group
0   a       1     a
1   c       2     a
2   e       3     a
3   a       1     b
4   c       2     b
5   e       3     b

In [7]: B = pandas.DataFrame({'key': list('bcd'), 'rvalue': [1, 2, 3]})[['key', 'rvalue']]

In [8]: B
Out[8]:
  key  rvalue
0   b       1
1   c       2
2   d       3

In [9]: pandas.ordered_merge(A, B, fill_method='ffill', left_by='group')
C:\hbkbin\conda\envs\066980e5e5f1fb391717e0339739d2c9\Scripts\ipython-script.py:1: FutureWarning: ordered_merge is deprecated and replaced by merge_ordered
  if __name__ == '__main__':
Out[9]:
  key  lvalue group  rvalue
0   a       1     a     NaN
1   b       1     a     1.0
2   c       2     a     2.0
3   d       2     a     3.0
4   e       3     a     3.0
5   a       1     b     NaN
6   b       1     b     1.0
7   c       2     b     2.0
8   d       2     b     3.0
9   e       3     b     3.0

In [10]: pandas.merge_ordered(A, B, fill_method='ffill', left_by='group')
Out[10]:
  key  lvalue group  rvalue
0   a       1     a     NaN
1   b       1     a     1.0
2   c       2     a     2.0
3   d       2     a     3.0
4   e       3     a     3.0
5   a       1     b     NaN
6   b       1     b     1.0
7   c       2     b     2.0
8   d       2     b     3.0
9   e       3     b     3.0
```

#### Problem description

Here is the output shown in the documentation:
```
>>> ordered_merge(A, B, fill_method='ffill', left_by='group')
   key  lvalue group  rvalue
0    a       1     a     NaN
1    b       1     a       1
2    c       2     a       2
3    d       2     a       3
4    e       3     a       3
5    f       3     a       4
6    a       1     b     NaN
7    b       1     b       1
8    c       2     b       2
9    d       2     b       3
10   e       3     b       3
11   f       3     b       4
```

Note that the rows with `key` equal to `f` and `rvalue` equal to 4 are not present in the actual pandas output; those rows might be from an old version of the example.

#### Expected Output

The contents of an example are expected to be consistent with actual output from pandas, which is listed above.

#### Output of ``pd.show_versions()``

<details>

[paste the output of ``pd.show_versions()`` here below this line]
INSTALLED VERSIONS
------------------
commit: None
python: 3.4.5.final.0
python-bits: 64
OS: Windows
OS-release: 7
machine: AMD64
processor: Intel64 Family 6 Model 79 Stepping 1, GenuineIntel
byteorder: little
LC_ALL: None
LANG: en_US.UTF-8
LOCALE: None.None

pandas: 0.19.1
nose: 1.3.7
pip: 9.0.1
setuptools: 27.2.0
Cython: 0.24.1
numpy: 1.11.2
scipy: 0.18.1
statsmodels: 0.6.1
xarray: 0.8.2
IPython: 5.1.0
sphinx: 1.4.8
patsy: 0.4.1
dateutil: 2.6.0
pytz: 2016.7
blosc: 1.5.0
bottleneck: 1.2.0
tables: 3.2.2
numexpr: 2.6.1
matplotlib: 2.0.0
openpyxl: 2.4.0
xlrd: 1.0.0
xlwt: 1.1.2
xlsxwriter: 0.9.3
lxml: 3.6.4
bs4: 4.5.3
html5lib: 0.999
httplib2: 0.9.2
apiclient: None
sqlalchemy: 1.1.3
pymysql: None
psycopg2: 2.6.2 (dt dec pq3 ext lo64)
jinja2: 2.8
boto: 2.43.0
pandas_datareader: None

</details>
