Frequently Asked Question About Lire

Joost van Baal

Egon L. Willighagen

Francis J. Lacoste

This document is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this manual (see COPYING); if not, check with http://www.gnu.org/copyleft/gpl.html or write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.

Revision History
Revision 20020214 $Date: 2002/02/06 20:23:50 $
$Id: faq.dbx,v 1.14 2002/02/06 20:23:50 vanbaal Exp $

1 Problems Installing Lire On Specific Platforms
1.1 Installing Under Debian GNU/Linux
1. What .deb packages are required by Lire?
1.2 Installing Under Red Hat Linux
1. What RPM packages should I install to run Lire?
1.3 Installing Under SuSE Linux
1. What RPM packages should I install to run Lire?
2. I have installed all the requirements but I get the following errors when trying to generate an HTML report: /usr/bin/jade:/home/lire/logreport/share/lire/sgml/stylesheet/dsssl/\ html.dsl+:1:73:W: cannot generate system identifier for public text\ "-//James Clark//DTD+DSSSL Style Sheet//EN What does this means ?
1.4 Installing Under OpenBSD
1. Which ports should I install to run Lire?
1.5 Installing Under Solaris
1. Which packages should I install to run Lire?
2. Is it hard to install the needed libxslt?
3. How do I install OpenJade?
4. How do I install Jade?
5. While trying to generate an HTML report using lr_log2report -o html, I get the error following error all all lr_tag-20011013213208-983 lr_xml2html err docbook.dsl \ file '' does not exist! all all lr_tag-20011013213208-983 lr_xml2html err Please install \ Norman Walsh's DocBook DSSSL Stylesheets. all all lr_tag-20011013213208-983 lr_xml2html err Consult the Lire \ User's Manual for more informations. How do I fix this problem ?
6. I installed the necessary DocBook stuff, but generation of HTML reports still fails with the message: bogus message: cat: cannot open /usr/home/flacoste/tmp/lr_xml2html.6050/\ lr_xml2html.html www combined lr_tag-20011013215447-6006 lr_log2report err lr_xml2html failed How do I solve this problem?
1.6 Installing Under MacOS X
1. Can I run Lire under MacOSX?
2 Licensing
1. I wanna contribute code, and would like it to get distributed as a part of Lire, what should I do, license-wise?
2. Why is Lire licensed under the GPL?
3. If I make a contribution to Lire do I have to put my code under the GPL?
4. We want to write a DLF converter for the users of our proprietary product, can we distribute it under the same proprietary terms as our other products?
5. Can I distribute my XML report specifications under other terms than the GPL?
6. I want to reuse your file formats (DLF format, XML report) in my project, but I want to release this project under a MIT X-like license, may I?

1 Problems Installing Lire On Specific Platforms

In this section, you will find answers to common installation problems on various platforms.

1.1 Installing Under Debian GNU/Linux

1. What .deb packages are required by Lire?

The Lire .deb has the proper Suggests and Depends tags that will give you the proper dependencies. But if you would like to install Lire from source, read on.

To run a minimum Lire installation, you will need the following packages (those are from Woody):

and its other dependencies.

To run a Lire installation with all the output format supported, you will also need:

and their other dependencies.

If you want to run an online responder, you will also need the following packages in addition to your Mail Transport Agent (exim, sendmail, postfix or qmail):

1.2 Installing Under Red Hat Linux

1. What RPM packages should I install to run Lire?

To install a minimum Lire installation, you will need the following packages:

along with its required dependencies.

To run a Lire installation with all the output format supported, you will also need:

and their other dependencies.

In order to generate charts, you will need to install the following perl modules from a CPAN mirror:

To compile those modules, in addition to the usual development packages, you will need:

In order to run an online responder, you will have to install Mpack from source. There doesn't seems to be any RPM package for Red Hat Linux. You can download Mpack from ftp://ftp.andrew.cmu.edu/pub/mpack/.

1.3 Installing Under SuSE Linux

1. What RPM packages should I install to run Lire?

To install a minimum Lire installation, you will need the following packages that are available from your SuSE Linux installation CD:

  • perl-XML-Parser

along with its required dependencies.

To run a Lire installation with all the output formats supported, you will also need the following packages (all included on the installation CD):

  • openjade or jade_dsl

  • docbook_4

  • docbook-dsssl-stylesheets

  • docbook-xsl-stylesheets

  • jadetex

and their other dependencies.

You will also need to install an RPM for libxslt and libxml2 that aren't packaged with SuSE Linux. You can install the ones distributed by the author of libxslt and available from ftp://xmlsoft.org/

In order to generate charts, you will need to install the following perl module from a CPAN mirror:

Before installing that module, you will have to install the following packages from the SuSE Linux CD:
  • perl-GD

  • gd

  • gd-devel

