Tldr: Refactor proposal: incorrect and/or inconsistent usage of the word "folder"

[mebeim]

I noticed a widespread misusage of the term "folder", which is almost always used in pages as a replacement for the term "directory", even though the two words have different meanings.

The substantial difference between a directory and a folder is that a directory is a file system concept, while a folder is a term used to indicate the graphical user interface representing a directory (an analogy to an office file folder).

Using the term "folder" when describing the bahavior of a command line program is therefore most of the times wrong and/or misleading.

---

Carefully analizing by hand every single occurrence of the word, I found out that the term "folder" is often:

1. Misused instead of "directory".

   • In pages like cp (manpage), chown (manpage), attrib (manpage) and many others, where the manpage for the command doesn't even talk about folders at all (obviously, since these commands work on directories).

   • In other pages where it is clear that the object being referred to by the term "folder" is actually a system directory, for example in tomb:

     - Mount a tomb (by default in /media) using its key, making it usable as a regular filesystem folder:
     

2. Used inconsistently: "directory" used in the example description, but "folder" used in the example code, or vice versa.

   For example, in rsync:

   - Transfer a directory and all its children from a remote to local:
   
   `rsync -r {{remote_host_name}}:{{remote_folder_location}} {{local_folder_location}}`
   

3. Not used when needed: descriptions saying "in a file or folder" and example code showing path/to/file instead of path/to/file_or_folder, as recommended by the style guide.

   For example, in 7z, 7za, 7zr:

   - Archive a file or folder:
   
   `7z a {{archived.7z}} {{path/to/file}}`
   

The only exceptions I found for the above three points are the following, where the term "folder" is correctly used:

• bw: the term "folder" is specifically used by Bitwarden as a resource type.
• gdrive: the term "folder" is specifically used by Google Drive to identify directories in the cloud.
• skicka: same as gdrive.

---

What I'm proposing

I am proposing to apply the following changes to solve this issue:

• Fix pages for all of the above scenarios.
• Change the term "folder" to "directory" in the style guide.
• Change the term "folder" to "directory" in the pull request template.

What it could look like

I already had a go at this: a single commit applying what I've just proposed in the above section was made in my forked repo, manually checking each page. The total number of affected pages would be 81, along with the two files .github/PULL_REQUEST_TEMPLATE.md and contributing-guides/style-guide.md.

Here's a full list:

 it/com/7z it/com/7za it/com/7zr com/7z com/7za com/7zr com/adb com/ag com/asar com/atom com/aws-s3 com/bashmarks com/blender com/borg com/bup com/chgrp com/chmod com/chown com/cmake com/code com/cp com/cpio com/cppcheck com/cppclean com/df com/du com/duplicity com/git-checkout com/git-log com/git-worktree com/gitk com/gource com/gradle com/hg-commit com/ipfs com/jekyll com/ln com/mc com/mkdir com/mocha com/mogrify com/mongodump com/mongorestore com/mvn com/ng com/pdfunite com/pt com/rbenv com/rclone com/repren com/restic com/rm com/rsync com/scp com/sendmail com/sftp com/shards com/spike com/srm com/stow com/subl com/svgo com/tar com/tee com/tokei com/vagrant com/vue linux/chattr linux/entr linux/getfacl linux/mkisofs linux/smbclient linux/tomb linux/watch osx/ditto osx/drutil osx/du osx/sips osx/tree windows/attrib windows/xcopy

In case this refactor looks too heavy, I could document each change individually. I could also break it into individual commits for all the affected pages (although I don't think that would really be necessary).

---

Wat do you guys think about this?

[agnivade]

Wow, TIL that there is a difference !

I think 2 and 3 can be done right away in 2 separate commits.

1 is kind of low priority. If you are willing to do it, I would prioritize doing 2 and 3 first and then come to 1.

[owenvoke]

This seems like a good idea to me. 👍

[mebeim]

@agnivade when you talk about "1,2,3" are you talking about the numbered list:

1. Misused
2. Used inconsistently
3. Not used when needed

Or the proposed changes:

• Fix pages
• Edit the style guide
• Edit the PR template

Sorry for the confusion 😅 just want to be sure what you're talking about.

[agnivade]

The numbered list.

[waldyrious]

@mebeim shouldn't we include this recommendation in the Style guide? Using "folder" as interchangeable with "directory" is a pretty common practice so it would be helpful to have somewhere to point people to when needed, with links to the appropriate background for justification.

[mebeim]

@waldyrious I guess it could be helpful, but that's not a style guideline.

[zlatanvasovic]

It is, actually. Using specific words over others is a part of the writing style.

[sbrl]

does writing style == style guide though?

[mebeim]

@zdroid Our style guide currently basically only concerns formatting of pages and user tokens. It's not a guideline about grammar mistakes or specific word usage in a given context. That's what I meant in my comment, and that's why I wouldn't know where to fit a rule about the usage of the word "directory" over "folder" in that document.

[zlatanvasovic]

That's correct, it doesn't fit under the current layout of the file. But that can be changed. Although I'd prefer things like this to be linted instead of checked manually.

[mebeim]

@zdroid a re-shape of the file layout looks like a good idea. Linting something like that seems unfeasible though :thinking:. It would require a good amount of natural language processing, I don't think there's anything that can do that.