Name:

   cd2browse - create browsable menus out of directory structures

Version: 1.03

Synopsis:
   index -p <path to index> [-n -m -t -s -i -x -q]

Description:
   cd2browse is a command line tool, to create html menues out of directory
   trees mostly used on CDs and DVDs it also indexes all files and provides
   a java script search engine for full text search.

Preperation:
   befor you start to process a directory, you should consider the following.

   cd2browse creates several files and subdirectories inside the document root -
   means in the directory you start processing. All subdirectories in the tree
   will be scanned by cd2browse and the html results are written to the root
   directory and special subdirectories. All files, necessary to use the html
   menues are written to the root directory (given by the -p option). Files in
   the root directory itself are not indexed and processed. Just sub-folders 
   are recognised from the root. Above root also files are read and indexed.

   For each file in the file tree a line in the belonging html menu will be
   written. There are three possibilities to create the title of a file:
   The highest priority has the .htaccess file in each directory. The .htaccess
   file is a standard on apache web server and cd2browse uses the same 
   syntax.  If a line in the .htaccess file refers to a file in the directory, this 
   title has priority and will therefore be taken for the menu. 

Example:

   AddDescription "The description of how to use cd2browse" cd2browse_use.txt

   The above line in .htaccess will show a longer description than just
   cd2browse_use.txt
   The second priority has a title tag of whether a pdf or a html file.
   cd2browse scans each pdf or html file for a title tag and takes this as the
   title in the menu line.
   If none of both, a .htaccess entry or a title tag exists, cd2browse takes
   the file name.

   If cd2browse finds a Image in the file tree, it calculates a thumb nail
   image, a preview page and image of this image. So that automatically a 
   image gallery is built. If you dont want to process images, for example
   because images are linked inside html files, you may add a line in the 
   .htaccess file with "IndexIgnore <list  of extensions>" to the directory you 
   don't want to index images.

How to start processing on the command line:

   perl index.pl -p <path to index> [-n -m -t -s -i -x -q]

   where options -n , -m , -t ,-s -i -x and -q are optional

How to start the GUI for window based interface:

   perl CD2Browse.pl

   The GUI is mostly self explaining - if you need help, go to Help -> Help,
   or read the file CD2Browse.hlp

Example:

   perl c:\perl\own\index.pl -p "c:\Own Files\CD project"
   ( use the double quotes for files or path with spaces )

   The above line will index all sub directories in "c:\Own Files\CD project"
   and writes the result into c:\Own Files\CD project

   After calculation, point your browser to index.html in the directory and
   enjoy.

Options:
  -n  (re) calculate no images to save cpu time
      This is especially interesting to re-calculate the indexes and omitting
      re-calculation of images, because this may save a lot of time.
  -m  maxwidh of the preview image (default=800)
      You can define the maximum with of the preview images with this
      option the size is in pixels. If the files are smaller, the image gets the
      previous size.
  -s  size of the thumbnails (default=90x90)
      The size of the thumbnails in the menu. The aspect ratio of the image
      is kept, but the resulting maximum is according to the setting width or
      height, depending on which exceeds first.
  -t  title
      The title of the menu pages.
  -i  do not index images
      If -i exists, no images will be indexed at all - for example if all
      images belong to html files.
  -x  do not extract title from pdf file
      If -x exists, the indexing process will not extract the title from the
      pdf file. Instead, the file name is used. This is helpful, when the
      pdf files do not contain senseful title tags
  -q  quiet - do not output progress information on the console window.

.htaccess functions:
   Since the command line options influence the behaviour of cd2browse in
   general, there is a need to define the behaviour on a per directory base.
   Similiar to the apache directives, it is possible to influence the indexing
   process by setting directives inside .htaccess files.

   if a .htaccess file exists in a scanned directory, it will be opened and
   parsed. 
   
   The following directives are recognized in .htaccess files:

   IndexIgnore
   IndexOptions SuppressDescription
   AddDescription

   IndexIgnore takes Arguments like in apache.cnf:
   Like in Apache, the settings are valid also for all sub directories.

   IndexIgnore *.gif *.css *.jpg *.png thumbs.db

   The above line for examle does not index gif,jpeg and png images and 
   also no css files and thumbs.db files.
   One or more lines with this directive may be used in the .htaccess file.

   IndexOptions SuppressDescription
   Like in Apache, the settings are valid also for all sub directories.

   The above line prevents the indexing process to extract the pdf title from
   pdf files - this is a per directory setting similiar to the -x command line
   option,which works globally.
   One line with this directive may be used in the .htaccess file.

   AddDescription "Description of the file" filename
   Other than in Apache, the File description is not used in sub directories. 
   This is a feature, since Apache annoys with repeating descriptions in sub 
   directories, when the same file name appears. 

   The above line adds a description for a particular file. - see also the hints
   further up in this document.

Customizing cd2browse:

   To customize the look and feel of cd2browse results, you may read the
   following:

   Files are copied from the resourcesource directory of cd2browse - usually
   /var/cd2browse - to the target directory.

   cd2browse checks before copying the files. If the files to copy already
   exist, cd2browse does not copy. This means you may change just the files 
   in your particular target directory instead of changing the source.

Files:

\var\cd2browse\head.html    - the upper frame (search form and head line)
                              content
\var\cd2browse\index.html   - the frame set itself
\var\cd2browse\result.html  - do not edit - will be overwritten - change
                              \var\c23browse\page.tpl and list.tpl instead
\var\cd2browse\welcome.html - the first page shown in the main frame
\var\cd2browse\start.exe    - used together with autorun.inf to autostart
                              the browser when on cd and cd is inserted
\var\cd2browse\autorun.inf  - used together with start.exe to autostart
                              the browser when on cd and cd is inserted
\var\cd2browse\cd.ico       - shown in explorer as the drive icon
\var\cd2browse\resources    - file type icons for the use in the menu
\var\cd2browse\resources\empty_dir.html - page shown if the user clicks onto
                              a empty directory
\var\cd2browse\resources\image_end.html - page shown if the last image of the
                              gallery is reached
\var\cd2browse\templates\tree.tpl  - template for the file tree menu
\var\cd2browse\templates\image.tpl - template for the image gallery html
\var\cd2browse\templates\page.tpl  - template for the menu pages
\var\cd2browse\templates\list.tpl  - template for each menu page list line