Name:
cd2browse - create browsable menus out of directory structures.
index is a part of cd2browse and can run from the command line. If you start
cd2browse instead, a GUI menu will be started where you can set the command
line options for index.pl which then runs in the background.
Version: 1.05
Synopsis:
index -p <path to index> [-n -m -t -s -i -x -r -q -v]
Description:
index 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 document
root directory and special subdirectories. All files, necessary to use the
html menues are written to the document 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 ordinary files are read
and indexed.
For each file in the file tree a line in the belonging html menu(s) 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 beause
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 -r -q -v]
where options -n , -m , -t ,-s -i -x -r -q and -v 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
-r do not create several output pages for sorting. When applied, only
one result page per directory is created. This does not allow sorting
on the other hand. A different page.tpl template is recommended, because
if the sort template is used, clicking onto the sort links lead to a
error message of the browser - missing page. If the option is not
present, 8 pages per directory will be created, for offline sorting.
-q quiet - do not output progress information on the console window.
-v Do not create folder navigation in the page section of the main view.
If you use this option, no links for sub folders will be created in the
main views (page_xxx.html) So subfolders are not visible in the page
section. This forces the User to use the tree section for folder
navigation.
.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.
note: if you want to have a mix of images in a directory you want to index and
images you dont want to be indexed because they belong to a html file, you may
create a directory with a leading dot like for example .resource and put the
images for html pages inside this directory and link it inside the html
accordingly. Directories with a leading dot will not be indexed at all.
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/opt/cd2browse/repository (unix/Linux) or
c:\strawberry_operate\opt\cd2browse\repository (Windows)
- to the target directory "<dir to index>/.repository"
CD2Browse checks before copying the files. If the files to copy already
exist, cd2browse does not copy, but takes the settings from the target.
So you may change just the files in your particular target directory
instead of changing the source. Each further run of index.pl will take the
settings from the target. This means you can customize the output on a
project base this way. On the other hand this means, that if once a target
directory has been changed, it will be never overwritten again, until you
delete all files in the .repository directory on the target manually.
Files:
\var\opt\cd2browse\repository\head.html - the upper frame (search form and head
line)content
\var\opt\cd2browse\repository\index.html - the frame set itself
\var\opt\cd2browse\repository\result.html - do not edit - will be overwritten -
change
\var\cd2browse\repository\menu\templatespage.tpl
and list.tpl instead
\var\opt\cd2browse\repository\welcome.html - the first page shown in the main
frame
\var\opt\cd2browse\repository\start.exe - used together with autorun.inf to
autostart the browser when on cd and
cd is inserted
\var\opt\cd2browse\repository\autorun.inf - used together with start.exe to
autostart the browser when on cd and
cd is inserted
\var\opt\cd2browse\repository\cd.ico - shown in explorer as the drive icon
\var\opt\cd2browse\repository\resources - file type icons for the use in the
menu
\var\opt\cd2browse\repository\empty_dir.html -page shown if the user clicks onto
a empty directory if the folder
navigation is not in use
\var\opt\cd2browse\repository\image_end.html -page shown if the last image of the
gallery is reached
\var\opt\cd2browse\resources\templates\image.tpl
- template for the image gallery html
\var\opt\cd2browse\repository\templates\page.tpl - template for the menu pages
\var\opt\cd2browse\repository\menu\templates\list.tpl
- template for each menu page list line
\var\opt\cd2browse\repository\menu\templates\tree.tpl
- template for the file tree menu
\var\var\opt\cd2browse\repository\menu\templates\treeitem1-1.tpl
- template for the root folders of the
tree menu - this is the opening tag.
Together with treeitem1-2.tpl it
contains the code for this folder
level menu structure
...\treeitem1-2.tpl - Closing tag - works together with
treeitem1-1.tpl
...\treeitem2-1.tpl - This is the end fragment for the folder
hirarchy i.e. used for a folder wich
has no sub-folders.
...\treeitem2-2.tpl - Contains the closing tag - works
together with treeitem2-1.tpl
...\treeitem2-1a.tpl - Used for folders in between the root
and the end folder
...\treeitem2-2a.tpl - Contains the closing tag - works
together with treeitem2-1a.tpl
After running cd2browse once sucessfully, a similar structure exists in your
target file tree, because the above files and folders will be copied to your
document root. These files will be copied only if the don't exist before. This
means customizing them allows you a project based look and feel
<target directory>\index.html
<target directory>\.repository\head.html
<target directory>\.repository\result.html
<target directory>\.repository\welcome.html
<target directory>start.exe
<target directory>autorun.inf
<target directory>cd.ico
<target directory>\.repository\resources <all copied from
\var\opt\cd2browse\repository\resources>
<target directory>\.repository\menu\ <all copied from
\var\opt\cd2browse\repository\menu>
<target directory>\.repository\teplates\ <all copied from
\var\opt\cd2browse\repository\templates>
How to use different Tree menus:
To use a different tree menu, you can rename one of the additional sample
repository directories "\var\opt\cd2browse\repository_xxxxx" into "repository"
Please read also the README files in the different repository_xxx directories.
A template set for the tree menu consists of four levels as shown below and is
the base for the resulting tree.html. During run time of index.pl, the templates
will be filled with data and linked together to form the resulting tree.html
-------------------
| |
| --------------------
| | treeitem1-1.tpl |
| ----------------------------
| | treeitem2-1a.tpl |
| ---------------------
| .....
| ----------------------
| | treeitem2-1a.tpl |
| -------------------------------
| | treeitem2-1.tpl |
| tree.tpl -----------------------
| | treeitem2-1.tpl |
| -------------------------------
| | treeitem2-2a.tpl |
| ----------------------
| .....
| ---------------------
| | treeitem2-2a.tpl |
| ----------------------------
| | treeitem1-2.tpl |
| --------------------
| | treeitem1-1.tpl |
| --------------------
| .....
| --------------------
| | treeitem1-2.tpl |
| --------------------
| |
------------------- Remember: After running once index.pl on a particular directory tree, you need
to delete the .resources directory in the target file tree if you want to try a
different tree menu for the same directory. Otherwise you will see no change !
*
