HTM(P3)L 1.2 ReadMe

HTM(P3)L 1.2 ReadMe

Contents

Introduction

HTM(P3)L is a Windows tool which was originally designed to quickly create an HTML view of a collection of MP3 files. As a new feature in version 1.2, HTM(P3)L now also lists shortcut files of Internet Explorer and more data types will come in future releases.

HTM(P3)L generates a single file called "index.html" in a selected folder which can be viewed with any modern browser. All suitable files in the folder and its subfolders are sorted by track number or alphabetically and can be opened with a simple mouse click. There is no easier way to provide access to remote files over HTTP or share your favorite collections in a local network or in the WWW.

Quick Start

If you have the Microsoft .NET Framework 1.1, you already have all you need to run HTM(P3)L. Take a look at the Download and Installation section if you need help to get the Framework or HTM(P3)L on your computer.

Now you have HTM(P3)L: launch it with a double click on the app's icon (the colorful icon). If everything's fine, the main program window with the title HTM(P3)L 1.2 appears and we are ready to start working.

Click on the Browse... button on the top right of the window and choose a directory that contains MP3 files. You may also type in a path name directly in the Root directory text box, or drop a folder in it from Windows Explorer. If you don't have many MP3's, you can also try out HTM(P3)L on your Internet Explorer links collection. To do so, select the location of your Internet Explorer Favorites folder as described above and check the IE Shortcut Files box in the middle of the window. Note that the directory you select must exist and be writable for HTM(P3)L to create the HTML file. If you choose a directory in a read-only drive like a CD-ROM, or if you don't have the privileges to modify the chosen location, it won't work.

Click on the Start button down on the right (just one time! no double click!). If the option Open HTML file when done is checked, after a few seconds the new generated HTML document opens in your browser so you can see it immediately. While HTM(P3)L is working, you can stop it at any time by clicking again on the Start button which automatically turns into a Stop button.

As a taste of what's coming with future release 2.0, HTM(P3)L 1.2 provides a few options to change the look of the HTML files you create. Click on HTML Options button on the middle right and try to change some colors. See what happens when you start HTM(P3)L again and re-create the HTML file.

When you are finished working with HTM(P3)L, you may close it like any other Windows application by clicking on the Close button (the X-shaped button on the top right corner of the window).

See the Usage section for a complete description of all available features.

What's New in this Version?

Changes in HTM(P3)L 1.2

Changes in HTM(P3)L 1.1

Requirements

HTM(P3)L runs against the Microsoft .NET Framework 1.1 which requires Windows 98, Windows ME, Windows NT 4.0 with Service Pack 6a, Windows 2000, Windows XP or Windows Server 2003 and Internet Explorer 5.01 or later. More information about the .NET Framework is available on Microsoft's website: http://msdn.microsoft.com/netframework/.

Download and Installation

The latest version of this software can be downloaded at http://www.ftq.de. Just go to the Software section and look for HTM(P3)L. No automatic installer is provided: if you downloaded a .zip archive, unpack it to a folder on your machine; if you got an .exe, double-click on the file to extract its contents. If you don't have the Microsoft .NET Framework 1.1 installed on your computer, you must get it from Windows Update before you can start using HTM(P3)L.

Usage

Double-click on the HTM(P3)L icon to open the main dialog window. In the text box labeled Root directory on the top of the window, type in the path of the directory where your MP3's or IE shortcuts are located. You may also drop a folder here from Windows Explorer or click on the Browse... button and select a location from the tree view. The list box remembers the eight last used folders: you can see them if you click on the button with the down arrow right of the text box.

Don't forget to select the correct option in the What to list group: choose MP3 Audio Files or IE Shortcut Files, whichever kind of files you want to list. Because files of any type may be mixed up together in the same directory, HTM(P3)L has no way to retrieve this information automatically.

Once you have selected the location and type of your collection, click on the Start button. If the option Open HTML file when done is selected, after a few seconds the new generated HTML document opens in your browser so you can see it immediately.

While performing longer operations, the status label and progress bar at the bottom of the window are constantly updated to show you how much of the job has been done already. You can stop HTM(P3)L during a job at any time by clicking on the Stop button (middle right at the same place of the Start button).

The option Ask before overwriting refers to the output HTML file. While it is always safer to ask the user before overwriting an existing document, you may want to turn this option off when updating a number of listings in different directories. When this option is turned on, you'll be prompted every time an existing document is about to be overwritten.

The HTML Options... button opens a dialog that provides control over several advanced formatting options for the output listing. These options are not quite finished yet, although they all do their work fine. If you experiment and change some of these settings you'll get an impression of the capabilities of the next HTM(P3)L version, HTM(P3)L Version 2.0.

When you are finished working with HTM(P3)L, you close it like any other Windows application by clicking on the Close button on the window's top-right corner.

How it Works

