
f2html.pl User Manual

November 27, 2001


-----------------------------------------------------------------------------

CONTENTS

About This Program
Usage
Requirements
Installation
Problems under Windows and Dos
Examples
Release History
Contacting the Author
ToDo

-----------------------------------------------------------------------------

About This Program

F2html.pl is a command line utility written in perl to generate html files by
searching recoursivly through directories.

With the program some additional files are delivered:
  - Copyright: the gnu public licence
  - hex.dat: a file containing hex code to correct links
  - 1.conf: an example configfile
  - repl.dat: an example replacement file (for windows users)

-----------------------------------------------------------------------------

Usage

perl f2html.pl [options]

	-h, --help                  Show this screen and exit
	-k, --mkconf                Use an assistant to write a config file
        -o, --os       (win,unix)   Default "unix", otherwise windows
        -b, --dbfile   <file>       Write database to a file for searching it        
        -m, --m3u      <file>       Write a m3u file
        -t, --html     <file>       Write a html file
        -a, --http     <name>       Define the http address for url
        -r, --remove                Remove id3tags
        -i, --mp3info               Use mp3info for html output
        -e, --ext                   Remove file extensions in html output 
        -f, --filesize              Use filesize for html output
        -c, --check    <ext>        Select files by their extension (e.g. mp3)
        -z, --skip     <number>     Skip n elements of directories/names
        -p, --conf     <file>       Use a config file
        -w, --hexfile  <file>       File with hexcode for replacements in links
        -q, --nocs                  Do sorting not case sensitive
        -j, --statfile <file>       Write statistics to file
        -d, --dir      <directory>  Define the (multiple) directory(ies) the 
                                    mp3s are stored in   
	-g, --sql      <file>       filename to store sql table in (only for mp3s!)  
        -y, --replace  <file>       Name of replacement file; in the file use 
                                    string_1 string_2 to transform string_1 
                                    into string_2; special characters like a 
                                    backslash have to be preceeded by a 
                                    backslash "\"
        -s, --seperate <path>       Write seperate html files for every 
                                    character 
                                    (this option is a little bit buggy)
        in the config file it is possible to use the command
        x=, exec=      <param>      Execute system command. 

-----------------------------------------------------------------------------

Requirements


F2html.pl runs under all systems where perl is installed. The program was
tested und Windos 98 and Linux.

You can download perl from http://www.perl.org


Furthermore the skript needs two perl modules. (1) getopt that is normally
part of every perl distributuion, and (2) Mp3Info. You can download Mp3Info
from http://search.cpan.org. Under Unix systems like linux you can use the
installation skripts. Under Windows the perl module "Info.pm" has to be 
copied to the perl libary directory: "path were perl is installed"\lib\. 
There you have to create a directory called MP3. Into this directory you have 
to copy the file Info.pm.


-----------------------------------------------------------------------------

Installation

F2html.pl does not need to be installed. Just copy it to a directory and 
execute it from this directory, or copy to a directory and set the 
PATH variable.


-----------------------------------------------------------------------------

Problems under Windows and Dos

The shell under Windows is limited to 256 characters. So sometimes it is not
possible to define all option wanted. Therefor I inplemented the option to
use a config file, in that all parameters can be written. 


-----------------------------------------------------------------------------

Examples

If you want to create a custom config file, then execute

  perl f2html.pl -k

If you want to use a configfile, just type 

  perl f2html.pl -p file.conf 

where file.conf is your configfile. 

With the command line
 
  perl f2html.pl -d /home/nikolei/download1 -d /home/nikolei/download2 
                 -o unix -t /home/nikolei/content.html

the script searches recursively through the two directories defined by 
"-d", builds a file list, sorts this filelist alphabetically by the filename,
not by the name of the directory they are stored in, and writes the list to
a html file defined by "-t". The options "-b"  and "-m" can be used 
additionally or instead of "-t" to write a database file, that can be 
used by the script mp3search.pl, or to create a playlist.

With the command line
 
  perl f2html.pl -d /home/nikolei/download1 -d /home/nikolei/download2 
                 -o unix -s /home/nikolei

the script does nearly the same as before. The difference is, that a
seperate html file for every different first character of the file names
is written into the directory defined by "-s". For example, the following
files could be created:

  /home/nikolei/1.html
  /home/nikolei/a.html
  /home/nikolei/b.html
  /home/nikolei/t.html

where "1.html" contains a list of all files beginning with a "1",
"a" contains all files beginning with an "a" (for example aa.dat,
ab.dat, ac.dat ...), and so on. 


With the command line
 
  perl f2html.pl -d /home/nikolei/download1 -o unix -c mp3 -c MP3
                 -t /home/nikolei/content.html

the script writes out a html file, but uses not all files it has found, but 
only files that have the suffix "mp3" or "MP3".

With the command line
 
  perl f2html.pl -d /home/nikolei/download1 -o unix -i -f -e
                 -t /home/nikolei/content.html

the script writes out a html file. For this html file it uses additional 
information, if the file is a mp3 file (the "-i" option), i.e. the length 
of the track, the bitrate, the frequency, and if it is variable encoded.
Defining "-f" option, the html file contains the size of each file, and 
given the "-e" option the file suffix is deleted in the html file. 

With the command line
 
  perl f2html.pl -d /home/nikolei/download1 -w /home/nikolei/hex.dat
                 -o unix -t /home/nikolei/content.html

the script writes out a html file, and corrects special characters 
by changing them to their hex code. Simply define a file where the hex code
is stored in by using option "-w". The file containing the hex code for 
replacements must have the following form:
  
   %C0
   %E0
   %C1
  
