NAME

bin/addsl.pl - generate HTML subject listings from ROADS templates

SYNOPSIS

  bin/addsl.pl [-ANacdhi] [-f config_dir] [-l view]
    [-m filename] [-n database_name] [-o override_file]
    [-p pattern] [-s source_dir] [-t target_dir] [-u name]
    [-w waylay_url] [handle1, handle2 ... handleN]

DESCRIPTION

The addsl.pl program generates a set of subject listing files for the templates with the specified handles. These listing files are also converted into static HTML documents which can be placed on the WWW. The program can also generate HTML lists in numerical and alphabetical order based on the contents of a subject descriptor mapping file.

The addsl.pl program can generate a number of different subject listings. This allows, for example, a subject listing of UK based resources in addition to a subject listing of all resources. The views also allow easy selection of which subject listing a template should be added to in the admin-cgi/mktemp.pl editor.

USAGE

You can arrange for the ROADS software to generate listings of some or all of your templates broken down by subject area. Note that each template which you would like to appear in a subject listing should contain at least one URI attribute and at least one Subject-Descriptor cluster.

You may have as many different views of your templates as you like. Each view is normally a collection of statically generated HTML documents created by addsl.pl, though in version 2 of ROADS you can also browse dynamically through your database using "canned" queries. The subject listings may be customized in a number of ways - notably via HTML outline files may be used to specify the overall format of each HTML document generated by the ROADS software. These have some extra pseudo-HTML tags which allow you to indicate where in the resulting documents you would like the subject listing information to appear.

It is also possible to specify a pattern which the URIs in the resource description templates will have to match in order to be included in a subject listing. This can be used to generate, for example, lists of resources which are found in the UK academic community, resources which are generated dynamically by scripts, all resources of a particular type (e.g. MPEG movies), and so on.

