home *** CD-ROM | disk | FTP | other *** search
/ Sound, Music & MIDI Collection 2 / SMMVOL2.bin / DOS / SS_PLAY / SHELL10.ZIP / SHELL.DOC < prev    next >
Encoding:
Text File  |  1995-04-11  |  16.0 KB  |  360 lines
  1.  
  2.                         ╓──╖
  3.                         ╙──╖ ╥ ╥ ╓── ╥   ╥
  4.                            ║ ╟─╢ ╟─  ║   ║
  5.                         ╙──╜ ╨ ╨ ╙── ╙─╜ ╙─╜
  6.                        ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡
  7.                          -- Version 1.0 --
  8.  
  9.  
  10.    Table of contents
  11.    [===============]
  12.  
  13.         [1] . . . . . . . . . . . . . . . . . . About Shell
  14.         [2] . . . . . . . . . . . . . . . . . . Shell Configuration Files
  15.           [2.1] . . . . . . . . . . . . . . . . SHELL.CFG
  16.           [2.2] . . . . . . . . . . . . . . . . SHELL.FMT
  17.         [3] . . . . . . . . . . . . . . . . . . General usage
  18.           [3.1] . . . . . . . . . . . . . . . . Command line parameters
  19.           [3.2] . . . . . . . . . . . . . . . . General keys
  20.           [3.3] . . . . . . . . . . . . . . . . Tag-related keys
  21.           [3.4] . . . . . . . . . . . . . . . . Mouse functions
  22.         [4] . . . . . . . . . . . . . . . . . . Important notes
  23.         [5] . . . . . . . . . . . . . . . . . . Credits, Contact Information
  24.  
  25.  
  26.  
  27.    1: About Shell
  28.    [============]
  29.  
  30.         Shell is a music file front-end that supports virtually any
  31.         command line music file player in existence.  Shell comes
  32.         preconfigured for Protracker MODs, Scream Tracker 3 S3Ms,
  33.         Farandole Composer FARs, Ultratracker ULTs, Multitracker Module
  34.         MTMs, Dual Module Player AMFs, Scream Tracker 2 STMs, Composer
  35.         669 669s, Noisetracker NSTs, X-Tracker DMFs, Fast Tracker 2 XMs,
  36.         Midi files, Windows WAV files, and raw audio SND files.  You
  37.         also have the ability to add more formats with the configuration
  38.         files.
  39.  
  40.         Shell will do you the labor of searching inside ZIP files as
  41.         well to find files that match any extensions supplied in the
  42.         format listing.  This feature can be turned off if not required.
  43.  
  44.         An added feature requested by flap / Capacala is to read 4Dos
  45.         DESCRIPT.ION files.  This feature only works if the file is not
  46.         archived in a ZIP file.
  47.  
  48.         Shell also comes preconfigured for a variety of players,
  49.         including Inertia Player 1.2, CapaMod 2.09, Cubic Player 0.96l,
  50.         Fast Tracker 2's PMP player, GLX 2.12, Edlib 1.05a, Renaissance
  51.         music player 1.15b, DMP 3.01, Future Crew MusicDisk Player,
  52.         X-Play, GusMod 2.11, the Ultrasound WAV/SND player, and the
  53.         Ultrasound MIDI player.  As with file formats, adding any other
  54.         players is very simple with the configuration files.
  55.  
  56.         For more information on the configuration files, read on to
  57.         chapter 2.
  58.  
  59.  
  60.    2: Configuration Files
  61.    [====================]
  62.  
  63.         Shell is highly configurable via two configuration files,
  64.         SHELL.CFG, and SHELL.FMT.  SHELL.CFG is the basic shell
  65.         configuration file, while SHELL.FMT is the configuration file
  66.         for the various file formats.  Both files use an easy WIN.INI
  67.         style, which makes for quick and simple modification.
  68.  
  69.      2.1: SHELL.CFG
  70.      [------------]
  71.  
  72.           This is the file which contains all of your players and all of
  73.           the shell variables.  The file contains many comments and is
  74.           fairly self-explanatory, so we won't go into very much detail
  75.           here in the document.
  76.  
  77.           DefDir                - the default directory for scanning
  78.           WorkDir               - where the files will be unarchived to
  79.           MaxFiles              - the max files Shell will scan for in a dir
  80.           Case                  - the case in which filenames are displayed
  81.           DoubleClickSpeed      - speed of mouse double click
  82.           ArchiveSearch         - whether or not to search ZIP files
  83.           Pkzip                 - name of pkzip program
  84.           Pkunzip               - name of pkunzip program
  85.           Loop                  - loop when play tagged list toggle
  86.           Tagdelay              - # of seconds to wait in between tag file play
  87.  
  88.           Usually the default settings will do for most of those.  Now,
  89.           on to the player setup.  The basic setup for a player is four
  90.           lines long, as follows:
  91.  
  92.           [Name of Player]
  93.           Mask=<masks supported>
  94.           Player=<player executable filename>
  95.           Options=<command line parameters>
  96.  
  97.           The first line is for the name of the player, enclosed in
  98.           brackets.  The second line is the list of masks defined in
  99.           SHELL.FMT that the player supports.  The third line is the
  100.           player executable name.  A full path is not required if the
  101.           executable is in the path.  The forth line is for any command
  102.           line parameters that you would like to pass to this particular
  103.           player.  Players are separated by a blank line.  Up to 20
  104.           player entries are supported.
  105.  
  106.      2.2: SHELL.FMT
  107.      [------------]
  108.  
  109.           This file contains the information for all of the music file
  110.           formats that will be scanned for.  Once again, this file has
  111.           many comments and is almost self-explanatory, so we'll only
  112.           touch on it a bit here.  The basic format for a file format is
  113.           5 lines long:
  114.  
  115.           [Name of Format]
  116.           Format=<filename extension of format>
  117.           HeaderOfs=<position in file to find "title" of song>
  118.           HeaderLen=<length of the "title">
  119.           Mask=<letter of mask for SHELL.CFG player setup>
  120.  
  121.           The first line is for the name of the format, enclosed in
  122.           brackets.  The second line is the extension of the filename
  123.           for that format, ie: for Scream Tracker 3 files, the extension
  124.           would be S3M.  HeaderOfs is the position in the file where the
  125.           title of the song is located.  If you're not sure, omit this
  126.           entry and also omit the HeaderLen entry.  If the format
  127.           doesn't have a "title" (such as WAV or SND files), also omit
  128.           those two entrees.  Mask is a single letter which is used to
  129.           reference the format in the SHELL.CFG file in the "Masks="
  130.           line of a player.  File formats are separated by a blank line.
  131.           Up to 30 format entries are supported.
  132.  
  133.  
  134.    3: General Usage
  135.    [==============]
  136.  
  137.         The following section describes the various keyboard/mouse
  138.         maneuvers that will let you do everything in shell.
  139.  
  140.      3.1: Command Line Parameters
  141.      [--------------------------]
  142.  
  143.           The basic usage of shell is:
  144.           SHELL [options] [drive:\path]
  145.  
  146.           Where [options] can be any combination of:
  147.                 -cl             (lowercase filenames)
  148.                 -cu             (uppercase filenames)
  149.                 -f<#>           (max # of files to scan for)
  150.                 -m<x>           (doubleclick speed, x = 0 to 2)
  151.                 -p<#>           (set current player to #)
  152.                 -a              (enable archive searching)
  153.                 -n              (disable archive searching)
  154.  
  155.           [drive:\path] is the full drive and pathname of the dir that
  156.           you want to scan.
  157.  
  158.           All of these parameters override the configuration file.
  159.  
  160.      3.2: General Keys
  161.      [---------------]
  162.  
  163.           F1                    : help screen
  164.  
  165.           Up/Down               : scroll through file list
  166.  
  167.           Ctrl-Up/Ctrl-Down     : scroll through file list while highlight
  168.                                   remains on the same filename
  169.  
  170.           Alt-Up/Alt-Down       : scroll through file list while highlight
  171.                                   remains in the same position on the screen
  172.  
  173.           PgUp/PgDn             : move one page up or one page down
  174.  
  175.           Ctrl-PgUp/Ctrl-PgDn   : move to absolute start/end of file list
  176.  
  177.           Home/End              : move to top/bottom of current screen
  178.  
  179.           Enter                 : play highlighted file/change directory
  180.  
  181.           [, ]                  : change current player
  182.  
  183.           Ctrl-Left             : back one dir in the hierarchy (cd ..)
  184.  
  185.           Alt-V                 : toggle 25/50 line mode
  186.  
  187.           Alt-S                 : shell out to operating system
  188.  
  189.           Alt-D                 : delete file/archive
  190.  
  191.           Alt-L                 : rescan current directory
  192.  
  193.  
  194.      3.3: Tag-Related Keys
  195.      [-------------------]
  196.  
  197.           Alt-T                 : tag all files
  198.  
  199.           Alt-U                 : untag all files
  200.  
  201.           Alt-R                 : randomize tagged list
  202.  
  203.           Alt-P                 : play tagged list
  204.  
  205.           Alt-O                 : resume aborted tag-play
  206.  
  207.           <, >                  : trace through tagged list
  208.  
  209.      3.4: Mouse Functions
  210.      [-------------------]
  211.  
  212.           File Display Area:
  213.              Click on any filename to select
  214.              Doubleclick on any filename to play or change directory
  215.              Right click on filename to tag/untag
  216.              Click/Drag on elements of scrollbar as usual
  217.  
  218.           Left or Right click on player info box to increase/decrease
  219.              player number
  220.  
  221.           Click on "Quit" in upper right corner to do just that
  222.  
  223.  
  224.    4: Important Notes
  225.    [================]
  226.  
  227.         If you happen across any bugs, it is not my liability if any
  228.         damage is done.  I have done my very best to make this the most
  229.         failsafe program I can.  Please report any ill occurances you
  230.         find to me by e-mail or however.
  231.  
  232.         If you have any suggestions or want to let me know how much you
  233.         like/dislike this program, feel free to send love/hate mail to
  234.         me.  I love mail, or catch me on IRC on the channels #coders and
  235.         #trax by the nickname mrdata.
  236.         
  237.         I do not ask for money for Shell.  It is a freeware product, or as I
  238.         would have it, a cardware product, but you can send money if you think
  239.         it is really think it's worth it.  All I request is a small notice
  240.         that you have Shell and whatever you want to say about it.  In future
  241.         versions of Shell I plan to:
  242.         
  243.            - add a sample ripper to be used as a player (not built in)
  244.            - add ARJ/LZH archive handling (was planned but never got it done)
  245.            - use a graphical mouse cursor in text mode
  246.            - above 1450 files and more info of the files
  247.            - ability to search multiple directories and show in same display
  248.         
  249.         Like I said, if you have any suggestions for additions or changes to
  250.         Shell, my ears are open for them.
  251.  
  252.  
  253.    5: Credits/Contact Information
  254.    [============================]
  255.  
  256.         Shell was programmed by Shawn Poulson from August '94 and
  257.         finally finished late March '95.  It started as my personal DMPC
  258.         wanna-be and eventially surpassed it in many ways so I was motivated
  259.         to work on it more until I thought it was good enough to release to
  260.         the public.  Throughout the developement I am in debt to the help from
  261.         Brazil (John Baduini) for suggesting better ways to improve Shell and
  262.         finding bugs.  I also thank Rich Geldreich for help and tips on
  263.         correctly handling the mouse and extended keyboard input.
  264.  
  265.         Shell has been coded primarily in large model C and assembly.
  266.         Shell has been optimized for speed wherever possible.  (and
  267.         convenient :)
  268.  
  269.         The group Continuum is a demo/game programming group, members are:
  270.            Mr. Data        - Coder / PR
  271.            Brazil          - Coder / Group Clown
  272.            Mozart          - Coder / Musician
  273.            Warlock         - Graphics / Concept
  274.            ArchAngel       - not quite sure yet... hmm
  275.  
  276.         We are for hire if requested, otherwise we have demos or our
  277.         game we develop (top secret).  We do bbs intros or crack loaders
  278.         and stuff.
  279.  
  280.         Personal greets go to: (alphabetized)
  281.            All Continuum members - blah...
  282.            Aqualung - When will I ever get to see you again
  283.            Brazil - For writing most of these docs
  284.            Chris McComas - True definition of a dumb jock
  285.                            (just checking if you actually read this far)
  286.            Pure Evil - Perhaps we will code together some time
  287.            Ram Junky - Too bad you sold your computer for college education
  288.                        You were a great coder/gfx pal
  289.            Thomas Wagner - For PD EXEC ems/xms/disk swap code library
  290.            White Shadow - Is the game going ok?  We need to talk more.
  291.  
  292.         Additional greets to:
  293.            The 'net surfers in #coders who are always on 24 hours a day.
  294.            The drunken idiots in #trax who never talk about music but always
  295.               have something interesting to say. (Hadji!!!) w00 w00!
  296.            The dudes on local Citadel bbses like Gateway and Potluck for their
  297.               humor and inspiration.
  298.            Friends on Red Sector A bbs, and the cool sysop By-Tor.
  299.               Call 609-983-6800 (28.8k/dual, 15 ringdown nodes) full internet
  300.               access, huge bbs file/message sections, and great group chats.
  301.               telnet to: bungle.rsabbs.com
  302.               or MUD to: xanadu.rsabbs.com
  303.  
  304.         Programming was done using the following tools:
  305.            - 486 DX2/66 and 486 SuX/25 machines
  306.            - 1 gig and 170meg IDE drives
  307.            - Cheap 14" monitor that shorts out my computer from time to time,
  308.              automatically rebooting it (donate money to me for a new 17"er)
  309.            - Gravis Ultrasound w/1meg (gotta listen to music, you know!)
  310.            - USR sportster 14.4 (to IRC with!)
  311.            - 101 key enhanced keyboard (a must)
  312.            - Farside 1995 calendar (tee hee)
  313.            - Boxer 6.00 (text editor everyone should use! e-mail for info)
  314.            - Borland C++ 3.1
  315.            - Turbo Assembler 3.1
  316.            - Thelp 3.0
  317.            - PkLite 1.12 (or Shell would've been over 80k)
  318.            - 4Dos 5.5 (great command.com replacement)
  319.            - M.C. Escher mouse pad
  320.            - 2 pound rubberband ball (*boing*)
  321.            - Descent (coding break)
  322.            - GE Clock/radio (for reminding me I'm up too late coding)
  323.            - DosRef printed manuals, great reference guide for everything
  324.            - 2Col 5.0d (to print DosRef!)
  325.            - Star NX2430 24-pin printer (to use 2Col with!)
  326.  
  327.         My code directory for Shell looks like:
  328.  
  329.  Volume in drive C is DOESNTSUCK     Serial number is D8ED:ACDB
  330.  Directory of  c:\code\shell\*.*
  331.  
  332. .             <D>   ..            <D>   1.bat          1K   1.txt          1K
  333. 1speed.bat     1K   2.bat          1K   appnote.txt   34K   checkpat.h     3K
  334. checkpcl.obj   2K   chiseler.asm  17K   chiseler.h     1K   chiseler.obj   8K
  335. compat.h       2K   control.inc   12K   cursor.asm     1K   cursor.h       1K
  336. cursor.obj     1K   dist.lst       1K   drives.asm     5K   drives.h       1K
  337. drives.obj     1K   emm.c          1K   emm.h          1K   emm.obj        2K
  338. exec.c        12K   exec.h         9K   exec.obj       8K   flatten.bat    1K
  339. funcs.h       40K   gcursor.asm   18K   gcursor.h      1K   gcursor.obj    5K
  340. help.asm       3K   help.h         1K   help.obj       2K   keybd.h        2K
  341. keysort.asm   18K   keysort.bas    7K   ksort.asm      3K   ksort.h        1K
  342. ksort.obj      1K   mouse.asm     19K   mouse.h        3K   mouse.inc      4K
  343. mouse.obj     11K   qsort.asm     37K   qsort.bas      1K   qsort.inc     16K
  344. scrn.c         7K   scrn.h         2K   scrn.obj       8K   shell.c       70K
  345. shell.cfg      2K   shell.doc     17K   shell.dsk      8K   shell.exe     45K
  346. shell.fmt      2K   shell.h        1K   shell.lnk      1K   shell.map      2K
  347. shell.obj     70K   sorttyp.asm   29K   spawncl.obj    5K   textdrv.c     10K
  348. yo             2K   
  349.        581,959 bytes in 63 files and 2 dirs    2,326,528 bytes allocated
  350.     81,133,568 bytes free
  351.     ^^^^^^^^^^ on my gig drive... :-(
  352.  
  353.         Mr. Data (Shawn Poulson) can be contacted by the following addresses:
  354.  
  355.         Snail Mail:     645 Oxford Drive
  356.                         Maple Shade, NJ  08052
  357.                         USA
  358.         Internet:       spoulson@cygnus.rsabbs.com
  359.  
  360.