On Mon, Jan 6, 2014 at 8:13 AM, Adam Williamson awilliam@redhat.com wrote:
On Mon, 2014-01-06 at 08:01 +0100, Lars E. Pettersson wrote:
On 01/06/2014 12:46 AM, Adam Williamson wrote:
If it exists for backward compatibility, it doesn't necessarily need to be documented.
Ehh? Why? Could you elaborate?
I don't see what needs elaborating. I'm not aware that the 11th commandment is "Every Subcommand Must Be Documented, Even Ones You Just Put In So People Still Using Syntax From The Old Tool You're Replacing Won't Have A Problem". If that's the only reason a synonym of a documented subcommand exists, what's the point of documenting it? Anyone who needs it doesn't need documentation to find it - that's the *point*, if they were going to read the documentation, they'd know the *new* subcommand - and anyone who reads the documentation doesn't stand to gain anything from learning that a subcommand has a synonym for backwards compatibility purposes. So, why go to the trouble?
To make sure the inevitable next generation of contributors (or authors of a rewrite) know not to throw the feature away, or design a new system in a way that makes the feature impossible. It doesn't necessarily need to be very emphasized, but it should be appropriately documented. Mirek