In order to run an online responder, you will have to install Mpack from source. There doesn't seems to be any RPM package for SuSE Linux. You can download Mpack from ftp://ftp.andrew.cmu.edu/pub/mpack/.

2. I have installed all the requirements but I get the following errors when trying to generate an HTML report:

/usr/bin/jade:/home/lire/logreport/share/lire/sgml/stylesheet/dsssl/\
 html.dsl+:1:73:W: cannot generate system identifier for public text\
 "-//James Clark//DTD+DSSSL Style Sheet//EN
	      
What does this means ?

The SGML environment isn't properly set when using openjade under SuSE Linux. You will have to set the SGML_CATALOG_FILES environment variable to the following:

$ export SGML_CATALOG_FILES="/usr/share/sgml/CATALOG.db41xml:\
>/usr/share/sgml/CATALOG.docbook-dsssl-stylesheets:\
>/usr/share/sgml/openjade/catalog"
	      

Please report this as a packaging bug to SuSE Linux.

1.4 Installing Under OpenBSD

1. Which ports should I install to run Lire?

Many of the softwares required to run Lire are part of the OpenBSD 2.8 ports collection.

Unfortunately, the minimum requirements to run aren't included in the ports collection. You will need to install both expat and XML::Parser from source.

To run a Lire installation with all the output format supported, the following ports can be installed:

and their other dependencies.

You will also need to install the following from source:

  • libxslt 1.0.4 and its required library: libxml2.

    You will need to use GNU make to install libxml2 because it breaks with OpenBSD's native make.

  • The DocBook XML DTD and Norman Walsh's DocBook XSL stylesheets.

If you want to run an online responder, you will also need the following port in addition to your Mail Transport Agent (exim, sendmail, postfix or qmail):

OpenBSD 2.9 and 2.10 ports collection contains more required sofwares.

To run a minimum Lire installation, you can install the following port:

To run a Lire installation with all the output formats supported, the following ports can be installed:

and their other dependencies.

Although libxslt and libxml2 are included in the ports collection, they are older versions which aren't supported by Lire.

You will need to install libxslt 1.0.4 from source.

You will need to use GNU make to install libxml2 because it breaks with OpenBSD's native make.

You will also need to install Norman Walsh's DocBook XSL stylesheets from source.

If you want to run an online responder, you will also need the following port in addition to your Mail Transport Agent (exim, sendmail, postfix or qmail):

1.5 Installing Under Solaris

1. Which packages should I install to run Lire?

Unfortunately, most of the required tools aren't available as Solaris packages. The only ones that you will find on SunFreeWare are:

DB_File, db

Needed if you want to anonimize logs before sending them an online responder.

mpack

Needed if you want to run an online responder.

Fortunately, most development packages that you will need to build the other requirements are available as packages:

  • GNU make

    zlib

    gcc

    gd

    teTeX

The following requirements will have to be compiled from source:

  • perl GD module

  • perl GDGraph module

  • libxslt

  • libxml2

  • jade

  • jadetex

2. Is it hard to install the needed libxslt?

We successfully installed libxslt on a SPARCstation-20 running SunOS 5.7, using GNU make and gcc 2.8.1. We used libxml2-2.4.5.tar.gz and libxslt-1.0.4.tar.gz.

Apart from having to set our LD_LIBRARY_PATH to /usr/lib:/usr/local/lib (our libz from zlib-1.1.3, in /usr/local/lib/libz.a and /usr/local/lib/libz.so), and to set our PATH to include /usr/ccs/bin (to find ranlib), no issues arose.

3. How do I install OpenJade?

There are some issues with OpenJade. In case you get hit by something like :

c++ -O2 -fno-implicit-templates -I. -I./../include -I./../generic \
  -DSTDC_HEADERS=1 -DHAVE_LIMITS_H=1 -DHAVE_ST_BLKSIZE=1 -DSIZEOF_SIZE_T=4 \
  -DSIZEOF_UNSIGNED_INT=4 -DSP_HAVE_BOOL=1 -DSP_HAVE_LOCALE=1 \
  -DSP_HAVE_GETTEXT=1 -DSP_ANSI_CLASS_INST=1 -DJADE_MIF=1 -DJADE_HTML=1 \
  -DSP_MULTI_BYTE=1 \
  -DDEFAULT_SCHEME_BUILTINS=\"/usr/local/share/builtins.dsl\" -c  -fPIC \
  -DPIC TranslateCodingSystem.cxx -o TranslateCodingSystem.lo
TranslateCodingSystem.cxx: In method \
 `TranslateDecoder::TranslateDecoder(class Decoder *, const class \
 ConstPtr<CharMapResource<short unsigned int> > &)':
TranslateCodingSystem.cxx:28: Internal compiler error.
TranslateCodingSystem.cxx:28: Please submit a full bug report to \
 `bug-g++@prep.ai.mit.edu'.
