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

[Philippe Lhoste]

On 30/07/2009 17:25, Aaron Bentley wrote:
> Our see_also entries are always keywords you can look up with bzr help
> KEYWORD.  bzr help add --dry-run will not work.

Yes, I was fearing that, I felt it was useful at the Web doc level (I 
overlooked it when searching a recursive status command), but if it 
doesn't work, it should be just removed.

>> +    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.

Mmm, I understand the nuance, I wanted to stress out the "ignore" part 
as the nuance is subtle for a newbie (which I was not so long ago, and 
still am, more or less). Not sure if a better statement can be found or 
if the change should just be dropped.

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

Ah, I totally overlooked the hidden = True flag in my changes (but 
noticed it for the rocks command... :-)). Sorry for that.

> 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.

Are "see also" suggestions for equivalent commands? I thought they were 
suggestions for seeing related command that could influence behavior of 
current command or be used in similar context.

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

Mmm, my editor does that automatically, I should change this setting for 
Python files then.

-- 
Philippe Lhoste
--  (near) Paris -- France
--  http://Phi.Lho.free.fr
--  --  --  --  --  --  --  --  --  --  --  --  --  --