Thuch a substitution might be necessary, because you cannot download files
containing special characters in their file name. Using such a hexfile the 
name of a link will be replaced so that a file is downloadable. For example:

  <a href="namal.mp3">namal.mp3</a>

becomes

  <a href="%C0namal%E0.mp3">namal.mp3</a>  

With the command line
 
  perl f2html.pl -d /home/nikolei/download1 -y /home/nikolei/repl.dat
                 -o unix -t /home/nikolei/content.html

the script writes out a html file, and corrects special patterns in the 
link, if option "-y" is used. The patterns and their substitution have to be 
stored in a file. The option can be used for path name substitution. Windows
user have to be aware of using two backslashes instead of one! For example,
the file repl.dat contains the following replacement table:

  c:\\music\\good /mp3c
  c:\\music\\bad  /mp3d

Then the pathname for a file stored in the directory c:\music\good will be 
corrected to /mp3c. This option is usefull if you want to setup a webserver
for your files.

With the command line
 
  perl f2html.pl -d /home/nikolei/download1 -a http://www.yourdomain.net
                 -o unix -t /home/nikolei/content.html

the sript writes out a html file and uses a http address for the links. 
It might be necessary do use this option together with option "-z"!

With the command line
 
  perl f2html.pl -d /home/nikolei/download1 -z 2
                 -o unix -t /home/nikolei/content.html

the sript writes out a html file, and skips the first 2 directories when 
writing the link. For exmaple

  <a href="/home/nikolei/download1/name.mp3">name.mp3</a>

becomes 

  <a href="/download1/name.mp3">name.mp3</a>

This option is usedful if you have stored your file in subdirectory of 
the path where your homepage is stored in and if you want to put the files
for download into the net. It might also be useful for samba/windows shares etc.

Given the option -q in the commandline, the program does not work case 
sensitive any more. For example, it groups lower case and upper case 
characters of the same type together. So "a" and "A" are the same.


The command line
 
  perl f2html.pl -d /home/nikolei/download1 -q
                 -o unix -t /home/nikolei/content.html
                 -j /home/nikolei/statistics.html

forces the program to do the sorting ertc. not case sensitive (-q option)
and to write a statistics html file to /home/nikolei/statistics.html. The 
other things are done on the same way as for the command line before

To write a sql data file just type
 
  perl f2html.pl -d /home/nikolei/downlod1 -o unix 
                 -g /home/nikolei/sqldata.sql
		 
Only files that end with "mp3" or "MP3" make their way into the database file!
The sql data consists of the following mp3 file information: file name, song title,
artist, album, year, comment, genre, directory, filezize, modification time,
vbr, bitrate, frequency, minutes, and seconds.

The command line
 
  perl f2html.pl -d /home/nikolei/download1 -r -o unix

simply removes every id3tag it finds.

It has to be noted, that the option can be used together. For example

  perl f2html.pl -d /home/nikolei/download1 -d /home/nikolei/download2
                 -o unix -q -r -i -f -e -z 3 -y /home/nikolei/repl.dat
                 -w /home/nikolei/hex.dat -c MP3 -c mp3          
                 -b /home/nikolei/content.db -m /home/nikolei/content.m3u
                 -t /home/nikolei/content.html -a http://mydomain.net/music      

Because it is too much to write if you want to update the generated files
more frequentliy, you can write everything into a config file. In the config 
file you can use the same option, but they have to be written in a slighly 
different way:

  -d /home/nikolei/download1 

becomes

  d=/home/nikolei/download1 

and so on. An additional option is available if you are using a config file:
"x=". with this option, that you can use several times, it is possibles to 
make system calls. For example, if you want to copy the html file to an
other directory, then just type:

  x=copy /home/nikolei/content.html /home/nikolei/public_html/content.tml

It might be also useful to write a seperate script (under dos a so called
batch file). This file could execute the script f2html.pl several times 
using different config files. This can be useful if you want to handle some 
directories in a different way. 

Or you can use the batch option to updaten or create you aql database:
  
  x=mysql mp3 < sqldata.sql


Fortunately, everybody is free to modify the html code within the script 
to adjust the output. 

-----------------------------------------------------------------------------

Release History

This is the first release of f2html.pl, and called:
  
  f2html.pl 01-20001127
        Changes:
         - Initial release

  f2html.pl 02-20010117
        Changes:
         - The manual has been updated.
         - The option -c has been updated. Now this option can be used more 
           than only one time. So one is able to select file by different 
           extensions.

  f2html.pl 03-20010628
        Changes:
         - Some checks and corrections for pathnames
         - Only existing characters are written out at the top of a html 
           file
         - Rewrite of sum of files and sizes. Important for writing 
           seperate html files for every character 
         - The option -q has been implemented and allows for doing the 
           procedures in a non case sensitive way
         - The option -j has been implemented. A html file with statistics 
           can be written out. 

  f2html.pl 04-20011127
        Changes:
	 - Now f2html comes with a new version of Info.pm (version 0.91)
	   from MP3-Info-0.91 by Chris Nandor	   
	 - Minor Bugfixes
	 - New option to create sql database
	 - New option to create a config file
	 
-----------------------------------------------------------------------------

Contacting The Author 

You you have found bugs, need help, or have some ideas for further 
development of the program, feel free to mail me

  nikolei.steinhage@uni-bielefeld.de
  
-----------------------------------------------------------------------------  

Todo

There are still a lot of things to do. But first of all I have to write a 
better manual with a lot of examples in it. To me, this seems very necessary,
bacause some users may encounter problems using this program. Some feature
like sql-interface, advanced sorting and grouping have to be implemented.
Change all command line examples to config file examples.




