Bug 47818
| Summary: | [patch] ln(1) manpage is confusing | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Gary W. Swearingen <swear> | ||||
| Component: | Books & Articles | Assignee: | Tom Rhodes <trhodes> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | CC: | keramida | ||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
[-- adding to audit trail --] : Message-Id: <20030204010131.GA2267@gothmog.gr> : Date: Tue, 4 Feb 2003 03:01:31 +0200 : From: Giorgos Keramidas <keramida@freebsd.org> : : On 2003-02-02 12:31, "Gary W. Swearingen" <swear@attbi.com> wrote: : > >Originator: Gary W. Swearingen : > >Synopsis: ln(1) manpage is confusing : > >Category: docs : > >Release: FreeBSD 4.7-STABLE i386 : > >Environment: n/a : > >Description: : : This sort of change applies equally to 5.X and 4.X (or older) : versions. I still remember the thread in -doc. Thanks for : reminding me about it Gary, because I `lost' it in the rest of : the doc PRs. : : > The "ln" manual is confusing. This was cause for a recent -questions : > thread on the subject where that sentiment was confirmed by several : > people. Here are some problems: : > 1) Many newbies aren't familiar with its use of "target", or even with : > the more common use of the term. : : I don't like the to_filename and from_filename names either though :( : : I would probably prefer the names: : : newlink for the hard or symbolic link file name : file for any existing files : : the difference in names makes it pretty clear which one is which, and : if you still have doubts if the reader will grasp the difference of : the two 'file' names, we can explicitly write in the text of the : manpage the fact that 'file ...' refers to existing files, while : 'newlink' refers to the files created by ln(1). : : Deciding what to call the two arguments of ln(1) is not an easy task. : I have thought a lot about it before replying. It is imperative we : find a good way to name them though, as this will also fix a lot of : the wrongs you have (rightfully) pointed out. : : > 9) The last sentence of the first paragraph is more noise than help. : : Perhaps, if we expanded the difference a bit with the following? : : How a link : .Dq points : to a file is one of the differences between a hard and symbolic link. : + Hard links are effectively different names for the same set of : + disk blocks. : + Removing one of the hard links of a file does not free the : + space of the rest of the hard links and return the disk space : + occupied by the file to the pool of free space on the disk. : + Symbolic links (also known as : + .Dq symlinks ) : + point to a specific file name. : + If you remove the file that a symbolic link points to, the : + disk space occupied by the file is freed to. : + The symbolic link continues to point to a file that no longer : + exists. : + It is then called a : + .Dq broken : + symbolic link. : : Does this look better than deleting the line? : : > 11) The beginning of the description doesn't mention the "link" command. : : This needs fixing. I agree. But isn't the paragraph near the end of : description good enough already? : : When the utility is called as link, exactly two arguments must be : supplied, neither of which may specify a directory. No options : may be supplied in this simple mode of operation, which performs : a link(2) operation using the two passed arguments. : : - Giorgos State Changed From-To: open->feedback keramida has suggested changes and asks for comment. Giorgos Keramidas <keramida@freebsd.org> writes: > I don't like the to_filename and from_filename names either though :( > > I would probably prefer the names: > > newlink for the hard or symbolic link file name > file for any existing files > I find "ln to_filename from_filename" ("link to filename from filename") has a really nice, rememberable ring to it. I reviewed the old thread and it's several suggestions and can find things wrong with all of them including a couple of my previous ideas. "link", "from_link", or "newlink" as the last argument isn't bad and I guess I wouldn't complain real loud about it, but the less we imply that a hard link is a link like a symlink, instead of just another filename entry in a directory, the better. I think "from_filename" is more generic and fits both soft and hard link cases better. If you really don't like "from_filename", how about "from_link" (or "from_newlink")? (I don't like the "new" part because it makes me want to go looking for the old link.) I don't like "file" even more. As you said before, that argument doesn't have to refer to a file. It can be just a filename string for the symlink's directory entry. More in next para.. > the difference in names makes it pretty clear which one is which, and > if you still have doubts if the reader will grasp the difference of > the two 'file' names, we can explicitly write in the text of the > manpage the fact that 'file ...' refers to existing files, while > 'newlink' refers to the files created by ln(1). The "difference in names" is too great in the case of a hard link. It makes it seem that a "file" and a "newlink" are very different things, when they are essentially identical, but maybe that's really more a problem with "newlink". The new manpage already explains what the arguments refer to, but I guess you can replace it to work better with any new arugment names. > Deciding what to call the two arguments of ln(1) is not an easy task. > I have thought a lot about it before replying. It is imperative we > find a good way to name them though, as this will also fix a lot of > the wrongs you have (rightfully) pointed out. Agreed. I must admit that your argument names run second-best of the candidates I've seen so far, and I'm no-doubt biased by having lived with mine for many hours, so I can live with yours, if you still want them after thinking about it again. (Maybe dropping "new"?) > Perhaps, if we expanded the difference a bit with the following? ... > to a file is one of the differences between a hard and symbolic link. > + Hard links are effectively different names for the same set of > + disk blocks. > + Removing one of the hard links of a file does not free the > + space of the rest of the hard links and return the disk space > + occupied by the file to the pool of free space on the disk. > + Symbolic links (also known as > + .Dq symlinks ) > + point to a specific file name. > + If you remove the file that a symbolic link points to, the > + disk space occupied by the file is freed to. > + The symbolic link continues to point to a file that no longer > + exists. > + It is then called a > + .Dq broken > + symbolic link. > > Does this look better than deleting the line? Worse, methinks. That sort of thing doesn't belong in the introductory paragraph(s). I think I covered that well enough in the descriptions of hardlinks and softlinks after the option descriptions. And I see no need to mention disk blocks at all; it's an implementation detail, which belongs outside the "DESCRIPTION" section, if anywhere. > > 11) The beginning of the description doesn't mention the "link" command. > > This needs fixing. I agree. But isn't the paragraph near the end of > description good enough already? I think not; the first paragraph(s) should introduce the manpage's commands, and an introduction is all that the command requires. Also, the paragraph you quote is wrong about specifying a directory. It also has an unnecessary implementation detail (which I moved to "NOTES" and generalized to all hard links, not just link(1)'s links). State Changed From-To: feedback->open Feedback is in the audit trail of this PR since a long time now. State Changed From-To: open->patched Patch committed which cleans up the language of the manual page and improves the .Nd line. The "source/target" part remains as it is also used by other manual pages such as mv(1) and cp(1). Thanks! Responsible Changed From-To: freebsd-doc->trhodes Over to me, MFC reminder. Author: trhodes Date: Tue Jan 13 15:24:35 2009 New Revision: 187148 URL: http://svn.freebsd.org/changeset/base/187148 Log: Clean up a bit of confusing language and improve .Nd. PR: 47818 Reviewed by: keramida Modified: head/bin/ln/ln.1 Modified: head/bin/ln/ln.1 ============================================================================== --- head/bin/ln/ln.1 Tue Jan 13 13:19:42 2009 (r187147) +++ head/bin/ln/ln.1 Tue Jan 13 15:24:35 2009 (r187148) @@ -38,7 +38,7 @@ .Sh NAME .Nm ln , .Nm link -.Nd make links +.Nd link files .Sh SYNOPSIS .Nm .Op Fl s Op Fl F @@ -57,8 +57,13 @@ .Sh DESCRIPTION The .Nm -utility creates a new directory entry (linked file) which has the -same modes as the original file. +utility creates a new directory entry (linked file) for the file name +specified by +.Ar target_file . +The +.Ar target_file +will be created with the same file modes as the +.Ar source_file . It is useful for maintaining multiple copies of a file in many places at once without using up storage for the .Dq copies ; @@ -148,7 +153,7 @@ links. A hard link to a file is indistinguishable from the original directory entry; any changes to a file are effectively independent of the name used to reference the file. -Hard links may not normally refer to directories and may not span file systems. +Directories may not be hardlinked, and hard links may not span file systems. .Pp A symbolic link contains the name of the file to which it is linked. _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" Author: keramida (doc committer) Date: Fri Jan 23 12:01:24 2009 New Revision: 187630 URL: http://svn.freebsd.org/changeset/base/187630 Log: MFC 187148 from /head Clean up a bit of confusing language and improve .Nd. PR: 47818 Modified: stable/7/bin/ln/ (props changed) stable/7/bin/ln/ln.1 Modified: stable/7/bin/ln/ln.1 ============================================================================== --- stable/7/bin/ln/ln.1 Fri Jan 23 11:58:24 2009 (r187629) +++ stable/7/bin/ln/ln.1 Fri Jan 23 12:01:24 2009 (r187630) @@ -38,7 +38,7 @@ .Sh NAME .Nm ln , .Nm link -.Nd make links +.Nd link files .Sh SYNOPSIS .Nm .Op Fl s Op Fl F @@ -57,8 +57,13 @@ .Sh DESCRIPTION The .Nm -utility creates a new directory entry (linked file) which has the -same modes as the original file. +utility creates a new directory entry (linked file) for the file name +specified by +.Ar target_file . +The +.Ar target_file +will be created with the same file modes as the +.Ar source_file . It is useful for maintaining multiple copies of a file in many places at once without using up storage for the .Dq copies ; @@ -148,7 +153,7 @@ links. A hard link to a file is indistinguishable from the original directory entry; any changes to a file are effectively independent of the name used to reference the file. -Hard links may not normally refer to directories and may not span file systems. +Directories may not be hardlinked, and hard links may not span file systems. .Pp A symbolic link contains the name of the file to which it is linked. _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" State Changed From-To: patched->closed Patch is in HEAD, 8.x and 7.x. 6.x went EoL. |
The "ln" manual is confusing. This was cause for a recent -questions thread on the subject where that sentiment was confirmed by several people. Here are some problems: 1) Many newbies aren't familiar with its use of "target", or even with the more common use of the term. 2) The "ls -l" output shows an arrow coming out of the "target" instead of the more natural direction. This is not a problem with "ls", but a problem with "ln" misnaming the argument. 3) The other argument is called "target" by code within the "ln" program itself and by POSIX docs. 4) It's not intuitive that the "source" should be the source of the link (ie, the source of the "arrow") or the source of data when the linked file is accessed -- opposite senses. Better not use the term. 5) The seemingly arbitrary assignment of the terms "source file" and "target file" to the arguments makes their order hard to remember. 6) The order of the two arguments is opposite from their order when output by "ls -l". This is not necessarily bad, but it makes things harder to remember and makes it important that the manual help readers remember the correct order. Good terms and naming is important. 7) The "ls -l" command shows an arrow coming out of the "target", using the old ln(1)'s jargon. Arrows should go into targets. Better yet, keep them in their quiver. (I.e, don't use the esoteric term.) 8) The "apropos" string in the "Name" section doesn't contain the terms "symbolic", "soft", "hard", or the same followed by "link", all of which are likely to be searched for by apropos(1) users. 9) The last sentence of the first paragraph is more noise than help. 10) The -h description is a little confusing about how a "target_file" can point to a directory or how such a link could be followed by ln. 11) The beginning of the description doesn't mention the "link" command. 12) The descriptions could be better organized and otherwise improved. ================ Fix: ========================= 1) The names of the command arguments (eg, in the synopsis) are changed to make clear what purpose the arguments serve and to make the command read naturally as a command to the system. ln to_filename from_filename That is, "link to [first] file from [second] file". Of course, with -s, to_filename can be any string and need not refer to a file, but that is a detail better left for the description instead of using an esoteric term like "target" to refer also to an existing filename (without -s). The terms seem less arbitrary than the ln(1)-peculiar meanings of "source" and "target", and are thus more easily remembered. Note that during discussion, it seemed clear to me that any arugment name which contained some form of the word "link" (as then proposed by me and others) caused problems for some people. The proposed names leave the word only in the command name where it is unconfusing. 2) The new synopsis looks like this: ln [-fhinsv] to_filename {... directory_name | [from_filename]} link to_filename {directory_name | from_filename} Note that "filename" is used in the synopses because the argument specifies a filename, but not necessarily a file; with -s, the filename need not refer to a file; if may refer to a directory or to nothing. 3) The description section's use of "source file" and "target file" very-much echo the names of the arguments and so they are easily replaced by new terms, "to filename" and "from filename". 4) Separating the hard and soft link cases was considered, but having five synopsis lines and using more specific argument names (which has its benefits), looked messy/confusing/redundant and gave too much to decypher and think about. 5) Some other descriptions are reworked to improve clarity. Preview results of this patch with something like this: zcat /usr/share/man/man1/ln.1.gz >/tmp/ln.1 patch -s /tmp/ln.1 <this message> groff -mandoc -Tascii /tmp/ln.1 | less Patch this: [.\" $FreeBSD: src/bin/ln/ln.1,v 1.11.2.7 2002/08/19 08:14:22 tjr Exp $] with this: How-To-Repeat: n/a ================