The indexer recurses through subdirectories. So if your menu structure looks like this::

DOS Games\ Adventure\ 1981\ 1982\ 1983\

...they will all get picked up by the indexer as long as you specify DOS Games as the source directory.

Acceptable File Types ^^^^^^^^^^^^^^^^^^^^^

Each program you want to process with the TDL must be self-contained in a single file. This typically means that all files that make up a single program (.EXE files, data files, etc.) be contained in a .zip file. However, you can process individual .COM and .EXE files as long as they don't require additional files. For example, the freeware game Flightmare (1984) only came as a single FLIGHT.COM file; it doesn't require any other files to run, so you can feed FLIGHT.COM directly to TDL without first putting it in a .zip file.

You can also feed non-program files to TDL, such as .TXT text files, GIFs, whatever. They'll be copied over as well, and if the appropriate handler exists on the target system, it will be used to "launch" those files as well. (See "Handling additional file types" elsewhere in this documentation.)

Step Two: Copy to the vintage system

Using any method you feel comfortable with, copy the entire contents of the output directory you specified over to your vintage DOS system, being careful to preserve the directory structure.

Instructing the user on copying files from a modern system to a vintage system is beyond the scope of this documentation, but here are a few pointers to get you started:

• Removable hard drives: You can use a Compact Flash card instead of a physical IDE drive with a cheap CF-to-IDE adapter; then all you need to do is insert it into your modern system with a CF card reader to do the copy. For very old systems that can't use IDE drives, there are homebrew ISA hard drive adapters that use CF cards directly; search the internet for "XTIDE Compact Flash" to find a few examples.

• TCP/IP: Install a network card that has a supported DOS packet driver, then install and use some sort of transport to copy the files over. This can be Microsoft LAN Manager, Novel Netware, etc., or a simpler and faster option like Mike Brutman's mTCP suite. If your system can load programs into upper memory, you can also get away with running MS LANMAN resident, and just access your files as a driver letter over the network.

• CD or DVD: Burn everything to a CD or DVD and just run from there.

While a serial or parallel cable can also work to copy files over (like LapLink, FastLynx, INTERLNK/INTERSVR, etc), the speed of a serial or parallel cable is extremely slow compared to the above methods and is generally not recommended unless you have no other choice.

Step three: Launch the menu program

On your vintage system, navigate to the directory you copied over and type TDL to launch the menu. Once the menu appears, use the arrow keys to navigate to the software you want to launch, and hit enter. The software will then run, and when it exits, you'll be returned to the menu to make another selection.

If the software you copy over is in compressed archives (ie. .ZIP files), the menu is smart enough to decompress an archive into a cache directory before trying to launch it. (It is also smart enough to not decompress an archive if it already exists in the cache.)

Additional Features ^^^^^^^^^^^^^^^^^^^

The TDL has some additional features that help with navigation and execution:

• Pressing any letter will jump to the first title starting with that letter
• Pressing F2 will mark/unmark a title as a "favorite", and you can use CTRL-F to toggle the title display between all titles and only favorites

Press F1 while in TDL to display a complete list of keys and functions.

The TDL swaps itself out of low DOS RAM before a program needs to run, and restores itself after the program has finished executing. By use of this swapping mechanism, the TDL does not "steal" any low DOS RAM away from programs that need to run.

The TDL has been successfully tested with 32-bit protected-mode programs that require a DOS extender (such as DOS4GW).

Configuring TDL

TDL, out of the box, does not need to be configured. If you want to configure it to your liking, such as specifying multiple source directories (to get past the DOS 2G partition limit), forcing a specific location for the cache directory, using a high-res VESA text mode, etc. then edit the TDL.INI and HANDLERS.INI files. Both .INI files contain a description of what they do.

TDL.EXE also has some command-line options to control how it operates:

/h Print a summary the most current set of command-line options. /c Set 43-line (EGA) or 50-line (VGA) mode. (If you need more lines than that, see TDL.INI for VESA options.) /r Instructs TDL that it resides on read-only media (ie. CDROM or DVDROM) and that it should not try to write anything to its local filesystem. This disables "favorites" as well as writing the debug log to disk. /d Print excessive debugging messages during initialization. Used for troubleshooting only. /f Always use fast display routines on all CGA systems. This may cause "snow" or display corruption on true CGA adapters.

Handling Additional File Types

TDL uses a "handlers" system to determine what to do with a file when the user requests lauching it. When a file is selected, TDL looks in HANDLERS.INI to determine what should be done with that particular file.

You probably won't need to touch HANDLERS.INI. Out of the box, it is configured to do the following:

