improved README

README.md

@@ -24,11 +24,16 @@ cdf papers
 # Your are now here: ~/the/windy/road/to/my/many/papers
 ```
 
-**Auto-complete works with `cdf`:** It is sufficient to type the first letters of the name of a shortcut plus the <kbd>Tab</kbd> key.
+## Features
 
-## Installation (UNIX/OSX only)
+- **Simple and lightweight:** `cdf` adds just two new commands:
+  - `addfav` ("add to favorites") 
+  - `cdf` ("`cd` to favorite")
+- You can use any **short and memorable name** for your shortcuts, like `pet` or `thesis` (or even `p73`).
+- Supports **auto-complete:** Just type the first few letters and hit the <kbd>Tab</kbd> key.
+- All **shortcuts can also be used in** a GUI tool like **Apple Finder,** because they are simple symbolic links. 
 
-**Note:** Always backup your `~/.bashrc` or `~/.bash_profile` files prior to installing this tool. If not, please do not blame me if things go wrong.
+## Installation (UNIX/OSX only)
 
 ### Simple
 
@@ -38,21 +43,22 @@ cdf papers
     mkdir some_directory
     cd some_directory
     git clone https://github.com/mfhepp/cdf.git
-    # Git will create a folder named cdf/
     cd cdf
     ```
   - **Option 2:** Download and extract ZIP from <https://github.com/mfhepp/cdf/zipball/main>
 2. Open a terminal window in the respective directory.
 3. Run the install script `install.sh`
     ```bash
-    # Make it executable
-    chmod +x install.sh
     # Run script
     ./install.sh
     ```
+    Normally, the install script should be executable as it stands. If not, run     
+    ```bash
+    chmod +x install.sh
+    ```
 4. Open a new terminal window for the changes to take effect.
 
-### Manual
+### Manual installation
 
 1. Create a directory in your home directory, e.g. `~/myshortcuts`, either in the OSX Finder or a terminal window with 
     ```bash
@@ -65,8 +71,10 @@ cdf papers
     export CDFPATH=~/myshortcuts
     ```
     Replace `~/myshortcuts` with the absolute path of your chosen directory for the shortcuts (e.g. `~/Documents/myshortcuts`; note that `~/` is a shortcut for your user directory on Unix systems; you can also use the full path.). **Save the file, but keep it open.**
-4. After these lines, insert the entire contents from the `cdf.sh` file from this repository. **Save and close the `~/.bashrc` or `~/.bash_profile` file.**
-5. Open a new terminal window or run `source ~/.bashrc` or `source ~/.bash_profile` in open terminal window to activate the changes.
+4. After these lines, insert the entire contents [from the `cdf.sh` file from this repository](https://raw.githubusercontent.com/mfhepp/cdf/main/cdf.sh). You can directly copy-and-paste it from the link. **Save and close the `~/.bashrc` or `~/.bash_profile` file.**
+5. Open a new terminal window for the changes to take effect.
+
+**Note:** Always backup your `~/.bashrc` or `~/.bash_profile` files prior to installing this tool. If not, please do not blame me if things go wrong. The install script tries to create backups automatically.
 
 ## Usage
 
@@ -109,7 +117,7 @@ Existing directory shortcuts are:
 
 You can also use `addfav --list` for the same purpose.
 
-## Command-Line Arguments
+## Command-line arguments
 
 ```bash
 CDF: Change to a directory via a shortcut from CDFPATH
@@ -133,15 +141,17 @@ Example:
   addfav --list:    List all available shortcuts
 ```
 
-## Technical Details
+## Technical details
 
 The tool creates *symbolic links* pointing to the bookmarked paths in the chosen directory. When running `cdf`, we simply obtain the **physical path** with `realpath` (available on most modern systems) and the `cd` to that path, if it exists. Hence, **we end up in the *real physical location and not that of the symbolic link*.**
 
 It is possible to use the `CDPATH` variable for similar purposes, but this has several downsides. One could also change the behavior of the original `cd` command, but I think it is bad practice to mess around with core OS components in an intransparent way; hence the usage of a new `cdf` command.
 
 The script tries to prevent you from creating shortcuts to locations that are themselves symbolic links. 
 
-## Serious Warning: Be CAREFUL when DELETING symbolic links!
+## Warning: Be CAREFUL when DELETING symbolic links!
+
+**IMPORTANT:** Read this if you want to delete shortcuts from the shortcuts folder! When unsure, **use** a GUI tool like the **OSX Finder for deleting symbolic links.**
 
 This tool uses [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link). While this an established part of any Unix-like environment, things can go terribly wrong **when deleting symbolic links**. In the **worst case, you can delete ALL CONTENTS of the target of a symbolic link** when you are **trying to delete the symbolic link.**
 
@@ -161,11 +171,9 @@ rm -r bar/
 rm -r bar
 ```
 
-**Recommendation:** When unsure, **use** a GUI tool like the **OSX Finder for deleting symbolic links.**
-
 This warning is mostly relevant when you are trying to remove previously created symbolic links in the respective folder.
 
-## Security
+## Security considerations
 
 The following aspects are not specific to this tool, but likely useful background information.
 
@@ -194,7 +202,7 @@ This is because OSX, by default, grants at least read-access to all users on the
 
 If you were to use the `source` command to include the `cdf.sh` script within your `.bashrc` or `.bash_profile` file, you must make sure that the respective directory cannot be written to by other users. Otherwise, someone could inject arbitrary Bash commands into your environment. **This is why the install script instead *copies the contents of that script* to your Bash profile.**
 
-## Credits and Acknowledgments
+## Credits and acknowledgments
 
 This tool was initially inspired by the following article:
 
@@ -205,7 +213,7 @@ While the proposed approach works, it has a few limitations, namely that you end
 ChatGPT 4 was a great buddy and time-saver, helping me through the many pitfalls of Bash as the grand, old lady of scripting languages.
 
 
-## Similar Projects
+## Similar projects
 
 There are several other very popular tools for similar purposes, e.g.
 
@@ -228,6 +236,17 @@ Main differences between `cdf` and most of these are as follows:
 - `cdf` **uses a simple folder with symbolic links** for managing the names and target locations of shortcuts.
 - `cdf` **supports arbitrary names for any target path** that are **easy to remember.** You can use **very short names for your most popular directories;** like a simple form of [entropy coding](https://en.wikipedia.org/wiki/Entropy_coding).
 
+## Disclaimer
+
+This project and all Web resources are a non-commercial community contribution. 
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
 
 ## Contact