Homepage
How to use cd2browse
18 Jul 2013 17:59
cd2browse



Verwandte Themen:


Documentation
FAQ cd2browse
Life Demo of cd2browse (tree menu)
Life Demo of cd2browse (xul menu)
Package download
Sample screenshots
To do list
Version History

Name:
   cd2browse - create browsable menus out of directory structures

Version: 1.05

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

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 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 !

*