Migrate ASCII docs to markdown and update contents where necessary.
authorAlexander Koenig <alex@lisas.de>
Fri, 24 Jun 2016 18:09:42 +0000 (20:09 +0200)
committerAlexander Koenig <alex@lisas.de>
Fri, 24 Jun 2016 18:09:42 +0000 (20:09 +0200)
AUTHORS
INSTALL
README
README.PERFORMANCE
THANKS
TODO

diff --git a/AUTHORS b/AUTHORS
index f63aa8c..1e43515 100644 (file)
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,16 +1,22 @@
-terminatorX AUTHORS:
+terminatorX AUTHORS
+===================
 
-Author:                        Alexander König <alex@lisas.de>
+Author
+------
 
-Contributors:
-licmak.awk:            Christian <eleet@altern.org>
-tX_wavfunc.c-patch:    "Andrew C. Bul+hac?k" <acb@zikzak.net>
-(removed) MK II icon:  Michael Kahl <m.kahl@student.hu-berlin.de>
-new startup switches:  Josh Steiner <joschi@eds.org>
-misc fixes and enhancements:
-                       Adrian Reber <adrian@lisas.de>
-piped Ogg support:     Matthew Evans <activesx@hotmail.com>
-MIDI interface:                Arthur Peters <amp@singingwizard.org>
+Alexander König <alex@lisas.de>
 
