#36977 [Opn->Csd]: Doc's for symlink are confusing

ID: 36977 Updated by: ramsey@php.net Reported By: mpb dot mail at gmail dot com -Status: Open +Status: Closed Bug Type: Documentation problem PHP Version: Irrelevant -Assigned To: +Assigned To: ramsey New Comment: My symlink man page says: int symlink(const char *name1, const char *name2); A symbolic link name2 is created to name1 The order of the parameters doesn't necessarily have to dictate the order in which they appear in a sentence describing them, as we can see from above. However, rewording the sentence as it is in the PHP manual is unnecessary. Simply changing the word "from" to "to" will add sufficient clarity, so that is what I have done. Previous Comments: ------------------------------------------------------------------------ [2006-04-05 16:40:39] mpb dot mail at gmail dot com vrana@php.net Closed this bug saying: "Current wording follows parameters order." Respectfully: 1) At the very least, the word "from" should be changed to the word "to". 2) If the parameter names were listed in column 1 of a table, with descriptions in column 2, then I agree that they should be listed in order. 3) However, as the description of the parameters is a single English sentence, I believe that sentence should be written for clarity. 4) The symlink man pages on both Linux and FreeBSD list the parameters in reverse order, and are both much clearer than the PHP docs. I prefer the Linux version. Linux: int symlink(const char *oldpath, const char *newpath); symlink() creates a symbolic link named newpath which contains the string oldpath. FreeBSD: int symlink(const char *name1, const char *name2); A symbolic link name2 is created to name1 (name2 is the name of the file created, name1 is the string used in creating the symbolic link). I will not reopen this bug again. Thank you! ------------------------------------------------------------------------ [2006-04-05 16:14:49] vrana@php.net Current wording follows parameters order. ------------------------------------------------------------------------ [2006-04-04 21:49:36] mpb dot mail at gmail dot com Description: ------------ On this page: http://us2.php.net/manual/en/function.symlink.php I get confused every time a read the following sentence: "symlink() creates a symbolic link from the existing target with the specified name link." In my opinion, "from" is the wrong direction. Would it not be clearer to say: "symlink() creates a symbolic link named link that points to target. Typically, target is a file or directory that already exists." ------------------------------------------------------------------------ -- Edit this bug report at http://bugs.php.net/?id=36977&edit=1