first commit - moved from local dev to git

tools/mxplay/doc/using.txt

@@ -0,0 +1,393 @@
+mxPlay User's Manual
+====================
+
+1.1 Introduction to mxPlay 1.0.0
+--------------------------------
+
+Phew... so it really happend... if you're reading this text it means our
+little child called mxPlay is finally released.
+
+Everything started with the one post on our local Atari list for Czech and
+Slovak Atari fans, where one guy has complained he isn't able to use great
+MegaPlayer under CT60 and that is bad there's no decent player for so many
+formats... Some guy on dhs.nu came with the idea to make plugins to FalcAMP,
+but it seems FalcAMP development is quite slow (I asked Frost about release
+date but he's hunting bugs so no release date is know yet :( ) and even no
+plugin API is known...
+
+Final 'ass-kick' was Xi's reply to my comment "Did you see the new GemAce and
+GemMod? They looks pretty nice!" in style "Yeah, that's nice, but hell, I
+don't want to have nice player for mods, nice player for ace songs and
+another nice one for mp3s.. I want one, good looking player with the
+playlist!". Oh yes, here it really started.
+
+After some discussion we came to the point "That's damn easy to make it! We
+have many free replay routines for various formats, we'll make some lame gem
+interface to it, hmm, maybe playlist will be a little bit tricky, but this
+could be done in 1-2 weeks!". So, 3 months passed very fast and here you are,
+mxPlay player with playlist, skins, plugins, open code and the coolest user
+features from the plenty of other players ;)
+
+Maybe you're wondering what the hell we did make on this for about 3 months.
+Firstly, I'm democoder. I didn't know nearly anything about GEM. So getting
+touch with this kind of programming was a new experience for me. Secondly,
+every day we come with new ideas what should we add, my TODO list was (and
+still is) full of things to implement...
+
+1.2 Introduction to mxPlay 2.0
+------------------------------
+
+Unbelievable, nearly exactly seven years later and I'm updating final bits of
+the new version :) Frankly, I considered this project dead as there was very
+little of interest from Atari users and I personally don't use Atari for
+daily work anymore so I didn't really miss a software like this.
+
+But then again, some magic has happend :) Some time in December I found a
+website with Turrican II modules and I realized that I have no clue how to
+replay this on my Linux PC. So I googled a little and found the XMP project.
+Out of curiosity I read its API documentation and I immediately realized how
+easy this would be to port over to our platform.
+
+In about the same time someone asked on dhs about some DSPMOD usage example
+and ggn reminded him about mxPlay...
+
+All of this somehow led me to the feeling that I should at least try to make
+the project compilable again and perhaps I could try to hack an XMP plugin,
+as a proof of concept.
+
+Of course, I coded a simple XMP player in like few hours. So only some tweaks
+to Makefile, code a wrapper to the player and we're done, right? Right :)
+Immediately as I started mxPlay, I saw a bug here and there and a better way
+how to do this and that and ... fuck, I spent 2 months only fixing bugs.
+There's very few new features, if any. Only bugfixes, bugfixes, bugfixes. For
+some crazy reason I decided also to finish all the remaing plugins (as it's
+clear nobody would do that), that led to another delays and frustration.
+
+But, in the end... I've caught really a lot of bugs, improved stability a
+lot, I can't understand how the player could work at all before. Now, if you
+use only ASAP and XMP plugins, you can even remove the "Super" flag from
+mxPlay.prg, it's 100% OS friendly and safe even under memory protection. This
+is a thing never seen on Atari before ;-) And bonus - you've got a FireBee
+version, too.
+
+Current state is a reasonable compromise between functionality and release
+date. Most of the code is still (7 years old!) mess, it made me puke several
+times. A lot of things could have been done but I really wanted to get rid of
+it. If there's any volunteer ...
+
+1.3 Introduction to mxPlay 2.1
+------------------------------
+
+Few weeks after the alpha phase (called 'release' in public ;)) I'm happy to
+bring you the la(te)st version of mxPlay. Generally, not much to mention:
+
+- 'Play' initiates playback even if no file is selected on startup
+- all dialogs are properly iconified and reopened
+- plugin path is now set separately for FireBee and ARAnyM, no more messing
+  with copy and rename
+- XMP plugin is compiled against the latest version, MTMs and DMFs yet work
+- oh and by the way, a plugin for full featured MPEG-1 audio layer I, II and
+  III is included ;)
+
+Btw, thanks to the MPG123 plugin I discovered that sample frequency in ARAnyM
+is set wrong all the time, i.e. all ASAP and XMP modules I had heard were about
+10% slower :))) Oh my.
+
+2. Features
+-----------
+
+- modern user interface
+
+- fully skinable GUI
+
+- compatible from the simple TOS to the latest XaAES
+
+- best d&d / va-start / long name support you've ever seen
+
+- memory protection friendly
+
+- multitasking support, windowed dialogs
+
+- universal plugin API which allows you to take any kind of replay routine
+  and to adapt it to mxPlay
+
+- it's free!
+
+- open development, anyone can contribute / bugfix
+
+- recursive directory/file adding with autodetection for supported formats
+
+and a lot of more ...
+
+3. Windows
+----------
+
+Here you'll find brief description of each mxPlay's window.
+
+3.1 Panel
+
+The heart of mxPlay. You don't need to top the panel, button will be
+activated even on untopped panel.
+
+3.1.1 Play
+
+Play the current song. If no song was selected it will be played either the
+first file in playlist or the random song (in the case 'Random' button was
+activated, see bellow)
+
+3.1.2 Stop
+
+Self-explaining.
+
+3.1.3 Pause
+
+Pause playing. Please note not every plugin supports this function. Click on
+this button again to continue playing.
+
+3.1.4 Previous Subsong
+
+Playback must be active to make this work (currently ASAP and SNDH plugin).
+
+3.1.5 Next Subsong
+
+Playback must be active to make this work (currently ASAP and SNDH plugin).
+
+3.1.6 Next Song
+
+Play the next song in the playlist.
+
+If you're at the end of playlist and the 'Repeat' button was activated (see
+bellow) as next file will be taken the first one.
+
+If 'Random' button was activated, next song will be choosen randomly.
+
+3.1.7 Previous Song
+
+Play the previous song in the playlist. Please note previous song will be
+played even in random mode, no random selection as done in Aniplayer!
+
+3.1.8 Playtime
+
+By clicking on the playtime you change time addition/substraction a la Winamp
+or XMMS. Please note that most of the plugins do not support time reporting
+so a hardcoded value is used (3 minutes). You can change this in mxplay.inf.
+
+3.1.9 Repeat
+
+Wrap to the begin of playlist when requested for the next song and we're on
+the last entry in the playlist.
+
+3.1.10 Random
+
+Activate random song selection. 'Repeat' button has no sense then.
+
+3.1.11 Mute
+
+Mute the playing. This function must be present in the plugin.
+
+3.1.12 Volume Slider
+
+Increase or decrease volume level. It even watches for current sound system
+status so you can try to play with volume in some CPX and you will see the
+effect :)
+
+3.1.13 Playlist
+
+Open/close playlist.
+
+3.1.14 Module Info
+
+Open/close module info dialog.
+
+3.1.15 Plugin Info
+
+Open/close plugin info dialog.
+
+3.1.16 About
+
+Open/close information about application.
+
+3.2 Playlist
+
+The best playlist for our little Atari :)
+
+3.2.1 Add file
+
+Add file(s) to the playlist. Please note your fileselector has to support
+Selectric and/or MagiC/XaAES fileselector protocol to select more than one
+file. Except the Selectric and MagiC/XaAES it does Hugo for example.
+
+3.2.2 Add Directory
+
+Add director(y|ies) to the playlist. It's fully recursive operation so, yes,
+you can take your music partition and open it in mxPlay! If your fileselector
+doesn't allow you to select exact directory, open such directory, clear
+"filename" field and press RETURN.
+
+3.2.3 Select All
+
+Select all entries in the playlist. If you press SHIFT key, it will do
+inverse operation - i.e. deselecting selected files and vice versa.
+
+3.2.4 Remove
+
+Remove selected files. No stupid questions, so beware.
+
+3.2.5 Load Playlist
+
+Load .m3u file. Yes, that's the file from winamp and others :)
+
+3.2.6 Save Playlist
+
+Save .m3u file.
+
+3.3 Module Info
+
+Here you can find some information about currently played module as provided
+by plugin. Enabled (not shaded) arrows mean you can scroll left and/or right
+to see the full text (better is to resize window I think ;)
+
+3.4 Plugin Info
+
+Similar to Module Info but you're allowed even enter some values. It could be
+simple on/off flag or numerical/text parameter. If there are up and down
+arrows you can scroll with them (sorry no resize at this time...)
+
+3.5 About
+
+Simple about dialog. Here you can read the license under which is mxPlay
+released and the current version.
+
+4. Keyboard Shortcuts
+---------------------
+
+4.1 (SHIFT) CTRL + O
+
+Open (and add to playlist) file(s) or (with SHIFT) director(y|ies).
+
+4.2 CTRL + Q
+
+Quit application.
+
+4.3 SPACE
+
+Pause playing.
+
+4.4 CTRL + P
+
+Start playing.
+
+4.5 CTRL + S
+
+Stop playing.
+
+4.6 (SHIFT) UP ARROW
+
+If in playlist, move up (1 entry or whole page with SHIFT)
+
+4.7 (SHIFT) DOWN ARROW
+
+If in playlist, move down (1 entry or whole page with SHIFT)
+
+4.8 (SHIFT) CTRL + A
+
+Select all entries in the playlist or (with SHIFT) make opaque to the current
+state.
+
+4.9 DELETE
+
+Delete selected entries from the playlist.
+
+4.10 INSERT
+
+Activate 'Repeat' button.
+
+4.11 CLR HOME
+
+Activate 'Random' button.
+
+4.12 (SHIFT) TAB
+
+Open/close Module info or (with SHIFT) Plugin info dialog.
+
+4.13 HELP
+
+Open/close About dialog.
+
+4.14 UNDO
+
+Activate 'Mute' button.
+
+4.15 NUM /
+
+Change the current skin. Change is done in realtime but only if there's no
+playback.
+
+4.16 NUM (
+
+Play previous song in the playlist.
+
+4.17 NUM )
+
+Play next song in the playlist.
+
+4.18 NUM *
+
+Open/close playlist.
+
+5. Supported protocols
+----------------------
+
+5.1 ARGV
+
+You can assign some file type, e.g. *.mp2 to mxPlay and then just click on
+the mp2 files and mxPlay will open & play such file. The filename could be
+even with spaces, bigger than 8+3 characters etc. Please note, not all
+desktops support this, see file BUGS for details.
+
+5.2 VA-START
+
+If you go in the way described in 5.1 you can double-click on the file during
+song playing and mxPlay will update its playlist and begin to play this file.
+
+5.3 Drag & Drop
+
+You can take files, directories and even hard disk icons and place it onto
+mxPlay, everything will go as you expect! Full support for long names.
+
+6. Thanks
+---------
+
+At first I would like to thank to all people who decided to publish their
+source codes. Without them there's no mxPlay. So for others - please, support
+free software, release your source code - it helps all of us. Very good
+example is zView, really good work, Zorro!
+
+Next I have to thank Xi, my never-tired-for-another-bugreport friend ;),
+without your usefull hints about application architecture and without your
+massive support I doubt I finish mxPlay in this look and functionality.
+
+Also thanks to people on MiNT list, they helped me sometimes when I was in
+total dark :)
+
+And at last but not least I have to thank YOU, Atari fan, you're still using
+Atari computers!
+
+7. Contact
+----------
+
+Don't forget mxPlay is FREE SOFTWARE that means everyone can contribute to
+and/or bugfix the current version. If you can't code you can make skins. If
+you can't make GEM dialogs, you can test mxPlay, spell-check documentation,
+think about new features, ... help is always welcome.
+
+You can reach me 7 days of week at:
+
+miro dot kropacek at gmail dot com
+
+Xi is the author of skins, the most of plugins and he is the very good
+beta-tester, you can reach him at:
+
+xi at napri dot sk
+
+... happy playing!