make[2]: *** [TranslateCodingSystem.lo] Error 1
           
there's a workaround, reported by Carlos Villegas on dssslist@lists.mulberrytech.com, which can be implemented by running:
$ CXXFLAGS=' ' ./configure
$ make
# make install
              

Note

This problem may be specific to gcc 2.8.1.

4. How do I install Jade?

In case you're running something like SunOS 5.7, you're advised to not install OpenJade, but Jade. OpenJade is reported to segfault. We've successfully installed Jade on such a machine. In order to build jade, we modified the Makefile to feature:

prefix=/usr/local
XDEFINES=-DSP_HAVE_GETTEXT -DSP_DECLARE_H_ERRNO
RANLIB=ranlib
	      

Test your installation by running:

$ jade -t rtf -d demo.dsl demo.sgm
              
and inspecting the generated demo.rtf.

5. While trying to generate an HTML report using lr_log2report -o html, I get the error following error

all all lr_tag-20011013213208-983 lr_xml2html err docbook.dsl \
 file '' does not exist!
all all lr_tag-20011013213208-983 lr_xml2html err Please install \
 Norman Walsh's DocBook DSSSL Stylesheets.
all all lr_tag-20011013213208-983 lr_xml2html err Consult the Lire \
 User's Manual for more informations.
	      
How do I fix this problem ?

You need to install the following software:

You only have to unpack the files in a directory. Both the DocBook DTD distribution and the DSSSL stylesheets come with a OASIS catalog that you probably want to add to your SGML_CATALOG_FILES. (See next question for more informations.)

Lire tries to find those components in ‘standard’ places like /usr/share/sgml or /usr/lib/sgml. When configuring Lire, you should point it to the locations where you unpacked those files by using environmental variables:

$ DBK_XML_DTD="docbook_dtd_directory/docbookx.dtd" \
> DBK_DSSSL_STYLESHEETS="docbook_dsssl_directory" \
> DBK_XSL_STYLESHEETS="docbook_xsl_directory" \
./configure other-options
	      

6. I installed the necessary DocBook stuff, but generation of HTML reports still fails with the message:

bogus message: cat: cannot open /usr/home/flacoste/tmp/lr_xml2html.6050/\
 lr_xml2html.html
www combined lr_tag-20011013215447-6006 lr_log2report err lr_xml2html failed
	      
How do I solve this problem?

This is probably because jade cannot find the DocBook DTD or the DSSSL stylesheets. You can set the DEBUG variable to 1 in your $HOME/.lire/etc/defaults file to make sure. If this is indeed the error, you will get the following in the messages output by Lire:

all all lr_tag-20011013215935-6210 lr_xml2html info /usr/local/bin/jade \
 says /usr/local/bin/jade:/usr/home/flacoste/lire-test/share/lire/sgml/\
 stylesheet/dsssl/html.dsl:1:73:W: cannot generate system identifier for \
 public text "-//James Clark//DTD DSSSL Style Sheet//EN"
all all lr_tag-20011013215935-6210 lr_xml2html info /usr/local/bin/jade \
 says /usr/local/bin/jade:/usr/home/flacoste/lire-test/share/lire/sgml/\
 stylesheet/dsssl/html.dsl:2:91:W: cannot generate system identifier for \
 public text "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN"
	      

For jade to find the necessary ‘public identifiers’, you will need to set your SGML_CATALOG_FILES to point to the necessary ‘OASIS catalogs’. This variable will need to contain at least the three following catalogs:

  • Catalog for DocBook XML DTD: it is in docbook_dtd_directory/docbook.cat.

  • Catalog that comes with Jade or OpenJade: jade_source_directory/dsssl/catalog.

  • Catalog that comes with Norman Walsh's DSSSL Stylesheets: docbook_dsssl_directory/catalog.

So doing
$ export SGML_CATALOG_FILES="docbook_dtd_directory/docbook.cat:\
> docbook_dsssl_directory/catalog:\
> docbook_dsssl_directory/catalog"
	      
will probably fix the problem. Be sure to replace the docbook_dtd_directory and such with the actual directories where you installed the DocBook DTD.

1.6 Installing Under MacOS X

1. Can I run Lire under MacOSX?

