Markdown and updated READMEs and gitignore

* Converted the READMEs to Markdown
* Added useful links (like the one to the [DocBook guide](https://tdg.docbook.org/))
* Updated obviously out of date content
* Added some Notes
* Added test byproducts to `tests/.gitignore`

My hope is that this makes the xdg-utils seem less like a dead project and lowers the barrier for contributing.

7 files changed, 332 insertions, 241 deletions

diff --git a/README b/README
deleted file mode 100644
index e680e47..0000000
--- a/README
+++ /dev/null
@@ -1,100 +0,0 @@
-xdg-utils
----------
-
-    The xdg-utils package is a set of simple scripts that provide
-basic desktop integration functions for any Free Desktop, such as Linux.
-
-    They are intended to provide a set of defacto standards.  This
-means that:
-    *  Third party software developers can rely on these xdg-utils
-       for all of their simple integration needs.
-
-    *  Developers of desktop environments can make sure that their
-       environments are well supported
-
-       If a desktop developer wants to be certain that their environment
-       functions with all third party software, then can simply
-       make sure that these utilities work properly in their environment.
-
-       This will hopefully mean that 'third tier' window managers
-       such as XFCE and Blackbox can reach full parity with Gnome and KDE
-       in terms of third party ISV support.
-
-    *  Distribution vendors can provide custom versions of these utilities
-
-       If a distribution vendor wishes to have unusual systems,
-       they can provide custom scripts, and the third party software
-       should still continue to work.
-
-
-OVERVIEW:
----------
-
-    The following tools are included in xdg-utils 1.0:
-
-xdg-desktop-menu	Install desktop menu items
-xdg-desktop-icon	Install icons to the desktop
-xdg-icon-resource	Install icon resources
-xdg-mime		Query information about file type handling and
-			install descriptions for new file types
-xdg-open		Open a file or URL in the user's preferred application
-xdg-email		Send mail using the user's preferred e-mail composer
-xdg-screensaver		Control the screensaver
-
-
-BUILD:
-------
-
-    Building is not required, all tools are located in the
-scripts/ subdirectory and are ready to be used.
-
-    You can optionally choose to install the scripts
-to a target directory.  To do this, you could issue
-the following commands:
-         ./configure [--prefix=<your-place-here>]
-        make install
-that would cause the scripts to be installed to
-  <your-place-here>/bin
-
-
-USE:
-----
-
-    Although we expect that these scripts will generally come as part
-of the operating system, we recommend that you package the scripts
-that your application needs along with your product as a fallback. For
-this purpose please obtain the original version of the xdg-utils from
-http://portland.freedesktop.org. The xdg-utils scripts that are
-distributed by operating systems vendors may have been tuned for their
-particular operating system and may not work on the same broad variety
-of operating systems as the original version.
-
-    We recommend that you place these scripts in a directory, and
-then add that directory to the end of the PATH.  So, let's say that
-you're writing your post installation script, and you want to create
-a menu on any xdg-util compliant environment.  Let's further assume
-that you've just installed to $INSTALL_DIR, and that your menu
-desktop file is in $INSTALL_DIR/desktop/icon.desktop.  Finally, let's
-say that you've included the xdg-utils package in your installation
-in $INSTALL_DIR/xdg-utils.
-
-    Then a simple post install script could look like this:
-
-        export PATH=$PATH:$INSTALL_DIR/xdg-utils
-        xdg-desktop-menu install $INSTALL_DIR/mycompany-myapp.desktop
-
-    And now your product has a menu on any XDG compliant desktop!
-
-Note that we strongly recommend using this method - that is,
-putting your copy of the xdg-utils at the end of the path,
-and then invoking them without a specific path name.
-
-That will allow your users and their system providers to
-use custom versions of the xdg-utils to adjust for system specific
-differences.
-
-If you wish to absolutely force the issue and only use the versions
-you shipped, you could instead hard code the path to the version
-you bundle with your application.  We strongly recommend against
-this, as it will make your product obsolete more quickly than is
-necessary.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b514cb7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,126 @@
+# xdg-utils
+
+The xdg-utils package is a set of scripts that provide
+basic desktop integration functions for any Free Desktop
+on Linux, the BSDs and even partially on MacOS and WSL.
+
+They are intended to provide a set of defacto standards.  This
+means that:
+
+* Third party software developers can rely on these xdg-utils
+  for all of their simple integration needs.
+
+* Developers of desktop environments can make sure that their
+  environments are well supported
+
+  If a desktop developer wants to be certain that their environment
+  functions with all third party software, then can simply
+  make sure that these utilities work properly in their environment.
+
+  This will hopefully mean that 'third tier' window managers
+  such as XFCE and Blackbox can reach full parity with Gnome and KDE
+  in terms of third party ISV support.
+
+* Distribution vendors can provide custom versions of these utilities
+
+  If a distribution vendor wishes to have unusual systems,
+  they can provide custom scripts, and the third party software
+  should still continue to work.
+
+Documentation is mostly in the maual pages and on the [freedesktop.org wiki](https://www.freedesktop.org/wiki/Software/xdg-utils/).
+
+## Overview
+
+
+The following tools are included in xdg-utils 1.0:
+
+* `xdg-desktop-menu` - Install desktop menu items
+* `xdg-desktop-icon` - Install icons to the desktop
+* `xdg-icon-resource` - Install icon resources
+* `xdg-mime` - Query information about file type handling and install descriptions for new file types
+* `xdg-open` - Open a file or URL in the user's preferred application
+* `xdg-email` - Send mail using the user's preferred e-mail composer
+* `xdg-screensaver` - Control the screensaver
+
+
+## Building
+
+While the xdg-utils are shellscripts they are not ready to be used as is.
+
+Run `make` in the root directory of this repository to build [scripts and documentation](scripts).
+
+### Installing
+
+<b>Note:</b> If you just want to use the xdg-utils please use the version packaged in your distribution unless you have a reason not to do so.
+
+You can optionally choose to install the scripts
+to a target directory.  To do this, you could issue
+the following commands:
+
+```sh
+./configure [--prefix=<your-place-here>]
+make install
+```
+
+That would cause the scripts to be installed to `<your-place-here>/bin`
+
+
+## Use in (Custom) Install Scripts
+
+Please consider making yourself familiar with how to package for a given distribution
+and the recommend tooling before writing a custom installer.
+Even a beinner level package is in most cases better than a "run me as root" install script.
+(especially if you support only one or a handful of distributions anyway)
+
+That said …
+
+Although we expect that these scripts will generally come as part
+of the operating system, we recommend that you package the scripts
+that your application needs along with your product as a fallback.
+
+For this purpose please obtain the original version of the xdg-utils from
+https://www.freedesktop.org/wiki/Software/xdg-utils/.
+The xdg-utils scripts that are distributed by operating systems vendors
+may have been tuned for their particular operating system
+and may not work on the same broad variety
+of operating systems as the original version.
+
+We recommend that you place these scripts in a directory, and
+then add that directory to the end of the `PATH`.
+
+---
+
+So, let's say that you're writing your post installation script,
+and you want to create a menu on any xdg-util compliant environment.
+
+Let's further assume that you've just installed to `$INSTALL_DIR`,
+and that your menu desktop file is in `$INSTALL_DIR/desktop/icon.desktop`.
+
+Finally, let's say that you've included the xdg-utils package in your installation
+in `$INSTALL_DIR/xdg-utils`.
+
+
+Then a simple post install script could look like this:
+
+```sh
+export PATH="$PATH:$INSTALL_DIR/xdg-utils"
+xdg-desktop-menu install "$INSTALL_DIR/mycompany-myapp.desktop"
+```
+
+And now your product has a menu on any XDG compliant desktop!
+
+---
+
+Note that we strongly recommend using this method - that is,
+putting your copy of the xdg-utils at the end of the `PATH`,
+and then invoking them without a specific path name.
+
+That will allow your users and their system providers to
+use custom versions of the xdg-utils to adjust for system specific
+differences.
+
+If you wish to absolutely force the issue and only use the versions
+you shipped, you could instead hard code the path to the version
+you bundle with your application.  We strongly recommend against
+this, as it will make your product obsolete more quickly than is
+necessary.
diff --git a/scripts/HACKING b/scripts/HACKING
deleted file mode 100644
index ab1da9a..0000000
--- a/scripts/HACKING
+++ /dev/null
@@ -1,17 +0,0 @@
-Note that the actual scripts are generated from xdg-*.in,
-xdg-utils-common.in and desc/xdg-*.xml which contains the
-command line descriptions. These are the files that you
-want to edit.  To add a new script, you must also provide 
-a desc/xdg-*.xml file.
-
-DO NOT MAKE CHANGES TO THE GENERATED SCRIPTS THEMSELVES!
-
-Use 'make scripts-clean' to delete all generated files and use
-'make scripts' to re-generate them.
-
-The manual files in man/ and html/ are also generated from the
-desc/xdg-*.xml files.
-
-Use 'make scripts html man' to update all generated files
-
-Use 'make release' to remove everything but the generated files.
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..eb41e03
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,51 @@
+# xdg-utils - Scripts and Documentation
+
+The actual scripts are generated from `xdg-*.in`,
+[xdg-utils-common.in](xdg-utils-common.in) and
+[desc/xdg-*.xml](desc) which contains the
+command line descriptions.
+
+These are the files that you want to edit.
+To add a new script, you must also provide 
+a `desc/xdg-*.xml` file.
+
+**Do not make changes to the generated scripts themselves!**
+
+---
+
+Use `make scripts-clean` to delete all generated files and use
+`make scripts` to re-generate them.
+
+The manual files in [man/](man) and [html/](html)
+are also generated from the [desc/xdg-*.xml](desc) files.
+
+Use `make scripts html man` to update all generated files
+
+Use `make release` to remove everything but the generated files.
+
+## Writing Documentation
+
+The files in [desc/](desc) make use of the [DocBook format](https://tdg.docbook.org/).
+
+If you want to use more recent tags please update to the minimum version of DocBook that is required by changing the `DOCTYPE`.
+
+Exmaple:
+
+You want to use the `<code>` tag which requires DocBook 4.3.
+
+Replace the lines …
+
+```xml
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+```
+
+… with:
+
+```xml
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+```
+
diff --git a/tests/.gitignore b/tests/.gitignore
index f3c7a7c..5479af8 100644
--- a/tests/.gitignore
+++ b/tests/.gitignore
@@ -1 +1,3 @@
 Makefile
+tmp
+*.log
diff --git a/tests/README b/tests/README
deleted file mode 100644
index 8ebcfef..0000000
--- a/tests/README
+++ /dev/null
@@ -1,124 +0,0 @@
-README: xdg-utils tests
-
-Created 6/27/2006 by Tom Whipple <tom.whipple@intel.com>
-
-
-RUNNING XDG-UTILS TESTS
------------------------
-At a minimum, you must have your current directory be the same as the
-directory containing this README. Then, simply execute:
-
-$ ./testrun
-WARNING: guessed XDG_TEST_DIR to be /home/tw/portland/xdg-utils/tests
-TEST_LIST:  generic_bogus_arg-1-1 ... generic_version-1-50
-...
-FAIL: test_user_mime_install
-NORESULT: test_system_mime_install
-71 of 92 tests passed. (114 attempted)
-See xdg-test.log for details.
-NOT OK!
-
-FAIL     indicates (not surprisingly) a test failure.
-NORESULT indicates that the test prerequisites failed for some reason. 
-         (e.g. the install phase of an uninstall test failed)
-UNTESTED means that something needed was not found. This is fine and should
-         be ignored. These tests are not counted in the total, only attempted. 
-         (e.g. test requires root, but we are not running as root)
-
-NOTE: The test runner makes guesses about appropriate values of XDG_TEST_DIR
-      and PATH. These values can be overridden explicitly.
-
-To run tests individually, or as smaller groups do something like
-
-$ ./testrun xdg-mime
-
-OR
-
-$ ./testrun xdg-mime/t.10-user_mime_install
-
-OR (if you have defined XDG_TEST_DIR and PATH correctly)
-
-$ xdg-mime/t.10-user_mime_install
-
-
-BACKUPS
--------
-THESE TESTS CHANGE YOUR USER ENVIRONMENT. Effort is made to keep pollution
-to a minimum, but we make no guarantees!! Back up your environment/system
-early and often. This is especially critical if you run tests as root. You
-have been warned. 
-
-
-INTERACTIVE TESTS
------------------
-Because it is difficult to verify the way things appear to the user, some
-tests are interactive and require the user to verify or perform actions.
-This is sometimes annoying, so interactive tests can be disabled with the
--I flag. Note that if you run tests non-interactively, some tests
-(xdg-email) may generate strange errors on the screen, since the test
-cleans up support files before the email client tries to read them. Use
-the -C option to work around this.
-
-
-PRIVILEGED TESTS
----------------
-BACK UP YOUR SYSTEM. See above.
-
-Some tests require root (e.g. those commands with a --system option). So,
-tests in this group return UNTESTED if they are not run as root. 
-
-The test runner will ask for the root password in order to run these tests
-as the root user.
-
-
-CLEANUP
--------
-Tests should clean up after themselves. However, this sometimes fails,
-so use 'sudo make tests-clean' or 'make tests-userclean'.
-(Note that you must have generated a makefile via 'cd .. && ./configure'
-at some point.) 
-
- 
-DIRECTORY STRUCTURE
--------------------
-xdg-*		tests for each util
-include		"library" code used by most tests
-generic		generic tests to be run on most utilities.
-		See xdg-mime/t.apply_generic
-
-
-WRITING XDG-UTILS TESTS
------------------------
-See xdg-mime/t.10-user_mime_install as an example.
-
-Each test is as follows
-
-test_function() {		-- Tests are functions for TET integration.
-
-test_start "test description"	-- required to begin a test
-test_purpose "verbose text"	-- optionally provide a verbose description.
-				   not used.
-test_init			-- optionally begin a prerequisite section.
-				   assertions that fail here cause NORESULT
-				   rather than FAIL
-<pre-assertions>
-test_procedure			-- required to begin the actuall test
-				   assertions
-<test-assertions>
-
-test_result			-- required to generate result codes.
-				   Must be last.
-}
-
-run_test test_function
-  - OR -
-repeat_test test_function NVARS V1 ... VN V1val1 ... V1valM ... VNval1 ... VNvalM
-				-- one of the above is required. 
-				   see include/testcontrol.sh for detail
-				
-
-For questions or feedback, please use the Portland mailinglist at
-http://lists.freedesktop.org/mailman/listinfo/portland
-
-Test results can be submitted on
-http://portland.freedesktop.org/testreport.html
diff --git a/tests/README.md b/tests/README.md
new file mode 100644
index 0000000..9e193fb
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1,153 @@
+# xdg-utils tests
+
+Created 6/27/2006 by Tom Whipple <tom.whipple@intel.com>
+
+## Running xdg-utils Tests
+
+At a minimum, you must have your current directory be the same as the
+directory containing this README.
+
+Then execute:
+```
+$ ./testrun -R
+WARNING: guessed XDG_TEST_DIR to be /home/tw/portland/xdg-utils/tests
+TEST_LIST:  generic_bogus_arg-1-1 ... generic_version-1-50
+...
+FAIL: test_user_mime_install
+NORESULT: test_system_mime_install
+71 of 92 tests passed. (114 attempted)
+See xdg-test.log for details.
+NOT OK!
+
+FAIL     indicates (not surprisingly) a test failure.
+NORESULT indicates that the test prerequisites failed for some reason. 
+         (e.g. the install phase of an uninstall test failed)
+UNTESTED means that something needed was not found. This is fine and should
+         be ignored. These tests are not counted in the total, only attempted. 
+         (e.g. test requires root, but we are not running as root)
+
+NOTE: The test runner makes guesses about appropriate values of XDG_TEST_DIR
+      and PATH. These values can be overridden explicitly.
+```
+
+<b>Note:</b> The `-R` flag disables tests that require root privileges,
+remove it to include those. See [Privileged Tests](#privileged-tests)
+
+To run tests individually, or as smaller groups do something like
+
+```sh
+./testrun -R xdg-mime
+```
+
+OR
+
+```sh
+./testrun -R xdg-mime/t.10-user_mime_install
+```
+
+OR (if you have defined `XDG_TEST_DIR` and `PATH` correctly)
+
+```sh
+xdg-mime/t.10-user_mime_install
+```
+
+## Create Backups!
+
+**These tests change your user environment.**
+
+Effort is made to keep pollution to a minimum, but we make no guarantees!!
+
+Back up your environment/system early and often.
+This is especially critical if you run tests as root.
+You have been warned. 
+
+
+## Interactive Tests
+
+Because it is difficult to verify the way things appear to the user, some
+tests are interactive and require the user to verify or perform actions.
+
+This is sometimes annoying, so interactive tests can be disabled with the
+`-I` flag. Note that if you run tests non-interactively, some tests
+(xdg-email) may generate strange errors on the screen, since the test
+cleans up support files before the email client tries to read them. Use
+the `-C` option to work around this.
+
+
+## Privileged Tests
+
+[**BACK UP YOUR SYSTEM.** See above.](#create-backups)
+
+Some tests require root (e.g. those commands with a `--system` option). So,
+tests in this group return `UNTESTED` if they are not run as root. 
+
+The test runner will ask for the root password in order to run these tests
+as the root user.
+
+To disable privileged tests, use the `-R` option.
+
+## Cleanup
+
+Tests should clean up after themselves. However, this sometimes fails,
+so use `sudo make tests-clean` or `make tests-userclean`.
+
+(Note that you must have generated a makefile via `cd .. && ./configure`
+at some point.) 
+
+ 
+## Directory Structure
+
+* `xdg-* ` - tests for each util
+* [include](include) -	"library" code used by most tests
+* [generic](generic) - generic tests to be run on most utilities.
+  i.e. [xdg-mime/t.00-apply_generic](xdg-mime/t.00-apply_generic)
+
+
+## Writing xdg-utils Tests
+
+See [xdg-mime/t.10-user_mime_install](xdg-mime/t.10-user_mime_install) as an example.
+
+Each test is as follows
+
+```sh
+# Tests are functions for TET integration.
+test_function() {
+
+	# required to begin a test
+	test_start "test description"  
+
+	# optionally provide a verbose description. (not used)
+	test_purpose "verbose text"	   
+
+	# optionally begin a prerequisite section.
+	# assertions that fail here cause NORESULT
+	# rather than FAIL
+	test_init
+
+	# pre-assertions go here
+
+	# required to begin the actual test assertions
+	test_procedure
+
+	# test-assertions go here
+	
+	# required to generate result codes.
+	# Must be last
+	test_result
+}
+
+run_test test_function
+#  - OR -
+repeat_test test_function NVARS V1 ... VN V1val1 ... V1valM ... VNval1 ... VNvalM
+```
+
+One of `run_test` or `repeat_test` is required,
+see [include/testcontrol.sh](include/testcontrol.sh) for detail.
+
+## Feedback
+
+For questions or feedback, please use the Portland mailinglist at
+http://lists.freedesktop.org/mailman/listinfo/portland
+
+Test results and issues can be filed on the
+[xdg-utils issue tracker on the freedesktop.org gitlab](https://gitlab.freedesktop.org/xdg/xdg-utils/-/issues).