Installing lpdoc

Author(s): Manuel Hermenegildo.

This documentation is outdated.

The source distribution contains all the source code and libraries and can be compiled on a supported Prolog system (lpdoc is developed using Ciao Prolog). The latest publically distributed version of lpdoc is available from http:://www.clip.dia.fi.upm.es/Software/Ciao. A newer version in Beta test is often available in http:://www.clip.dia.fi.upm.es/Software/Beta/Ciao.

Installing the source distribution (lpdoc)

  • Before installing lpdoc, you may want to read Other software packages required (lpdoc). Make sure that emacs is installed in your system

  • Uncompress (using gunzip) and unpackage (using tar -xpf) the distribution in a suitable directory. This will create a new directory called lpdoc as well as a link lpdoc-X.Y to this directory, where X.Y is the version number of the distribution. The -p option in the tar command ensures that the relative dates of the files in the package are preserved, which is needed for correct operation of the Makefiles.

  • Enter the newly created directory and if needed edit the file LPDOCSETTINGS.pl in a text editor, but in general the default options works well (edit the one in that directory, not the ones in the subdirectories).

    • Decide which Prolog/CLP system you will use for compiling lpdoc (actually, currently only Ciao is supported -- but porting to, e.g., SICStus Prolog should not be too difficult) and modify the first part of the LPDOCSETTINGS.pl file accordingly. The DOCDIR directory should not be an existing info directory, since this will overwrite the dir file in that directory.

    • Select the directories in which you want the lpdoc binaries, libraries, and documents installed, by setting the corresponding variables in LPDOCSETTINGS.pl.

  • Type lpmake all. This should create the lpdoc executable and compile related libraries.

  • Type lpmake install. This should install it in the BINDIR directory, install the lpdoc library in a separate directory in the LIBDIR directory, and install the lpdoc documentation in the DOCDIR directory.

  • In order for the lpdoc documentation to be available to users automatically, certain environment variables have to be set. The installation leaves files suitable for inclusion in initialization scripts (e.g., DOTcshrc for csh) in the lpdoc library.

Other software packages required (lpdoc)

The most basic functionality of lpdoc (generating manuals in .texi format, short manual entries in .manl format, generating index files) is essentially self contained. However, using the full capabilities of lpdoc requires having several other software packages installed in the system. Fortunately, all of these packages are public domain software and they will normally be already installed in, e.g., a standard Linux distribution. It should be relatively easy to get and install the required packages in other Unix-like packages or even in Windows, under the Cygwin environment.

  • Basic requirements: the Makefiles used by lpdoc require GNU Make (gmake), and for now have only been designed for UN*X-like operating systems.

  • Generating .dvi files: lpdoc normally generates .texi files (actually, a number of .texic files). From the .texi files, .dvi files are generated using the standard tex package directly. The .dvi files can also be generated with the GNU Texinfo package, which provides, among others, the texi2dvi command. However, Texinfo itself requires the standard tex document processing package. In order to use texi2dvi instead of tex when processing documents you should change the variable TEX in the Makefile.skel file in the lib directory before installing lpdoc. Generating the .dvi file requires that the texinfo.tex file (containing the relevant macros) be available to tex. This file is normally included with modern tex distributions, although it may be obsolete. An appropriate and up-to-date one for lpdoc is provided with the lpdoc distribution, stored in the lpdoc library during installation, and used automatically when lpdoc runs tex. The texindex package is required in order to process the indices. If you use references in your manual, then the bibtex package is also needed. texindex and bibtex are included with most tex distributions.

  • Generating .ps files: .ps files are generated from the .dvi files using the dvips command (this, again, can be changed in the Makefile.skel file in the lib directory). This command is included with standard tex distributions.

  • Generating .pdf files: .pdf files are currently generated from the .texi file using the pdftex command (this, again, can be changed in the Makefile.skel file in the lib directory). This command is included in current Linux distributions.

  • Generating .html files: .html files are generated directly from the .texi file using the texi2html command (this, again, can be changed in the Makefile.skel file in the lib directory). This command is a perl script and is included with the lpdoc distribution, and installed in the library (so that it does not overwrite other existing versions). It is also typically included in the Texinfo distribution. A required intermediate step is to resolve the link references which appear in the .texi file (the .texi file includes all the .texic files and has all references resolved). This is done using the emacs editor in batch mode, calling functions in the emacs-library.el file included in the lib directory of the lpdoc distribution. Thus, a recent version of emacs is required for this purpose.

  • Generating .info files: .info files are also generated directly from the .texi file using the makeinfo command (this, again, can be changed in the Makefile.skel file in the lib directory). This command is included in the Texinfo distribution. Resolving the link references in the .texi file is also required as above.

  • If pictures are used in the manual, and html output is selected, the commands pstogif and cjpeg are also required, in order to convert the figures from .eps to .jpg format.