• Launch .EXE or .COM files
• Decompress .ZIP and .ARC files, and launch programs inside them
• Run BASIC .BAS files with GWBASIC or BASICA
• Write raw image formats (.360, .720, etc.) to a blank floppy in drive A:
• Display .TXT and .NFO files

If you'd like to configure TDL to handle something less common, such as decompressing uncommon file types (.ARJ, etc.), viewing pictures, etc., then you'll need to add their file extensions and associated utility programs to HANDLERS.INI. Consult HANDLERS.INI itself for documentation.

Contributing to the TDL

The author welcomes contributions and enhancements, especially in the form of the python indexer. Quick cheat-sheet for those who have never contributed to a github open-source project before:

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request

This guide may be helpful: https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/

Design Requirements For New Features

The following constraints are in place:

• Any python code must be 3.x, as the indexer already uses some 3.6+ features.
• The DOS launcher must be able to run on an 8088 system with MDA or better video

If your new feature is optional and won't break the above constraints (for example, you want to add mouse support to the DOS launcher), that's fine. Any pull request that breaks the above constraints will not be accepted.

If you want to add a feature that breaks compatibility with older systems, check with me before working on it, as there is likely a way to implement what you want while still staying compatible with the 8088.

Building TDL

Building the TDL is not required to use it! This section is only for those who want to hack on the code and contribute back to the project -- however, be prepared to get (re)acquainted with DOS compilers and tools!

Languages ^^^^^^^^^ TDL is written in Turbo Pascal 7.0, with a small amount of assembler thrown in for speed or utility. Knowledge of Pascal is required to extend TDL. Knowledge of assembler is helpful, but not required.

Libraries ^^^^^^^^^ TDL is not 100% self-contained; it uses some support libraries and units to provide functionality like CUI/TUI primitives, userspace swapping, and stream extensions. Ensure you have both https://github.com/MobyGamer/TPLibs and https://github.com/MobyGamer/UNITS available in your source path.

Compilers and Tools ^^^^^^^^^^^^^^^^^^^ Borland Pascal 7.0, which includes both Turbo Pascal as well as Turbo Assembler/linker/debugger, is available via your favorite search engine. A full installation of it is rumored to be included in ftp://ftp.oldskool.org/pub/misc/xtfiles.rar but this is unconfirmed.

Compiler/Assembler restrictions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You must always ensure that the code you write will execute on any x86 system, including the 8088. Don't use 80186+ instructions such as PUSHA, POPA, ENTER, LEAVE, etc. In Turbo Pascal, always ensure $G-,N-,E- to turn off 80286 code generation, 8087 code generation, and 8087 emulation respectively. One of TDL's design goals is the ability to work on any IBM PC or compatible.

Frequently-Asked Questions

Usage

Can I use this with emulators such as DOSBox? Yes, but if you are using an emulator, there are much better launchers and front-ends you can use, such as Metropolis Launcher <https://metropolis-launcher.net/>_ . TDL was developed to solve issues specific to running large archives of software directly on vintage computers, and as such, doesn't have as many features as modern emulator front-ends.

Where can I find collections of DOS games to run on my vintage system? Any internet search can help you. As of this writing, "DOS game collection" produced 3.2 million hits in google. If you'd like to support commercial entities that legally sell vintage games, some choice exists, with Good Old Games <http://www.gog.com/> being the most popular as of 2024.

I'm using TDL with DOSBOX and it won't unzip some of the larger games, claiming there is not enough free space in the cache to extract them. Some DOSBOX variants default to limiting the amount of free space to 16MB regardless of how much is actually free. To get around this, mount the drive with the option " -freesize [size]". For example::

mount C C:\dosgames -freesize 1024

Extending the code

Why was this written in Pascal and assembler, instead of something more popular like C? The principle developer of the TDL prefers the Turbo Pascal 7 IDE when writing code on, and for, 8088-based systems. The TP7 IDE is a powerful development environment that allows an 8088-based IBM PC with 640KB to perform symbolic debugging with conditional breakpoints, watch/inspect/change variables at runtime, and watch CPU registers change line by line, all without leaving the IDE. Also, TP7 makes it easy to speed up sections by either writing in-line assembler directly in the pascal source, or linking to external assembler objects (which can also be traced and debugged within the IDE, with the same features previously listed).

Turbo Pascal 7 isn't free; will you switch to FreePascal at some point? The formal commit of 8086 code generation in FreePascal in 2017 now makes this possible, so it is conceivable the project will move to FreePascal once all proposed features have been added and the codebase is frozen.

Philosophy

Emulators are much easier to use than maintaining original hardware. Why not just use emulators? Both hardware and emulators are useful for running programs for which the hardware environments are no longer sold or maintained. Emulators are unparalleled for their accessibility. But, as good as emulators are, the only way to truly research a historical work is to experience it on the hardware that work targeted.