Yes! Lire version 20011017 and later (some earlier versions too, probably) builds and runs under MacOSX 10.1. This has not been anywhere near fully tested and many features are dodgy at best. However, here's what you need to do to get the basic package cooking. This assumes some familiarity with the terminal application and command line interface. You'll also obviously need to have the developers tools installed.

  • Open a terminal window. Download and de-compress the latest lire package by typing the following:

    $ curl http://www.logreport.org/pub/current.tar.gz
    $ tar -xzvf current.tar.gz
    		  

    DO NOT decompress with StuffIt Expander. This will result in a broken package!

  • Then cd into the directory this creates (should be lire-20011205) and run the configuration utility with the --prefix option. Then make and make install. You can change this to wherever you want to install. This will create a logreport folder in your home directory which holds all the lire software. You might also try --prefix=$HOME/Applications/lire

    $ ./configure --prefix=$HOME/logreport
    <blah blah>
    $ make
    <blah blah>
    $ make install
    		  

  • Now the software is in. The next step is to make your shell aware of it. Remember the prefix you picked above.

    $ pico ~/.tcshrc
    		  

    Now add the following lines to the .tcshrc file (this is read by your shell whenever you log in). Then press ctrl+X to exit. Answer y for yes to save and hit return to write the file.

    setenv PATH {$PATH}:$HOME/logreport/bin
    setenv MANPATH {$MANPATH}:$HOME/logreport/man
    		  

  • Now close this shell and open a new one. You're ready to use lire. There are man pages to help, and a user manual is installed. The apache logs generated by default in OSX (in /var/log/httpd/) are readable by lire. You can analyze access_log as a www common file. This FAQ section will improve in the future as we are able to play with OS 10.1 more in the future.

2 Licensing

In this section, you will find answers to common questions about various aspects of Lire's licensing, e.g. questions which might arise if you plan to extend Lire with your own code.

Be aware that the LogReport team is very happy to include and maintain contributed code. We want to make this as easy as possible. See the first question. If you write code to be used with or as a part of Lire, please consider contributing it. This will not only benefit Stichting LogReport Foundation, but also you: the LogReport team will maintain and distribute your code, and will take care of handling bug reports.

Note

Apply the usual disclaimers about the fact that this information doesn't represent ‘legal advice’ and that you should consult an appropriate legal advisor for the definitive answers.

1. I wanna contribute code, and would like it to get distributed as a part of Lire, what should I do, license-wise?

As with any software, it's a good thing to add a copyright notice to your code, like


 Copyright (C) 2001,2002 Joe Hacker joe@example.org
              

. This makes it easy to find out who holds the copyright of this particular piece of code. Furthermore, you should add a license notice, like e.g. the modified BSD license which reads



 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

 1. Redistributions of source code must retain the above copyright notice,
 this list of conditions and the following disclaimer.

 2. Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.

 3. The name of the copyright holder may not be used to endorse or promote
 products derived from this software without specific prior written
 permission.

 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
 EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

              

or a referal to the GPL, which reads


This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program (see COPYING); if not, check with
http://www.gnu.org/copyleft/gpl.html or write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
              

This makes it clear what people are allowed to do with your code. See the questions below for other licenses you could use. If you sent us code along with a copyright notice ans license notice as above, we have no problems licence-wise with your contribution.

2. Why is Lire licensed under the GPL?

The Stichting LogReport Foundation exists to develop, maintain and propagate tools as well as knowledge for log file processing and report generation (among other things). The Foundation's statutes mandate that all software owned by the Foundation should be made available under an open source license.

The chosen license was the GNU General Public License (aka GPL) because it was one of most widespread “open source” licenses and it would allow integration of many existing code.

You can find more about the Stichting LogReport Foundation on our website. Unfortunately, our articles of association are available in Dutch only at this time.

3. If I make a contribution to Lire do I have to put my code under the GPL?

The short answer: no. As copyright holder of your contribution, you are free to choose whatever license terms please you. Be aware though that to be included in Lire, your contribution must be made available under terms compatible with the GPL. Examples of licenses that have compatible terms are the GNU GPL, the modified BSD license, the X11 license or the Clarified Artistic License (a list is on http://www.gnu.org/licenses/license-list.html).

The more adequate answer is that it depends of the nature of your contribution. Contributions that cannot really be considered independent of Lire's distribution and thus have to be considered as “derived work” must be distributed under the GPL. This would include most patches to Lire's internals or to programs or reports included in Lire, but not additions of superservices, services or reports.

4. We want to write a DLF converter for the users of our proprietary product, can we distribute it under the same proprietary terms as our other products?

Yes. If your DLF converter doesn't include any code from Lire you are free to distribute it under the terms of your choice. Note that converters that use the publically defined DLF converter API include link to developer's documentation, aren't considered to be including or copying from Lire's code.

Remember though that in this case, your DLF converter won't be able to be distributed as part of Lire.

5. Can I distribute my XML report specifications under other terms than the GPL?

Yes. The Lire Report Specification Markup Language used to define those reports is publically defined and no patent is held over it, so you are free to choose whatever license terms please you for them.

Remember though that if your license terms aren't compatible with the GPL, your report specifications cannot be included in Lire's distribution.

6. I want to reuse your file formats (DLF format, XML report) in my project, but I want to release this project under a MIT X-like license, may I?

Yes. Those formats aren't protected by any patent so you are free to write software that read and write files in those formats if you find them convenient for your project.