-The lowpass filter is based on a description:
-reso_lop.txt:          Paul Kellett <paul.kellett@maxim.abel.co.uk>
+Contributors
+------------
+
+- licmak.awk: Christian <eleet@altern.org>
+- tX_wavfunc.c-patch: "Andrew C. Bul+hac?k" <acb@zikzak.net>
+- (removed) MK II icon: Michael Kahl <m.kahl@student.hu-berlin.de>
+- new startup switches: Josh Steiner <joschi@eds.org>
+- misc fixes and enhancements:
+- Adrian Reber <adrian@lisas.de>
+- piped Ogg support: Matthew Evans <activesx@hotmail.com>
+- MIDI interface: Arthur Peters <amp@singingwizard.org>
+
+The lowpass filter is based on a textual description:
+- reso_lop.txt: Paul Kellett <paul.kellett@maxim.abel.co.uk>
diff --git a/INSTALL b/INSTALL
index b7d4a98..fefef49 100644 (file)
--- a/INSTALL
+++ b/INSTALL
-terminatorX INSTALL:
-Copyright (C) 1999-2008 by Alexander König <alex@lisas.de>
-http://terminatorX.org
-
-Note: As of Version 3.70 you need to have LADSPA installed to compile
-terminatorX. To get LADSPA visit http: http://www.ladspa.org
-
-Quickstart:
------------
-
-       If you want enhanced audio-file support or optimization don't
-       "quickstart" but read the rest of this file.
-
-       If you just cant wait any longer try:
-       > ./configure
-       > make install
-
-Step 1: Configure terminatorX.
-------------------------------
-
-       If you want your compiler to optimize the binary, you need to set your
-       environment variable CFLAGS to your needs BEFORE you run ./configure.
-
-       for example:
-       if use bash: > export CFLAGS="-O2"
-       with tcsh:   > setenv CFLAGS "-O2"
-
-       Optionally you might want to add your platform specific tunings (-m* 
-       stuff).
-
-       All of the following configure options can be either enabled with
-       --enable-option or disabled with --disable-option.
-
-       The configure Options:
-       
-               File support options:
-               ---------------------
-               
-               All of these are enabled by default. Nevertheless the configure
-               script checks for the availability of the helper application
-               and if it's not found disables support for it. Check the
-               terminatorX homepage for links to those apps if you don't have
-               them - or check your distribution first, AFAIK all bring these
-               tools nowaday.
-               
-               --enable-mad
-               
-               This will make terminatorX use the MPEG Audio Decoder library if 
-               it's detected. This allows terminatorX to load mp3 files
-               significantly faster than with the mpg123 method. Additionally
-               terminatorX will find out about the sampling rate of an mp3 file
-               and adjust the playback speed accordingly.
-               
-               --enable-vorbis
-               
-               This will make terminatorX use the OGG Vobris libraries to load
-               OGG files directly. This method has the same advantages over 
-               loading through ogg123 as the "mad" method has over loading 
-               through mpg123.
-               
-               --enable-audiofile
-               
-               This enables the use of libaudiofile on loading audio files.
-               The library supports a wide range of common audio file formats
-               (eg WAV/AIFF/AU etc) therefor its use highly recommended.
-               
-               --enable-wav
-               
-               This enables the builtin wav routines. They load 16Bit/44Khz
-               MONO RIFF/WAV files only but they do that significantly faster
-               than using sox. If these routines fail and sox support is
-               enabled, terminatorX will try to load the file with sox as 
-               a fallback. Disable them only if they don't load your files
-               correctly.
-               
-               --enable-sox
-               
-               This enables sox support. As sox can load nearly any audio file
-               it makes sense to use it. You have to have sox installed of 
-               course.
-               
-               --enable-mpg123
-               
-               This enables mpg123 support. If you want to be able to load mp3
-               files keep this option enabled. You have to have mpg123
-               installed of course.
-               
-               --enable-ogg123
-               
-               With this option you can turn on/off support for Ogg Vorbis
-               soundfiles. This requires ogg123 (Version >= 1.0RC2) and
-               sox to be installed. 
-               
-               Other options:
-               -------------
-               
-               --enable-capabilities
-               
-               Allows running terminatorX suid-root to gain realtime scheduling
-               (see README.PERFORMANCE).
-               
-               --with-docdir
-               
-               If you intend to package terminatorX this flag will allow
-               terminatorX to find the XML documentation in order to display
-               it online.
-               
-               --disable-libxml2
-               
-               If you've got libxml V2 installed but you want terminatorX to 
-               use V1 instead, use this to disable libxml V1.
-
-               --enable-debug
-               
-               This will cause terminatorX to display some debug messages on
-               your console. 
-               
-               Just as an example my configure line is (works with bash only):
-               > CFLAGS="-O3 -mathlon" ./configure 
-
-Step 2: Build the binary.
--------------------------
-
-       This one's easy:
-       > make
-       
-Step 3: Install the binary:
----------------------------
-
-       Just as easy:
-       > make install
-       
-       You need root privileges though. If you don't have them simply copy
-       the terminatorX-binary (in src/terminatorX) to a directory of your
-       choice and run terminatorX form there.
+terminatorX INSTALL
+===================
+
+Copyright (C) 1999-2016 by Alexander König <alex@lisas.de>
+https://terminatorX.org
+
+Quickstart
+----------
+
+If you want enhanced audio-file support or optimization don't
+"quickstart" but read the rest of this file.
+
+If you just cant wait any longer try:
+> ./configure
+> make install
+
+Step 1: Configure terminatorX
+-----------------------------
+
+If you want your compiler to optimize the binary, you need to set your
+environment variable CFLAGS to your needs BEFORE you run ./configure.
+
+for example:
+if use bash: > export CFLAGS="-O2"
+with tcsh:   > setenv CFLAGS "-O2"
+
+Optionally you might want to add additional tuning parameters for
+your target platform.
+
+All of the following configure options can be either enabled with
+--enable-option or disabled with --disable-option.
+
+The ./configure Options
+-----------------------
+
+### File support options
+
+All of these are enabled by default. Nevertheless the configure
+script checks for the availability of the helper application
+and if it's not found disables support for it. Check the
+terminatorX homepage for links to those apps if you don't have
+them - or check your distribution first, AFAIK all bring these
+tools nowaday.
+
+--enable-mad
+
+This will make terminatorX use the MPEG Audio Decoder library if
+it's detected. This allows terminatorX to load mp3 files
+significantly faster than with the mpg123 method. Additionally
+terminatorX will find out about the sampling rate of an mp3 file
+and adjust the playback speed accordingly.
+
+--enable-vorbis
+
+This will make terminatorX use the OGG Vobris libraries to load
+OGG files directly. This method has the same advantages over
+loading through ogg123 as the "mad" method has over loading
+through mpg123.
+
+--enable-audiofile
+
+This enables the use of libaudiofile on loading audio files.
+The library supports a wide range of common audio file formats
+(eg WAV/AIFF/AU etc) therefor its use highly recommended.
+
+--enable-wav
+
+This enables the builtin wav routines. They load 16Bit/44Khz
+MONO RIFF/WAV files only but they do that significantly faster
+than using sox. If these routines fail and sox support is
+enabled, terminatorX will try to load the file with sox as
+a fallback. Disable them only if they don't load your files
+correctly.
+
+--enable-sox
+
+This enables sox support. As sox can load nearly any audio file
+it makes sense to use it. You have to have sox installed of
+course.
+
+--enable-mpg123
+
+This enables mpg123 support. If you want to be able to load mp3
+files keep this option enabled. You have to have mpg123
+installed of course.
+
+--enable-ogg123
+
+With this option you can turn on/off support for Ogg Vorbis
+soundfiles. This requires ogg123 (Version >= 1.0RC2) and
+sox to be installed.
+
+--enable-suidroot
+
+When set, this option sets the setuid bits for the root user when
+installing the binary, note that this will require root privileges
+upon installation.
+
+## Other options
+
+--enable-capabilities
+
+Allows running terminatorX suid-root to gain realtime scheduling
+(see README.PERFORMANCE).
+
+--with-docdir
+
+If you intend to package terminatorX this flag will allow
+terminatorX to find the XML documentation in order to display
+it online.
+
+--disable-libxml2
+
+If you've got libxml V2 installed but you want terminatorX to
+use V1 instead, use this to disable libxml V1.
+
+--enable-debug
+
+This will cause terminatorX to display some debug messages on
+your console.
+
+Step 2: Build the binary
+------------------------
+
+This one's easy:
+> make
+
+Step 3: Install the binary
+--------------------------
+
+Just as easy:
+> make install
+
+Typically you will need root privileges to install in the standard prefix,
+if installing as root is not an option you can use the --prefix configure
+switch to install to another location.
diff --git a/README b/README
index 0841853..fb382dd 100644 (file)
--- a/README
+++ b/README
@@ -1,5 +1,5 @@
-terminatorX V3.90 README
-------------------------
+terminatorX v4.0.0
+==================
 
 Copyright (C) 1999-2016 Alexander König
 eMail: alex@lisas.de
