[Koha-devel] Issues for README.txt and Makefile.PL

[Thomas Dukleth]

README.txt and Makefile.PL for Koha 3.0 needs a number of significant
fixes and corrections.

As I was preparing some proposed fixes, Joshua Ferraro informed me that
there are various pending fixes from a few people.  Some of the pending
fixes will not be pushed up to the Koha git repository because they
conflict with other more complete fixes.  Galen Charlton has committed
some fixes which have yet to be pushed up to the main repository.  Galen's
fixes may resolve at least some of the issues which I have had.  Galen is
actively working on these issues so I raise the issues that I had
originally proposed to commit so that they may be considered for
non-conflicting incorporation if they have not already been fully
considered.

Some issues follow.  Please comment and add any additional issues.


1.  README.TXT PROBLEMS.

1.1.  LACK OF OPERATING SYSTEM DISTRIBUTION SPECIFIC INSTRUCTIONS.

Ideally, the installation would work seamlessly on every operating system
distribution which Koha supports.  However, we know that seamless
installation is not going to happen until the time is available for
building a complete set of Koha packages for various operating system
distributions.

README.txt lacks direction to operating system distribution specific
information and otherwise undistributed packages.

I have had to rely upon one and perhaps now two supplementary binary
packages for Debian to allow me to install Perl modules, which may not be
critical to using Koha but are certainly good to have.  Vincent Danjean
has some supplementary Debian packages at
http://www-id.imag.fr/Laboratoire/Membres/Danjean_Vincent/deb.html and MJ
Ray has some at http://serene.ttllp.co.uk/~mjr/ .  At some point, these
should be placed in repository for apt to use.

There seem to be problems building Barcode::Code12 8 on many platforms
which is a dependency of the needed PDF::Reuse::Barcode which the binary
Debian package from Vincent solved for me.  There have been problems
building Barcode::Code128 on many operating systems and platforms
throughout its release history.  See reports from CPAN testers such as
this one for the current version,
http://www.nntp.perl.org/group/perl.cpan.testers/2007/07/msg544810.html .

I also have a dependency issue which I have not yet completely
investigated for building XML::LibXSLT 1.6.3.  Maybe keeping version 1.6.2
for now will not be a problem.


1.2.  CORRECT PATHNAMES IN COMMANDS.

Any pathnames in commands should at least match the default pathnames
created by Makefile.PL.  Perhaps Makefile.PL should build the necessary
commands to run with the correct pathnames during make install or make
install should also create a script to run the commands after make
install.


1.3.  ENVIRONMENT VARIABLES.

Possibly conflicting Koha release 2.2 environment variables should be
unset or reset if that may be a potential problem for some.


1.4.  SPECIFYING THE XML CONFIGURATION FILE OPTION FOR ZEBRA.

The -c option is still given for zebrasrv which should long ago have been
changed to -f for using an XML configuration file.


2.  MAKEFILE.PL PROBLEMS.

2.1.  PROBLEMS PREVENTING SUCCESSFUL MAKE.

File globbing which captures directories builds a makefile which aborts
with the following error when running make.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
ERROR: Cannot copy 'installer/data/mysql/fr/mandatory' to
'/usr/local/lib/cgi-bin/koha/installer/data/mysql/fr/mandatory': Is a
directory
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 at -e line 1
make: *** [pm_to_blib] Error 21

Changing general file globbing from * to *.* for using the '.' in
filenames can fix that problem.  However, that solution is not robust if
files are not in *.* form and at least needs a specific correction for
.htaccess as the only file which does not match the pattern.


2.2.  INSTALLATION DIRECTORY PROBLEMS.

Default installation directories are not what they should be.  If the task
of resolving these issues has been left to Galen, I am not going to take
the full time to make a detailed list, however, some special attention
should be given to general principles.

The defaults do not put directories where they should be in multiple cases.

2.2.1.  CONFLICT BETWEEN PL_FILES AND MAP_TREE.

I believe that Galen has a fix for the problem where map_tree values had
been overwriting PL_FILES values.


2.2.2.  ZEBRA DIRECTORY LOCATIONS.

The case of Zebra is especially problematic.  The treatment of the Zebra
directories does not follow important principles.  Currently,
configuration and data directories for Zebra are in the same location.


2.2.2.1.  SEGREGATION OF CONFIGURATION AND DATA.

Configuration files should be segregated from data files for easy and
distinct management.  Configuration files are traditionally stored in /etc
or some equivalent such as /usr/local/etc.  Data files are usually stored
in /var or some equivalent such as /var/local.

Configuration information in some form of /etc can be reasonably compact
for storage and backup.  Data in some form of /var may be quite large and
require its own disc storage for all of what it needs to contain and as
use develops it may grow significantly over time.


2.2.2.2.  MISSING DIRECTORY.

One additional issue is of special importance.  The main Zebra temporary
directory is not created on installation.


2.3.  INSTALLATION FILE OWNERSHIP.

The webserver user should be read and ownership of the necessary files
should be changed to the webserver user when running make install.


2.4.  CONFIGURATION FILES CONTENT.

2.4.1.  GENERAL CONFIGURATION FILE PROBLEMS.

Configuration file pathnames do not match either the default pathnames or
the actually installed pathnames.


2.4.2.  KOHA-HTTPD.CONF.

Using the ScriptAlias directives is considered a security vulnerability. 
Alias directives, rewrite rules or some other more secure method should be
substituted for ScriptAlias directives.

Directory options should be specified in advance


2.4.3.  KOHA-CONF.XML.

The Koha administrator username and password should be written to the file
according to what is specified.


2.4.4.  LANGUAGE SPECIFIC CONFIGURATION FILES.

Language specific Zebra configuration files are missing from the Zebra
configuration directories.


Thomas Dukleth
Agogme
109 E 9th Street, 3D
New York, NY  10003
USA
http://www.agogme.com
212-674-3783