README.{txt -> md) and update text incl. license

3 files changed, 187 insertions, 132 deletions

diff --git a/LICENSE.txt b/LICENSE.txt
index 97bd585..7ce0812 100755
--- a/LICENSE.txt
+++ b/LICENSE.txt
@@ -3,7 +3,7 @@ JOAL is released under the BSD license. The full license terms follow:
 L.1) The JOAL source tree contains code from the JogAmp Community
      which is covered by the Simplified BSD 2-clause license:
 
-   Copyright 2010 - 2019 JogAmp Community. All rights reserved.
+   Copyright 2010 - 2023 JogAmp Community. All rights reserved.
   
    Redistribution and use in source and binary forms, with or without modification, are
    permitted provided that the following conditions are met:
@@ -30,16 +30,13 @@ L.1) The JOAL source tree contains code from the JogAmp Community
    or implied, of JogAmp Community.
 
    You can address the JogAmp Community via:
-       Web                http://jogamp.org/
-       Forum/Mailinglist  http://jogamp.762907.n3.nabble.com/
-       Chatrooms
-         IRC              irc.freenode.net #jogamp 
-         Jabber           conference.jabber.org room: jogamp (deprecated!)
-       Repository         http://jogamp.org/git/
-       Email              mediastream _at_ jogamp _dot_ org
+       Web                https://jogamp.org/
+       Forum/Mailinglist  https://forum.jogamp.org
+       Repository         https://jogamp.org/git/
+       Wiki               https://jogamp.org/wiki/
+       Maintainer         https://jogamp.org/wiki/index.php/Maintainer_and_Contacts
 
-
-L.2) The GlueGen source tree contains code from Sun Microsystems, Inc. 
+L.2) The JOAL source tree contains code from Sun Microsystems, Inc. 
      which is covered by the New BSD 3-clause license:
 
    Copyright (c) 2003-2006 Sun Microsystems, Inc. All Rights Reserved.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d566099
