2016-06-03 22:21:19 (UTC-03:00)

Marcel Rodrigues <marcelgmr@gmail.com>

Add FAQ.md with information for common use cases.

FAQ.md is supposed  to provide extra documentation  for Rover, based
on common  queries from  users. It's  a good  place to  put detailed
information that doesn't fit the manual.

The file  rover.sh has been  removed and  an explanation for  it has
been added in FAQ.md instead. The same should be done for any helper
script that might become worth of mention in the future. That way we
don't clutter the repository with files  that aren't part of a Rover
basic setup.

diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 0000000..b666e4e
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,69 @@
+# Frequently Asked Questions
+
+## How to use Rover to change the current directory of a shell?
+
+Rover cannot change  the working directory of its  calling shell directly.
+However, we can use the option `--save-cwd` to write the last visited path
+to a temporary file. Then we can `cd` to that path from the shell itself.
+
+The following shell script can be used to automate this mechanism.
+Note that it needs to be sourced directly from the shell.
+
+```
+#! /bin/sh
+
+# Based on ranger launcher.
+
+# Usage:
+#     . ./cdrover.sh [/path/to/rover]
+
+tempfile="$(mktemp 2> /dev/null || printf "/tmp/rover-cwd.%s" $$)"
+if [ $# -gt 0 ]; then
+    rover="$1"
+    shift
+else
+    rover="rover"
+fi
+"$rover" --save-cwd "$tempfile" "$@"
+returnvalue=$?
+test -f "$tempfile" &&
+if [ "$(cat -- "$tempfile")" != "$(echo -n `pwd`)" ]; then
+    cd "$(cat "$tempfile")"
+fi
+rm -f -- "$tempfile"
+return $returnvalue
+```
+
+## How to open files with appropriate applications?
+
+Rover doesn't have any built-in functionality to associate file types with
+applications. This  is delegated  to an external  tool, designated  by the
+environmental variable  `$ROVER_OPEN`. This  tool must  be a  command that
+takes a filename as argument and runs the appropriate program, opening the
+given file.
+
+As an example, the following shell script may be used as `$ROVER_OPEN`:
+
+```
+#! /bin/sh
+
+# Usage:
+#     ./open.sh /path/to/file
+
+case "$1" in
+  *.htm|*.html)
+    fmt="elinks %s" ;;
+  *.pdf|*.xps|*.cbz|*.epub)
+    fmt="mutool draw -F txt %s | less" ;;
+  *.ogg|*.flac|*.wav|*.mp3)
+    fmt="play %s" ;;
+  *.[1-9])
+    fmt="man -l %s" ;;
+  *.c|*.h|*.sh|*.lua|*.py|*.ml|*[Mm]akefile)
+    fmt="vim %s" ;;
+  *)
+    fmt="less %s"
+esac
+
+exec sh -c "$(printf "$fmt" "\"$1\"")"
+```

diff --git a/rover.sh b/rover.sh
deleted file mode 100755
index 82edf7c..0000000
--- a/rover.sh
+++ /dev/null
@@ -1,21 +0,0 @@
-#!/bin/sh
-
-# Based on ranger launcher.
-#
-# Usage: ". ./rover.sh [/path/to/rover]"
-
-tempfile="$(mktemp 2> /dev/null || printf "/tmp/rover-cwd.%s" $$)"
-if [ $# -gt 0 ]; then
-    rover="$1"
-    shift
-else
-    rover="rover"
-fi
-"$rover" --save-cwd "$tempfile" "$@"
-returnvalue=$?
-test -f "$tempfile" &&
-if [ "$(cat -- "$tempfile")" != "$(echo -n `pwd`)" ]; then
-    cd "$(cat "$tempfile")"
-fi
-rm -f -- "$tempfile"
-return $returnvalue