
f2html.pl User Manual

Mar 13, 2003


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

CONTENTS

About This Program
Usage
Requirements
Installation
Problems under Windows and Dos
Examples
Changing html layout
Functions
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
  - utf.dat: a file containing utf code to correct links
  - 1.conf: an example configfile
  - repl.dat: an example replacement file (for windows users)
  - Info.pm: the perl module MP3::Info is written by Chris Nandor
  - README: this file
  - mp3table.sql: file containing the sql skeletton

Bugs: Doubtless many. Feel free to contact the author, but remember:
      I do not promise anything.
      nikolei.steinhage@uni-bielefeld.de

Disclaimer: - I do not support Perl, html, or any OS
            - I do not promise that this program does anything
            - this program may distroy all your data
            - I cannot promise that this program will not distroy
              all human civilization

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

Usage

perl f2html.pl [options]

	-h, --help                  Show this screen and exit
        -l, --fast                  Use fast sorting (experimental)
	-k, --mkconf                Use an assistant to write a config file
        -o, --os       (win,unix)   Default "unix", otherwise windows
        -n, --dublicates            Check for dublicates of files by their
                                    filename
        -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, --utf8     <file>       File with UTF-8 code 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 mp3 and ogg!)
        -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
	-R, --rename                renames mp3 and ogg file using their id3tag
	-B, --renameback	    renames files back using the file RENAME.bak	    			    
        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. But a version is also delivered with f2html.pl.
Under Unix systems like linux you can use the installation skripts. Or it
can be copied into a folder like "/usr/lib/perl5/site_perl/5.6.1/MP3".
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/utf8.dat
                 -o unix -t /home/nikolei/content.html

the script writes out a html file, and corrects special characters 
by changing them to their utf-8 code. Simply define a file where the utf-8 code
is stored in by using option "-w". The file containing the utf-8 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 utf-8 file 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. Note that both strings are seperated by ------>. There are no
spaces before or after any string!

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.

If you want to check for dublicates of you files you can add the dublicates option
(-n) to you command and the filenames that exist more than one time are
listed on stdout.
 
  perl f2html.pl -d /home/nikolei/downlod1 -o unix -n
                 -g /home/nikolei/sqldata.sql

An experimental (at least for the moment) option is fast sorting (option --fast or -l). 
It performs much better than the standard sorting in the program if you want to index 
a huge number of files or if you want to index mp3 files with their additional information.

  perl f2html.pl -d /home/nikolei/downlod1 -o unix -l
                 -t /home/nikolei/content.html


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

simply removes every id3tag it finds.

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

renames all files containing an id3tag (nomally mp3 and ogg files) by the conent of
the tag in the form:

  ARTIST - ALBUM - TRACKNUMBER - TITLE.mp3 
  
The information about what files have been renamed and how can be found in the 
file "RENAME.bak" in the f2html.pl-directory. This file is used when you want to rename
your files back, so that they get their original name. This option is  only useful for 
for renaming new files. It is not good to run it on files that have already a good
naming shema or that already have been renamed. 

This can be done using the command line 

  perl f2html.pl -d /home/nikolei/download1 -B -o unix


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

  perl f2html.pl -d /home/nikolei/download1 -d /home/nikolei/download2
                 -o unix -q -g -i -l -f -e -R -n -z 3 
		 -y /home/nikolei/repl.dat
		 -n /home/nikolei/mp3.sql -j /home/nikolei/stat.html
                 -w /home/nikolei/utf.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 frequently, 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 
  
  or
  
  dir=/home/nikolei/download1 

and so on. But be aware about that one or more spaces (e.g. at the end of the
line) do also belong to the filename. So when you get an error message like
"cannot open directory xxx" then it may be due to your rights reading this 
directory or because you used spaces in the definition of the directory. 

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. 


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

Changing html layout

If you want to change the layout of the htmloutput, you have to go directly 
into the code (although it is planned to make changing the htmlcode more
flexible by using templates). The functions that contain html are:

Writestatfile: here you can change the layout of the statistics file.

Getmp3info: in this function layout is defined when using the command line
            parameter "mp3info"
	    
Getogginfo: in this function layout is defined when using the command line
            parameter "mp3info"

Date: here the layout of the actual date is defined.

Writehtml: here some layout of the html output can be changed.

Htmlheader: here you can change the header for "Writehtml".

Htmlfooter: here you can change the footer for "Writehtml".

Htmlchange: here the html code is defined when the first character from 
            on file to the other changes.

Htmlbody: here the htmlcode for writing each file is defined.

Writesephtml: here seperate html files for every different first character
              is written out.

Sephtmlheader: here the header for "Writesephtml" is defined.



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

Functions

There are 43 functions implemeted in f2html.pl:

Checkmodules
Mainprog
Programinfo
Help
Getparameters
Searchengine
Writesql
Getmp3tag
Loadhextable
Correcthexlinks
Loadreplacementtable
Replacelink
Deletefileext
Correctpathnames
Removeid3tag
vorbis_parse
Ogg
Getogginfo
Getmp3info
Openfile
Closefile
Writem3u
Writedb
Writehtml
Htmlheader
Htmlfooter
Htmlchange
Htmlbody
Date
Writesephtml
Sephtmlheader
Renamefilesbyorig
Renamefilesbyid3
Storefilenames
Printdublicates
Configfile
Execsys
Keeppath
Message
Delslash
Writestatfile
Line
Write_Configfile


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

Release History

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

  f2html.pl 0.2-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 0.3-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 0.4-20011127
        Changes:
	 - Now f2html comes with a new version of Info.pm
	   from MP3-Info-0.91 by Chris Nandor
	 - Minor Bugfixes
	 - New option to create sql database
	 - New option to create a config file

  f2html.pl 0.5-20020626
	Changes:
	 - Fixed problem with sql data output when files contain the
	   charakter "'"
	 - Name of option "hex" changed to "utf8"
	 - Implemeted progress bar for prepating html files
	 - More information about what the program is doing

  f2html.pl 0.6-20020718
        Changes:
	 - New method (experimental) for faster sorting.
	   Useful for indexing huge number of files or mp3 files
	   with additional information.
	 - New option for checking for dublicates of filenames
	 - Now f2html.pl comes wioth a new version of Info.pm
	   from MP3-Info-1.01 by Chris Nandor

  f2html.pl 0.7-20021016
        Changes:
	 - bug for the option "check" in config file and configuration wizard fixed
         - bug for the check of the mp3 extension when mp3info was enabled fixed
         - bug of sum of megs in html output fixed
	 - bug in mp3table.sql fixed
         - basic ogg vorbis support implemented (thanks to Jens Burkal)
	 
  f2html.pl 0.8-20021105
        Changes:
	 - some changes in the documentation
	 - new option to rename files using their id3tag
	 - new option to rename files back
	 - some code fixes

  f2html.pl 0.9-20030313
        Changes:
         - Fixed a commandline parameter bug where the parameters 
	   were handled non case sensitive. Now there are handled case sensitive
	   As a result the functions RENAME and RENAMEBACK did not work 
	   when called with the short command line argument.
	 - Fixed a commandline parameter bug that occured with Perl 5.8.0 and 
	   Getopt::Long 2.32. The "-s" flag in line 1 of the perl script 
	   causes the program to count the command line parameters in 
	   an usual way, so that command line parameters got disturbed and did
	   not work any more.
	   
	   
-----------------------------------------------------------------------------

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

  f2html@linxsecure.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.
PHP interface has to be written. Change all command line examples to config file examples.




