updated docs

CHANGELOG.md

@@ -7,4 +7,6 @@ v1.0.0
 Initial release
 
 * Added all initially planned features
+* Added INSTALL.md
+* Updated README.md
 

INSTALL.md

@@ -0,0 +1,78 @@
+
+Installation
+============
+
+1. Download a release from `https://github.com/runeimp/gzipdate/releases`
+2. For archives or packages:
+	* For Zip archives (`.zip`) I recommend:
+		1. `unzip gzipdate_1.0.1_windows_x86_64.zip`
+		2. `cd gzipdate_1.0.1_windows_x86_64`
+		3. `copy gzipdate.exe YOUR_PREFERED_PATH`
+	* For Tar-Gzip archives (`.tar.gz`) I recommend:
+		1. `tar xfz gzipdate_1.0.1_freebsd_x86_64.tar.gz`
+		2. `cd gzipdate_1.0.1_freebsd_x86_64`
+		3. `cp gzipdate YOUR_PREFERED_PATH` or `ln -s gzipdate YOUR_PREFERED_PATH/gzipdate` if your source folder is not going to get deleted later.
+	* For the Debian packages (`.deb`) I recommend:
+		* `sudo dpkg -i /path/to/gzipdate_1.0.1_linux_x86_64.deb` to install and upgrade. There are no dependencies so dpkg is fine for this task.
+	* For the RedHat Package Manager (`.rpm`) I recommend:
+		* `rpm -i /path/to/gzipdate_1.0.1_linux_x86_64.rpm` to install
+		* `rpm -U /path/to/gzipdate_1.0.1_linux_x86_64.rpm` to upgrade
+3. Copy the binary to a directory in your PATH and make sure it is executable for your system. It _should_ be ready to go by default.
+
+
+Finding YOUR_PREFERED_PATH (Windows)
+------------------------------------
+
+On Windows systems you can review your path list by:
+
+1. Open a Command Prompt
+2. Type `ECHO "%PATH:;="&ECHO "%"`
+
+
+Finding YOUR_PREFERED_PATH (POSIX)
+----------------------------------
+
+On POSIX systems (\*BSD, Linux, macOS, Solaris, UNIX, etc.) you can review your path list with
+
+```text
+$ echo $PATH | tr : "\n"
+/Users/runeimp/.local/bin
+/Users/runeimp/bin
+/Users/runeimp/dev/lang/go/bin
+/opt/local/bin
+/usr/local/bin
+/usr/local/sbin
+/usr/bin
+/usr/sbin
+/bin
+/sbin
+```
+
+If you use the command `echo $PATH | tr : "\n"` you should see a list similar to the example with `runeimp` replaced with whatever your username is on the system. Directory search priority is from top to bottom when you type in a command.
+
+
+### Which Paths to Avoid
+
+On any system there are certain paths you should not install apps into. On POSIX systems any path that ends with `sbin` means system binary. **NEVER** manually install apps into an `sbin` path. Following is a general order of preference when installing apps on a system for all users:
+
+* `/opt/local/bin` - This is generally best as `opt` paths are intended for _option software_ when it is present.
+	* This is where most package managers will install binaries. If it doesn't exist you should probably install something wonderful like [`just`][] or [`kitty`][] with your package manager to kickstart the path.
+* `/usr/local/opt` - This is a good path to use if it exists in your list and `/opt/local/bin` is not available.
+	* This is where many package managers will install binaries. If it doesn't exist you should probably install something wonderful like [`git`][] or [`wget`][] with your package manager to kickstart the path.
+* `/usr/local/bin` - This is a good path to use if neither `opt` path is available. Almost always available on all POSIX systems.
+	* This is where most package managers will install binaries. If it doesn't exist you should probably install something wonderful like [`jq`][] or [`htop`][] with your package manager to kickstart the path.
+* `/usr/bin` - This is acceptable if none of the above paths are available. Though it should be avoided if possible.
+	* If this seems to be your only option **definitely** try to install something with your package manager if you haven't already. Doing so should create one of the above paths which are _much_ preferred over `/usr/bin`.
+* `/bin` - While you could _technically_ install binaries to this path it's a very bad idea. System updates expect full control over this path and may remove or overwrite binaries you install there without warning before hand or notice after the fact.
+
+
+
+
+
+[`git`]: https://git-scm.com/
+[`htop`]: https://hisham.hm/htop/
+[`jq`]: https://stedolan.github.io/jq/
+[`just`]: https://github.com/casey/just
+[`kitty`]: https://sw.kovidgoyal.net/kitty/
+[`wget`]: https://www.gnu.org/software/wget/
+