@@ -12,8 +12,8 @@ WARNING: TerminatorX comes with ABSOLUTELY NO WARRANTY. This software is known
 to lockup X11 or cause other problems under rare conditions. Don't use
 it on production servers. You have been warned!
 
-Read that fine manual:
-----------------------
+Read that fine manual
+---------------------
 
     o ./INSTALL             - Information on installing terminatorX
     o ./README.PERFORMANCE  - Some hints on tuning terminatorX
index c984d32..dc34208 100644 (file)
@@ -1,31 +1,34 @@
+Tuning terminatorX' performance
+===============================
+
 There are several things you can do to improve terminatorX performance:
 
-1. Don't use fancy gtk+ themes
-2. Install suid root
-3. Compile an optimized binary
-4. Optimize your terminatorX setup
++ Don't use fancy gtk+ themes
++ Install suid root
++ Compile an optimized binary
++ Optimize your terminatorX setup
 
 In Detail:
 
-1. Don't use pixmapped nor other "fat" gtk+-themes.
----------------------------------------------------
+Don't use pixmapped nor other "fat" gtk+-themes
+-----------------------------------------------
 
 terminatorX involves quite some GUI activity, so it's desirable that drawing
-happens fast. Some gtk+ engines can slow down drawing signifcantly
+happens fast. Some gtk+ engines can slow down drawing signifcantly.
 
 2. Install suid root
 --------------------
 
 Note: Installing a program suid-root is always potentially dangerous. However,
 a program needs special privileges to acquire realtime scheduling (which 
-improves playback quality signifcantly). Since release 3.82 terminatorX provides
-only one method of running suid root:
+improves playback quality signifcantly). However, only when running suid-root
+terminatorX can acquire realtime scheduling priorty to avoid buffer underruns
+with low latency settings and the mouse motion events can be captured directly
+from the hardware improving scratching precision.
 
-- Linux' POSIX capabilities: when capabilities support is available at
-  compile time (requires libcap) terminatorX can make use of Linux' POSIX
-  capabilities. The binary has to be installed suid root but the program
-  will drop root privileges right on startup - after aquiring the CAP_SYS_NICE
-  capability.
+When running setuid-root, terminatorX makes use of Linux' POSIX capabilities:
+Right after start-up it acquires the CAP_SYS_NICE capabilty and accesses the
+Linux input interface before dropping root privileges for good.
 
 While the capabilities based approach seems much more secure than the approach
 that was previously implemented, it might still be exploitable. So, for 100%
@@ -35,13 +38,14 @@ suid root.
 3. Compile an optimized binary
 ------------------------------
 
-This issue is covered in the INSTALL file mostly. Setting good optimization
-flags is a good idea although this step will proabably have the least effect.
+This issue is covered in the seperate INSTALL file. Setting good optimization
+flags is a good idea although this step will proabably have the least effect
+and the defaults should be reasonable.
 
 4. Optimize your terminatorX setup
 ----------------------------------
 
 The default settings for the GUI updates provide good realtime feedback. This
-may cause problems on slower machines or evil gtk+-themes. If the GUI-thread
+may cause problems on slower machines or slow gtk+-themes. If the GUI-thread
 causes dropouts in the audio-engine you should increase the Update-Delay value 
 in the options dialog.
diff --git a/THANKS b/THANKS
index 2e25038..2b448a1 100644 (file)
--- a/THANKS
+++ b/THANKS
@@ -1,11 +1,12 @@
-terminatorX THANKS:
+terminatorX THANKS
+==================
 
 I'd like to thank:
 
 - All authors of: the GNU tools and libraries, the Linux kernel, XFree86,
-                  sox, mpg123, the wav-tools, gtk+ and TCP/IP. 
-                 It's obvious but: without their work there'd be no tX
-       
+  sox, mpg123, the wav-tools, gtk+ and TCP/IP.
+  It's obvious but: without their work there'd be no tX
+
 - All contributors (see AUTHORS)
 
 - All users who send feedback
diff --git a/TODO b/TODO
index 0a20889..3546cc6 100644 (file)
--- a/TODO
+++ b/TODO
@@ -1,15 +1,12 @@
-terminatorX TODO:
+terminatorX TODO
+================
 
 DISCLAIMER: I might implement some of these features in random order. You can 
 accelerate development of a certain feature by sending me a patch ;)
 
-- GTK3 port
-
-- Find DGA replacement as X11 is about to vanish
-
-- Stereo turntables
-  
-- Drop audio loaders use gstreamer-based streaming instead.
-
-- Implement a sequencer editor GUI to delete, copy & paste, edit event etc.
+* Individual turntable colours (to easily identify which controls belong to
+  which sample)
+* Stereo turntables
+* Drop audio loaders use gstreamer-based streaming instead.
+* Implement a sequencer editor GUI to delete, copy & paste, edit event etc.