[MERGE] Small doc improvements, mostly adding See Also references

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Philippe Lhoste wrote:
>      encoding_type = 'replace'
> -    _see_also = ['diff', 'revert', 'status-flags']
> +    _see_also = ['diff', 'revert', 'status-flags', 'add --dry-run']

Our see_also entries are always keywords you can look up with bzr help
KEYWORD.  bzr help add --dry-run will not work.

>      Therefore simply saying 'bzr add' will version all files that
> -    are currently unknown.
> +    are currently unknown and not ignored.


By definition, unknown files are not ignored.  'unversioned' files are
those not tracked by bzr.  If an unversioned file is ignored, it is an
"ignored" file.  If an unversioned file is not ignored, it is an
"unknown" file.

>      """
>  
>      hidden = True
> -    _see_also = ['status', 'ls']
> +    _see_also = ['status', 'ls', 'modified']
>      takes_options = [
>              Option('null',
>                     help='Write an ascii NUL (\\0) separator '

We should not be adding "see also" references to hidden commands.
'modified' is deprecated in favour of status.

>      """List files in a tree.
>      """
>  
> -    _see_also = ['status', 'cat']
> +    _see_also = ['status', 'cat', 'added', 'modified']
>      takes_args = ['path?']
>      takes_options = [
>              'verbose',

Added is also a hidden command, deprecated in favour of status.

I think some of these associations are not strong enough to warrant
see_also inclusion.  I don't think "diff" is strongly related to "cat",
for example.  Revert is different enough from cat that I think the
suggestion of using it in place of cat is potentially harmful.

Also, smashing trailing whitespace can lead to conflicts, so we
generally discourage it.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkpxu3AACgkQ0F+nu1YWqI25cwCdGrZoa5ypSALcuw6e9MSbFL0H
Q+oAnj8+IRzDD6bg3M10oSHXulGg6i+x
=SzpW
-----END PGP SIGNATURE-----