README.md

@@ -7,17 +7,74 @@ Simple command line app for the specific creation and handling of Gzip archives.
 Features
 --------
 
-* Create gzip archives for each of a list of files, adding a file system safe ISO-601 datatime value to the filename when creating the archive
+* Create gzip archives for each of a list of files, adding a file system safe [ISO-8601][ISO 8601 - Wikipedia] datatime value to the filename when creating the archive. The format is `YYYY-MM-DD_HHmmss`.
 * Extract the archived file from Gzip archives restoring their original names if available. The original name is always available for archives created by GzipDate.
 * Does not delete source files by default. Though they can be automatically deleted with a command line switch.
 * Always uses maximum compression when creating archives
 * 100% compatible with gzip and gunzip tools
 * Written in Go so it's easy to cross-compile binaries for many platforms
 
 
+Usage Examples
+--------------
+
+### Help
+
+```text
+$ gzipdate -h
+GzipDate v1.0.0
+
+USAGE: gzipdate [OPTIONS] [FILENAMES]
+
+OPTIONS:
+  -d | -del | -delete   Delete the source file after successful processing
+  -h | -help            Display this help info
+  -v | -ver | -version  Display this apps version number
+
+Options may be interspersed with file names if so desired.
+They are not position dependent.
+```
+
+### Brogue Save Game Backup
+
+```text
+runeimp$ ls -hl
+total 112
+-rw-r--r--  1 runeimp  staff    54K Apr 16 10:33 Saved game.broguesave
+
+runeimp$ gzipdate -d *
+Saving 21400 bytes from "Saved game.broguesave" to "Saved game.broguesave_2020-04-16_104846.gz"
+    Deleting source: "Saved game.broguesave"
+
+runeimp$ ls -hl
+total 48
+-rw-r--r--  1 runeimp  staff    21K Apr 16 10:48 Saved game.broguesave_2020-04-16_104846.gz
+
+runeimp$ gzipdate *.gz
+54984 B written to "Saved game.broguesave"
+
+runeimp$ ls -hl
+total 160
+-rw-r--r--  1 runeimp  staff    54K Apr 16 10:33 Saved game.broguesave
+-rw-r--r--  1 runeimp  staff    21K Apr 16 10:48 Saved game.broguesave_2020-04-16_104846.gz
+```
+
+Note that the size and date of "Saved game.broguesave" is the same in the original as in the version restored from the archive.
+
+Side Note: I added an extra line before each successive command in the second example for better readability.
+
+
 Rational
 --------
 
-I like making archives with the date in the name. Especially for game saves that get auto deleted like in Roguelike type games. It's also supper annoying to me that `gunzip` doesn't use the stored filename within the archive by default. I also like my tools to be smart about if a file is already compressed or not. Gzip will give an error if you try to recompress a file that already ends in `.gz`. GzipDate just uncompresses the file instead.
+I like making archives with the date in the name. Especially for game saves that get auto deleted like in Roguelike type games. It's also super annoying to me that `gunzip` doesn't use the stored filename within the archive by default. I also like my compression tools to be smart about if a file is already compressed or not. Gzip will give an error if you try to recompress a file that already ends in `.gz`. GzipDate just uncompresses the file instead. So just one command to use in either case.
+
+
+Installation
+------------
+
+See the [installation docs](INSTALL.md)
+
 
+[ISO 8601 - Wikipedia]: https://en.wikipedia.org/wiki/ISO_8601