Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask

mkdir in perldoc

by QM (Parson)
on Jan 08, 2013 at 23:00 UTC ( #1012350=perlquestion: print w/replies, xml ) Need Help??
QM has asked for the wisdom of the Perl Monks concerning the following question:

Why does perldoc use filename instead of dirname for mkdir?

Quantum Mechanics: The dreams stuff is made of

Replies are listed 'Best First'.
Re: mkdir in perldoc
by marto (Bishop) on Jan 09, 2013 at 10:16 UTC

    Everything_is_a_file, if you feel strongly about changing this consider raising the issue with the maintainers.

      Everything is a file...
      Yes, but in the documentation filename is used 2 ways, first as a standin for the wordy "file system entity", and second as an ordinary file (not a directory or somesuch). But since its use in mkdir is not the generic file system entity, it's misleading. (I'm particularly amused by rmdir's description.)

      Quantum Mechanics: The dreams stuff is made of

        The entries in mkdir and rmdir state:

        "Creates the directory specified by FILENAME"

        "Deletes the directory specified by FILENAME if that directory is empty."

        Now the Microsoft documentation states:

        "Note that a directory is simply a file with a special attribute designating it as a directory, but otherwise must follow all the same naming rules as a regular file. Because the term directory simply refers to a special type of file as far as the file system is concerned, some reference material will use the general term file to encompass both concepts of directories and data files as such."

        I don't find any of this misleading. If you do feel free to make a case to improve the documentation in question to those who maintain it.

Re: mkdir in perldoc
by blue_cowdawg (Monsignor) on Jan 09, 2013 at 14:10 UTC

    Given that (and I could be wrong here) Perl was first developed on Unix and Unix takes the view that files and directories are the same thing I'm not surprised. A directory on *nix is just a file of I-Node pointers with file names as the index key. (an oversimplified explanation I realize)

    Peter L. Berghold -- Unix Professional
    Peter -at- Berghold -dot- Net; AOL IM redcowdawg Yahoo IM: blue_cowdawg
Re: mkdir in perldoc
by jkeenan1 (Deacon) on Jan 09, 2013 at 03:20 UTC
    Good question, particularly as that differs from man 1 mkdir on both Linux and BSD. Perhaps we should ask Larry?

    a0d0e21e (Larry Wall 1994-10-17 23:00:00 +0000 1356) =item mkdir FILEN +AME,MODE

    Jim Keenan

      Perhaps we should ask Larry?

      Let's not

Re: mkdir in perldoc
by 7stud (Deacon) on Jan 09, 2013 at 10:08 UTC
    Perhaps because the names of files and directories are generically known as "filenames" in the unix world.
      Perhaps because the names of files and directories are generically known as "filenames" in the unix world.

      Not knocking you for this, but it's equivalent to Anonymous Monk's "Because", perhaps funneling into Appeal_to_tradition. But seriously, I understand, "FILENAME" here may be a generic term for any named filesystem entry, whether it's a file, link, directory, device, pipe, etc. But mkdir will only make directories, so let's be clear and specific, when that doesn't compromise generality. "mkdir DIRNAME" will in no way cause anyone to misunderstand what will happen.

      On the other hand, if there's some great savings in coding so docs and parsers and grammars don't have to handle special cases between things like chdir, mkdir, open, do, require, rmdir, chroot, link, symlink, and other things that take named filesystem entities, I'm all ears. I'm sure the developers have enough to do besides handle pedantic observations like this.

      Whoops! See rmdir:

          rmdir FILENAME
          Deletes the directory specified by FILENAME if that directory is empty. If it succeeds it returns true; otherwise it returns false and sets $! (errno). If FILENAME is omitted, uses $_ .
          To remove a directory tree recursively (rm -rf on Unix) look at the rmtree function of the File::Path module.

      And chmod and chown look weird, just specifying a list. For example:

          chmod LIST
      when the detail says the first element must be the mode. This is better written as:
          chmod MODE, LIST

      Quantum Mechanics: The dreams stuff is made of

        And chmod and chown look weird, just specifying a list. For example:

        chmod LIST

        when the detail says the first element must be the mode. This is better written as:

        chmod MODE, LIST

        Actually, the terse syntax examples given in the Perl documentation convey subtle meaning to those who are aware of the conventions being used and changing "chmod LIST" to "chmod MODE,LIST" would convey incorrect information to such people. (To become such a person, in part, one just needs to read, understand, and remember the 2nd paragraph of perlfunc.)

        $ say "prototype('CORE::chmod')" @

        I don't mind being told "mkdir FILENAME" because it hints at this possibility:

        $ perl -e'mkdir("$ENV{HOME}/.bashrc") or die $!,$/' File exists

        I started down the road of proposing that one of those conventions might actually be involved in the choice of "FILENAME" over "DIRNAME", because I noticed this:

        $ perldoc perlfunc | grep FILENAME | egrep '^ *[a-z]+ [A-Z]' chroot FILENAME mkdir FILENAME,MASK mkdir FILENAME rmdir FILENAME sysopen FILEHANDLE,FILENAME,MODE sysopen FILEHANDLE,FILENAME,MODE,PERMS $ say 'map prototype("CORE::$_"), qw/ chroot mkdir rmdir sysopen /' _ _;$ _ *$$;$

        But that doesn't make sense for a lot of reasons.

        I also noticed:

        $ perldoc perlfunc | grep DIRNAME $ perldoc perlfunc | grep FILENAME | wc -l 16

        So, how does opendir describe its argument?

        $ perldoc -f opendir | head -1 opendir DIRHANDLE,EXPR

        Now, that needs to say "DIRHANDLE" and not "FILEHANDLE", because you can't use a Perl DIRHANDLE as a Perl FILEHANDLE so that distinction is rather important. There is no such distinction between a FILENAME and a DIRNAME for Perl (nor for Unix, nor for Windows).

        But why is that "EXPR" and not "FILENAME"? Well, it is a common choice:

        $ perldoc perlfunc | egrep '^ {7}readlink [A-Z]' readlink EXPR $ perldoc perlfunc | egrep '^ {7}lstat [A-Z]' lstat EXPR $ perldoc perlfunc | egrep '^ {7}do [A-Z]' do BLOCK do SUBROUTINE(LIST) do EXPR Uses the value of EXPR as a filename and executes the c +ontents

        One could argue that "do EXPR" helps to convey the point that "any (other) expression gets interpretted as a file name" as opposed to possibly implying that Perl does something like looking at the value to see if it looks like a file name.

        [ I was surprised to (re)learn this:

        $ perl -we "do findModule(); sub findModule{''}" Use of "do" to call subroutines is deprecated at -e line 1.


        And that might explain the choice of "EXPR" for these cases as well:

        $ perldoc perlfunc | egrep '^ {7}truncate [A-Z]' truncate FILEHANDLE,LENGTH truncate EXPR,LENGTH $ perldoc perlfunc | egrep '^ {7}stat [A-Z]' stat FILEHANDLE stat EXPR stat DIRHANDLE

        Though, I think the case of noticing FILEHANDLE and DIRHANDLE exceptions really is about examining the value not about different syntax, so I find the "EXPR" choice less valuable here. But changing "stat EXPR" to "stat FILENAME" draws too much attention to the distinction between "FILE" and "DIR" in:


        While I think changing "DBNAME" to "FILENAME" would significantly improve the clarity here:

        $ perldoc perlfunc | egrep '^ {7}dbmopen [A-Z]' dbmopen HASH,DBNAME,MASK

        (Because "DBNAME" isn't a "FILENAME" in most contexts I deal with -- though, perhaps "FILENAME" was avoided since suffixes likely get appended.)

        How about places that don't use "EXPR"?

        $ perldoc perlfunc | egrep '^ {7}link ' link OLDFILE,NEWFILE $ perldoc perlfunc | egrep '^ {7}rename ' rename OLDNAME,NEWNAME

        I find "OLDNAME" a much better choice than "OLDFILE". Similar to the starting complaint, "OLDFILE" could be the name of a directory. But more important, for me, is that "OLDFILE" doesn't as clearly convey that what is given is the name of a file not some handle or other representation. I also wouldn't go more explicit like these:


        because I would worry about implying that these can't be used on directories [which isn't something I worry about implying for mkdir() or rmdir()]. One could argue for:


        but I'd probably depart even further and go with:


        (I've long found the argument order for link,3 and ln quite confusing, I must admit.)

        After considering the broader context, I think most of the uses of "FILENAME" really should be changed to "DIRNAME". Not because I find those uses of "FILENAME" confusing or inappropriate, but because they are cases where the distinction doesn't matter and so "DIRNAME" is just slightly clearer. (I find many cases that are a lot more in need of improvement than the one that started this thread.)

        Contrast that with changing "lstat EXPR" to "lstat FILENAME". I don't like "lstat FILENAME" as it sounds like it might be trying to imply that you can't use it on directories or links, but only on plain files. But I also see no reason to use "EXPR" for that case. I think I prefer "lstat PATHNAME".

        So my updates would only be as follows:

        So I'd explicitly leave these unchanged:


        - tye        

Re: mkdir in perldoc
by Anonymous Monk on Jan 09, 2013 at 03:14 UTC



Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://1012350]
Approved by Corion
[LanX]: 😅
[holli]: typo

How do I use this? | Other CB clients
Other Users?
Others wandering the Monastery: (4)
As of 2017-09-23 12:16 GMT
Find Nodes?
    Voting Booth?
    During the recent solar eclipse, I:

    Results (272 votes). Check out past polls.