--- /dev/null
+++ b/README.md
@@ -0,0 +1,180 @@
+# JOAL, OpenAL API Binding for Java™
+
+[Original document location](https://jogamp.org/cgit/joal.git/about/)
+
+## Git Repository
+This project's canonical repositories is hosted on [JogAmp](https://jogamp.org/cgit/joal.git/).
+
+## Overview
+The [*JOAL Project*](https://jogamp.org/joal/www/) hosts a reference implementation of the
+Java bindings for [OpenAL API](http://www.openal.org/), and is designed to provide
+hardware-supported 3D spatialized audio for applications written in Java.
+
+This project also hosts the Sound3D Toolkit, a high level
+API for spatialized audio built on top of the OpenAL bindings.
+This toolkit is designed to provide access to all the features
+of OpenAL through an intuitive, easy to use, object-oriented interface.
+
+JOAL is part of [the JogAmp project](https://jogamp.org).
+
+**The JogAmp project needs funding and we offer [commercial support](https://jogamp.org/wiki/index.php?title=Maintainer_and_Contacts#Commercial_Support)!**<br/>
+Please contact [Göthel Software (Jausoft)](https://jausoft.com/).
+
+### License
+See [LICENSE.txt](LICENSE.txt).
+
+## Platform Support
+JOAL is tested against [OpenAL-Soft](https://openal-soft.org/) ([github repo](https://github.com/kcat/openal-soft/)),
+the cross-platform, software implementation of the OpenAL 3D audio API.
+
+See OpenAL-Soft [environment variables](https://github.com/kcat/openal-soft/blob/master/docs/env-vars.txt)
+and [configuration example](https://github.com/kcat/openal-soft/blob/master/alsoftrc.sample).
+
+All JOAL platform builds contain a self-build native library of [OpenAL-Soft](https://openal-soft.org/),
+version [**v1.23.1** *from our fork*](https://jogamp.org/cgit/openal-soft.git/).
+
+Our builds expose the following audio backends:
+
+### GNU/Linux
+- PipeWire
+- PulseAudio
+- ALSA
+- OSS
+- SndIO (linked)
+- WaveFile
+- Null
+
+### Android/Linux
+- PipeWire
+- OpenSL
+- WaveFile
+- Null
+
+### Windows
+- WinMM
+- DirectSound
+- WASAPI
+- WaveFile
+- Null
+
+### MacOS
+- CoreAudio
+- WaveFile
+- Null
+
+## Build Requirements
+This project has been built under Win32, GNU/Linux, Android/Linux and MacOS. 
+
+Check [GlueGen's HowToBuild](https://jogamp.org/gluegen/doc/HowToBuild.html)
+for basic prerequisites.
+
+Additionally the following packages and tools have been used:
+
+* All Systems:
+  - See [GlueGen's HowToBuild](https://jogamp.org/gluegen/doc/HowToBuild.html)
+  - [OpenAL-Soft](https://openal-soft.org/) ([github repo](https://github.com/kcat/openal-soft/))
+
+* Windows:
+  - [CMake 3.15.2](https://cmake.org/download/)
+  - OpenAL Soft: Audio-Backends: WinMM, DirectSound, WASAPI, WaveFile, Null
+
+* GNU/Linux:
+  - cmake
+  - OpenAL Soft: OpenAL: PipeWire, PulseAudio, ALSA, OSS, SndIO (linked), WaveFile, Null
+```
+     apt-get install cmake autoconf \
+             libpipewire-0.3-dev \
+             libpulse-dev libpulse0:amd64 libpulse0:i386 pulseaudio \
+             libsndio-dev \
+             libasound2-dev libasound2:amd64 libasound2:i386
+```
+ On Debian 11 Bullseye, use bullseye-backports `apt -t bullseye-backports install libpipewire-0.3-dev`
+ to have libpipewire-0.3>=0.3.23, i.e. version 0.3.65.
+
+* Android/Linux:
+  - cmake
+  - OpenAL Soft: Audio-Backends: PipeWire, OpenSL, WaveFile, Null
+
+* OSX
+  - OSX 10.2 or later
+  - OSX Developer Tools Xcode
+  - CMake 3.15.2 <https://cmake.org/download/> 
+    and install the commandline tools <https://stackoverflow.com/questions/30668601/installing-cmake-command-line-tools-on-a-mac>
+  - OpenAL Soft: Audio-Backends: CoreAudio, WaveFile, Null
+
+JOAL requires the GlueGen workspace to be checked out as a sibling
+directory to the joal directory. 
+See GlueGen's HowToBuild <https://jogamp.org/gluegen/doc/HowToBuild.html>
+
+## Directory Organization:
+```
+make/           Build-related files and the main build.xml
+src/            The actual source for the JOAL APIs.
+src/test/       A couple of small tests
+build/          (generated directory) Where the Jar and DLL files get built to
+www/            JOAL project webpage files
+```
+
+## GIT
+JOAL can be build w/ openal-soft, which is a git submodule of JOAL.
+This is the default for our JogAmp build on all platforms.
+
+Cloning [and pulling] JOAL incl. openal-soft 
+can be performed w/ the option '--recurse-submodules'.
+```
+   > cd /home/dude/projects/jogamp/
+   > git clone --recurse-submodules git://jogamp.org/srv/scm/joal.git
+   > cd joal ; git pull --recurse-submodules
+```
+ 
+## JOAL Build Instructions:
+Change into the joal/make directory
+```
+   > cd /home/dude/projects/jogamp/make/
+```
+
+To clean: 
+```
+   > ant clean
+```
+
+To build:
+```
+   > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar
+```
+
+To build docs:
+```
+   > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar javadoc
+```
+
+To test:
+```
+   > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar runtests
+```
+
+Instead of properties, you may also use environment variables, 
+see GlueGen's HowToBuild <https://jogamp.org/gluegen/doc/HowToBuild.html>.
+
+## Contact Us
+- JogAmp             [http://jogamp.org/](http://jogamp.org/)
+- JOAL Web           [http://jogamp.org/](http://jogamp.org/joal/)
+- Forum/Mailinglist  [http://forum.jogamp.org/](http://forum.jogamp.org/)
+- Repository         [http://jogamp.org/git/](http://jogamp.org/git/)
+- Wiki               [https://jogamp.org/wiki/](https://jogamp.org/wiki/)
+- Maintainer         [https://jogamp.org/wiki/index.php/Maintainer_and_Contacts](https://jogamp.org/wiki/index.php/Maintainer_and_Contacts)
+- Sven's Blog        [https://jausoft.com/blog/tag/jogamp/](https://jausoft.com/blog/tag/jogamp/)
+- Email              sgothel _at_ jausoft _dot_ com
+
+## Acknowledgments
+Original JOAL and Sound3D authors
+
+- Athomas Goldberg
+- Wildcard
+- Java Games Initiative
+- Software Advanced Technologies Group
+- Sun Microsystems
+
+Since roughly 2010, JOAL development has been continued
+by individuals of the JogAmp community, see git log for details.
+
diff --git a/README.txt b/README.txt
deleted file mode 100644
index c1c52e5..0000000
--- a/README.txt
+++ /dev/null
@@ -1,122 +0,0 @@
-Project: com.jogamp.openal.* & com.jogamp.openal.sound3d.*
-Purpose: Open Source Java Bindings for OpenAL and Object-Oriented 3D sound toolkit
-License: See LICENSE.txt
-Author:
-    -- JOAL/Sound3D API Original Author
-        Athomas Goldberg
-        Wildcard
-        Java Games Initiative
-        Software Advanced Technologies Group,
-        Sun Microsystems
-        (see git log)
-    -- This file updated 08/19/2003 by Ole Arndt <ole at sugarshark dot com>
-    -- This file updated 11/23/2003 by Gregory Pierce <[email protected]>    
-    -- This file updated 12/21/2005 by Kenneth Russell <[email protected]>
-    -- This file updated 02/15/2014 by Sven Gothel <[email protected]> (see git log)
-    -- This file updated 05/17/2023 by Sven Gothel <[email protected]> (see git log)
-
-Introduction:
-=============
-
-The JOAL Project hosts a reference implementation of the
-Java bindings for OpenAL API, and is designed to provide
-hardware-supported 3D spatialized audio for applications written
-in Java.
-
-This project also hosts the Sound3D Toolkit, a high level
-API for spatialized audio built on top of the OpenAL bindings.
-This toolkit is designed to provide access to all the features
-of OpenAL through an intuitive, easy to use, object-oriented
-interface.
-
-
-Build Requirements:
-===================
-
-This project has been built under Win32, GNU/Linux, Android/Linux and MacOS. 
-
-Check GlueGen's HowToBuild <https://jogamp.org/gluegen/doc/HowToBuild.html>
-for basic prerequisites.
-
-Additionally the following packages and tools have been used:
-
-* All Systems:
-  -- See GlueGen's HowToBuild <https://jogamp.org/gluegen/doc/HowToBuild.html>
-  -- OpenAL <https://openal-soft.org/>
-
-* Windows:
-  -- CMake 3.15.2 <https://cmake.org/download/>
-  -- OpenAL Soft: Audio-Backends: WinMM, DirectSound, WASAPI, WaveFile, Null
-
-* GNU/Linux:
-  -- cmake
-  -- OpenAL Soft: OpenAL: PipeWire, PulseAudio, ALSA, OSS, SndIO (linked), WaveFile, Null
-     
-     apt-get install cmake autoconf \
-             libpipewire-0.3-dev \
-             libpulse-dev libpulse0:amd64 libpulse0:i386 pulseaudio \
-             libsndio-dev \
-             libasound2-dev libasound2:amd64 libasound2:i386
-
-     On Debian 11 Bullseye, use bullseye-backports `apt -t bullseye-backports install libpipewire-0.3-dev`
-     to have libpipewire-0.3>=0.3.23, i.e. version 0.3.65.
-
-* Android/Linux:
-  -- cmake
-  -- OpenAL Soft: Audio-Backends: PipeWire, OpenSL, WaveFile, Null
-
-* OSX
-  -- OSX 10.2 or later
-  -- OSX Developer Tools Xcode
-  -- CMake 3.15.2 <https://cmake.org/download/> 
-     and install the commandline tools <https://stackoverflow.com/questions/30668601/installing-cmake-command-line-tools-on-a-mac>
-  -- OpenAL Soft: Audio-Backends: CoreAudio, WaveFile, Null
-
-JOAL requires the GlueGen workspace to be checked out as a sibling
-directory to the joal directory. 
-See GlueGen's HowToBuild <https://jogamp.org/gluegen/doc/HowToBuild.html>
-
-Directory Organization:
-=======================
-
-  -- make           Build-related files and the main build.xml
-  -- src            The actual source for the JOAL APIs.
-  -- build          (generated directory) Where the Jar and DLL files get built to
-  -- javadoc_public (generated directory) Where the public Javadoc gets built to
-  -- unit_tests     A couple of small tests
-  -- www            JOAL project webpage files
-
-GIT
-====
-
-JOAL can be build w/ openal-soft, which is a git submodule of JOAL.
-This is the default for our JogAmp build on all platforms.
-
-Cloning [and pulling] JOAL incl. openal-soft 
-can be performed w/ the option '--recurse-submodules'.
-
-   > cd /home/dude/projects/jogamp/
-   > git clone --recurse-submodules git://jogamp.org/srv/scm/joal.git
-   > cd joal ; git pull --recurse-submodules
- 
-JOAL Build Instructions:
-===================
-
-Change into the joal/make directory
-   > cd /home/dude/projects/jogamp/make/
-
-To clean: 
-   > ant clean
-To build:
-   > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar
-To build docs:
-   > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar javadoc
-To test:
-   > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar runtests
-
-Instead of properties, you may also use environment variables, 
-see GlueGen's HowToBuild <https://jogamp.org/gluegen/doc/HowToBuild.html>.
-
-Release Info:
-    Initial Release:  This release contains an implementation of the Java
-    bindings for OpenAL, as well as the Sound3D Object-Oriented toolkit for games.