Basically, HTM(P3)L is not much more than a text-processing program with a graphical user interface. The hard work, that is the essence of HTM(P3)L, is to extract a title along with numbering information from a file of a well known type: this information is indispensable to create the text for a link to the file, and sort the links alphabetically or numerically, when appropriate, before printing out the whole listing to an HTML document. Although many aspects of the elaboration are strictly related with the type of files being listed (MP3's have track numbers, but shortcuts do not!), HTM(P3)L's approach is identical in all cases: remove redundant expressions from file names checking for commonly used delimitation patterns to isolate interesting information. Note that only the file name is involved in this important process, not the file contents: information contained in the tags of an MP3 file is quite invisible to HTM(P3)L; a text document with the extension ".mp3" is treated as a valid MP3 music file and no particular check of any kind is performed. Actually, this system is not very satisfactory and it's very likely to be improved in future releases of this software.

As the whole file name parsing algorithm mentioned above is quite complicated and may become yet more complicated in newer versions, we are not going to examine it here in detail. The aim of this section is just to provide you with an overview of what happens behind the scene and point out the main characteristics of HTM(P3)L's core design.

First of all, HTM(P3)L scans the directory structure of the root folder to locate and examine all suitable files in all subdirectories. Only when this first phase is completed, generation of the final HTML listing begins.

Directory names are very important as they often contain text elements, such as the title of the album or the name of the artist, which are common to all songs in that directory and its subdirectories. In case of IE shortcuts, the directory name may contain for example a word or expression that is repeated as a common qualifier in the title of the shortcuts contained in the directory.

To understand some of the details of HTM(P3)L's behavior, we'll take a look at two examples taken from real scenarios, the one with MP3's and the other with IE shortcuts.

For instance, let's suppose you have in your root folder a subdirectory named "NIN - Pretty Hate Machine" with the following files:

02 -- Terrible Lie.MP3
10 - Nine Inch Nails - Ringfinger.Mp3
cover.jpg
nin - 01) head like a hole.mp3
NIN - 04 - Sanctified.mp3
NIN - Pretty Hate Machine - 06 - Kinda I Want To.mp3
NINE INCH NAILS - 08. THAT'S WHAT I GET.mp3
Nine Inch Nails - 09 - The Only Time.mp3
pretty_hate_machine_-_05_-_something_i_can_never_have.mp3
Sin.mp3

As you can imagine, this folder contains the album titled "Pretty Hate Machine" of the artist "Nine Inch Nails". Each track is stored as an MP3 file, and there is also a picture of the CD cover in form of a JPG file. If you use a P2P application to download self-encoded MP3's from different users, your files will surely have quite confused names, so a "stupid" computer will need some intelligence to correctly recognize title and track number in those names. As we said, this is HTM(P3)L's main job. The output of HTM(P3)L for such a directory will look like this (don't click on the links, they don't work here)-:

NIN - Pretty Hate Machine

  1. head like a hole
  2. Terrible Lie
  3. (missing track)
  4. Sanctified
  5. something_i_can_never_have
  6. Kinda I Want To
  7. (missing track)
  8. THAT'S WHAT I GET
  9. The Only Time
  10. Ringfinger

We can see here, the relative path name of the directory is always shown on the top of the list. Only files with the extension ".mp3" are listed. Underscores in the titles are treated as white spaces by the filtering engine. The strings "NIN" and "Pretty Hate Machine" are filtered away from the song titles regardless of case. "Nine Inch Nails" is recognized as the extended form of the acronym "NIN", so it also gets filtered. Track numbers are matched on a predefined set of commonly used patterns. Files with no recognizable track number are listed alphabetically after the numbered tracks.

While this example illustrates HTM(P3)L's skill in isolating confusedly decorated titles in file names, you should take care of naming your mp3 collection in a clearly readable, standardized way. Typing errors, repeated or altered word sequences or unusual separators are very likely to fool HTM(P3)L's filtering engine. On the other hand, a tidy naming convention will make it easier for you to find what you're looking for and manipulate your collection.

The most common format for a directory name containing music files is "<Artist> - <Album>" (note the white spaces before and after the hyphen in the middle). If the tracks come from different artists, or if the name of the artist is already expressed in a parent folder, you may want to name your directory just like the album name. If the tracks come from the same artist, but from different albums, your directory will be probably called like the artist is.

The best way to name a music file is probably: "[<Artist> - ][<Album> - ][<TrackNr> - ]<Title>". In this scheme, just the song title is required; all other elements are optional. Generally, you should only omit an information if it does not apply, or if it is already contained in the name of the directory or a parent directory. The hyphen between two white spaces is the most used separator.

Let's see another example now: a folder with IE shortcut files and a few subdirectories.

News
|   Wired News.url
|   Yahoo! News - Front Page.url
|
+-->The New York Times
|       The New York Times International.url
|       The New York Times on the Web.url
|       The New York Times Technology.url
|
+-->CNN.com
|   |   CNN.com.url
|   |
|   +-->Technology
|   |       CNN.com - Technology.url
|   |       CNN.com - Technology-Internet.url
|   |
|   +-->More
|          CNN.com - Travel.url
|          CNN.com - Education.url
|          CNN.com - Entertainment.url
|
+-->Last Hour

The section in the output file for such a directory tree looks like this:

News

News/CNN.com

News/CNN.com/More

News/CNN.com/Technology

News/The New York Times

We see here, there are no track numbers to list or sort. The parent directory is always listed before its subdirectories. Subdirectories that belong to the same parent are sorted alphabetically. Empty directories or directories with no suitable files are not displayed at all. As with MP3's, redundant elements are cut off from file names to improve readability.

To learn more about HTM(P3)L, try it out yourself. If you have any questions or suggestions, please contact the author. HTM(P3)L is still a growing project, so many of the thing discussed above may change in future releases.

Author, Copyright

HTM(P3)L 1.2 was released on 8th December 2003 and is Copyright © 2003 Francesco Trotta.

HTM(P3)L is provided as it is with no warranty of any kind. You are welcome to redistribute this software.

You can contact the author by sending an e-mail to: ftq@ftq.de.

You are also invited to visit the author's home page on the web at http://www.ftq.de where you can get the latest version of HTM(P3)L.