[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Bug-tar] Manual should normally use Long or Short form for operations a

From: Sam Kuper
Subject: [Bug-tar] Manual should normally use Long or Short form for operations and options, not Old form
Date: Thu, 26 May 2011 06:59:57 +0100

Dear GNU tar maintainers,

In the manual, at
http://www.gnu.org/software/tar/manual/tar.html#SEC11 , I read the
following: "In the examples and in the text of this tutorial, we
usually use the long forms of operations and options; but the “short”
forms produce the same result and can make typing long tar commands

This is a reasonable approach. I also think it is right that in that
same section the following is, additionally, present: "In this book we
present a full discussion of this way of writing options and
operations (see section Old Option Style), and we discuss the other
two styles of writing options (See section Long Option Style, and see
section Short Option Style)."

As a reader of the manual, my impression from that section is that:

- In the section headed "Old Option Style", I will find an explanation
of why the Old form exists, and when and how to use it;
- In all other sections of the manual, I will encounter only the Long
form and the Short form.

I wish the manual would conform to these expectations, but
unfortunately it doesn't.

(For example, see
http://www.gnu.org/software/tar/manual/tar.html#SEC132 , which uses
the Old form.)

Until it does, I expect I will find that the traffic to my blog post
http://www.sampablokuper.com/2009/01/03/tar-cannot-stat/ remains
considerable, which obviously represents a less than ideal state of
affairs from a usability standpoint re: tar. It is clear from the
comments on my blog post that the manual as it stands is not
adequately clear (unless, perhaps, if it is read all the way through):
if a reader skips straight to SEC132, for instance, s/he will miss the
explanation that the Short and Old forms are different, and will be
puzzled if s/he attempts to apply the options shown there, but with
what s/he believes to be an entirely reasonable, conventional and
functionally insignificant addition of a hyphen prepended to them.

Best regards,

Sam Kuper

reply via email to

[Prev in Thread] Current Thread [Next in Thread]