addsl.pl will also generate customizable lists of the available subject categories in both alphabetical and numerical order (assuming the Subject-Descriptor classification is numeric.

A default set of subject categories based on the different programme areas in the UK Electronic Libraries Programme (to match our sample database) is distributed with the ROADS software as config/classmap, under the top level ROADS installation directory. You will probably want to change this to reflect your installation.

The file format of the subject listing views is explained in detail below. Essentially, it should contain pointers to the location of each of the following:

Outline HTML files for the subject listings themselves, and the breakdowns of subject categories by alphabetical and numerical order
The directory (visible to your WWW server) where the generated HTML files should be placed
The directory where any internal files used by the subject listing generator should be stored
The location of the mapping file which provides titles for each of the classifications in your scheme, and the names of the HTML files which should be generated for each classification

A typical view specification would look like this:

  HTML-Directory:         subject-listing
  WWW-Directory:          subject-listing
  Listing-Directory:      subject-listing
  Mapping-File:           class-map
  Subject-Scheme:         DDC
  AlphaList-File:         alphalist.html
  NumList-File:           numlist.html

The meanings of these path names are explained below. It is worth noting that they can be either relative (to the various directories involved in generating the subject listings, such as the ROADS config, guts and htdocs directories), or absolute - e.g. /usr/local/roads/guts/subject-listing/Default. You may prefer to refer to them by the full path name to avoid confusion, but be aware that this may cause you problems if you move the ROADS installation to another directory tree.

Note that the ROADS software comes shipped with defaults for the Default, DefaultAlpha and DefaultNumber outlines. The outline HTML used to generate the actual subject listings lives by default under config/multilingual/*/subject-listing-views. In version 2 of ROADS we switched to using our generic HTML rendering code, away from the old hard-coded HTML rendering embedded in the older versions of this code.

If your Subject-Descriptor-Scheme is UDC (the default), you should be able generate subject listings for all your templates using the default view by running addsl.pl with the -a argument:

  % addsl.pl -a

You will not need to do this if you are creating templates from scratch using the WWW based forms editor - this gives you the option of entering new templates into the subject listings automatically. In fact, it runs addsl.pl behind the scenes. If you only want to add a subset of your templates (such as those which have changed recently), addsl.pl should be called without the -a argument, and with the handles of the templates as arguments, e.g.

  % addsl.pl 0123 0124 0125

If you would like to create more than one view of your resource description templates, e.g. to have a separate AllUK listing of resources which pertain to the UK higher education community (Internet domain - ac.uk), you will need to make another view file and run addsl.pl with the -l specifying this, e.g. the view file for AllUK might look something like this:

  Outline-File: subject-listing/Default
  HTML-Directory: subject-listing/AllUK/
  Listing-Directory: subject-listing/AllUK/
  Mapping-File: subject-listing/classmap
  Alpha-Outline: subject-listing/DefaultAlpha
  Number-Outline: subject-listing/DefaultNumber

Whilst in this example the same HTML outline documents have been used for both views, this is entirely under the control of the ROADS server administrator. To create the AllUK view, you would need to run addsl.pl with both the -l and -p arguments, e.g.

  % addsl.pl -a -p '\.ac\.uk' -l AllUK

The resulting subject listing files will be generated in the directory specified in the view file as HTML-Directory, e.g. /usr/local/www/ROADS/subject-listing/AllUK. The following files will be generated:

alphalist.html - breakdown of subject categories in alphabetical order
numlist.html - breakdown of subject categories in numerical order
A separate HTML file for each of the subject categories listed in your Mapping-File. These will be based on the short name for the subject category, with a .html tacked on the end

Should you ever need to completely re-generate your subject listings, it will be necessary to remove the files in the directory specified by the Listing-Directory entry in the view file, e.g. /usr/local/roads/guts/subject-listing/AllUK. You may also choose to remove the HTML documents generated by addsl.pl in the HTML-Directory. Alternatively, cullsl.pl the subject list culling tool, may be adequate for your needs - see its manual page for more information.

Note that if they do not exist already, you will need to create parent directories for the directories referred to in a subject listing view configuration file.

OPTIONS

A number of options are available for the addsl.pl program to control which files are used for generating the subject listings and where configuration options are located. Note that most of these can also be supplied in the addsl.pl view config file (see below), and that settings which appear in this will usually override command line arguments.

-A

Don't generate alphabetical subject index

-a

Process all templates in source directory.

-c

Specify that the alphabetical listing should take acount of the case of the characters. Without this option, acorn , Apple and Zebra are sorted in that order. With this flag set, they would be sorted as Apple , Zebra and acorn.

-d

Specify that some (fairly copious) debugging information should be generated during the generation of the hypertext tree. This option is probably not of interest to anyone bar the developers.

-f directory

Specify the directory for views configuration files.

-h

Provide some online help outlining the options available and exit.

-i

Regenerate HTML files regardless of timestamps on subject listing files.

-l view

Set subject listing view name. This is the name of the file that contains the configuration information concerning the location of the listings, HTML and outline files. For more information on this see below.

Be aware that for a given view you will actually need three sub- directories under the config/multilingual/*/subject-listing-views directory, named view, viewAlpha, and viewNumber. This is because the addsl.pl tool generates three separate sets of HTML files when it runs - the regular view of your database, plus views sorted by numerical and alphabetical order.

Just another reminder that the settings specified in a view file typically override other command line arguments, e.g. Subject-Scheme overrides the -u argument.

-m filename

Specify the subject descriptor mapping file to use.

-N

Don't generate numeric subject index.

-n name

Specifies the name of the database to use when generating HTML. The default is the service name which was entered when the ROADS software was installed.

-p pattern

Only enter entries in the subject listings for templates that have URI fields that match the supplied pattern. The pattern can be a full Perl regular expression and allows one to, for example, restrict entries in the subject listings to only include UK academic sites. By default the pattern matches all URLs and so all templates are included in the hypertext lists.

-s source_dir

Set the absolute pathname of the directory containing the IAFA templates.

-t target_dir

Set the absolute pathname of the directory where the files created by addsl.pl will be placed.

-u name

Sets the name of the Subject-Descriptor-Scheme to search for in the templates. The default is UDC.

-w waylay_url

The URL to waylay people too when dealing with an unusual or complex URL scheme, e.g. wais. See "waylay.pl" in cgi-bin for more information on this.

These options are then followed by zero or more templates' handles (note - not filenames). If the -a option is given, no handles need be given on the command line; all templates in the database will be added to the subject listings.

FILES

config/class-map - where to get default mappings from.

Subject-Descriptor-Scheme attributes in templates to filenames used for generating HTML.

config/subject-listing/* - view files, each of which describing a particular way of rendering the templates into HTML.

config/multilingual/*/subject-listing-views/* - HTML rendering rules for addsl.pl subject listing views, with a separate directory per view. The actual rendering rules are as per search results.

guts/subject-listing/*.lst - default location of the internal files used to maintain state between runs of subject listing tools.

htdocs/subject-listing - default location of the HTML generated by addsl.pl

FILE FORMATS

Subject Descriptor Mapping File

The subject descriptor mapping file specifies the code for a particular subject section, the name given to that section in the HTML documents and the root of the filename used to hold that section's hypertext listing, each element being separated by a colon. An example line from a subject descriptor mapping file (for the UDC subject descriptor scheme) is:

  30.442:Development Studies:devstud

Note that the section name should not contain the colon character ":" - this would confuse addsl.pl.

Subject Listing Views

Each available HTML view of the templates is specified by a view file. A sample file is:

  HTML-Directory: /WWW/htdocs/ROADS/subject-listing/
  WWW-Directory: /ROADS/sl/
  NumList-File: /ROADS/sl/numeric.html
  AlphaList-File: /ROADS/sl/numeric.html
  Listing-Directory: /usr/local/ROADS/guts/subject-listing/
  Mapping-File: /usr/local/ROADS/config/subject-listing/class-map
  Generate-Children: yes

The various attributes currently defined in the view file are:

AlphaList-File: The name of the file into which addsl.pl will save a list of the subject categories sorted by alphabetical order.
Casefold-List: Turns on case folding when alphabetising the list - the same as the -c option on the command line.
Generate-Children: Whether or not to generate subject listings for templates that only have ChildOf relation types in them.
HTML-Directory: The path to the directory in which the subject listing HTML documents should be generated. This directory should be accessible to the HTTP daemon that serves the ROADS documents if they are to be accessible via the World Wide Web. If the path is a relative one, it is assumed to be relative to the ROADS htdocs directory, i.e. the directory under which the ROADS related HTML documents are rooted.
Listing-Directory: The path to the directory in which the subject listing files should be located. This is typically a subdirectory of the guts directory of the ROADS installation, where internal files used only by the ROADS software are kept. If this is a relative path, it is assumed to be relative to the ROADS guts directory.
Mapping-File: The path to the subject descriptor mapping file. If this is a relative path, it is assumed to be relative to the ROADS config directory.
Subject-Scheme: The name of the subject scheme that this view relates to.
WWW-Directory: The WWW path to the directory in which the HTML generated by addsl.pl will appear. This includes the AlphaList-File and NumList-File listings.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

It was developed by the Department of Computer Studies at Loughborough University of Technology, as part of the ROADS project. ROADS is funded under the UK Electronic Libraries Programme (eLib), the European Commission Telematics for Research Programme, and the TERENA development programme.

Author

Jon Knight <jon@net.lut.ac.uk>, Martin Hamilton <martinh@gnu.org>

To install ROADS::WPPC, copy and paste the appropriate command in to your terminal.

cpanm

cpanm ROADS::WPPC

CPAN shell

perl -MCPAN -e shell
install ROADS::WPPC

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)