root/tags/lgt2372/CUSTOMIZE.txt

================================================================
Logtalk - Open source object-oriented logic programming language
Release 2.37.2

Copyright (c) 1998-2009 Paulo Moura.        All Rights Reserved.
Logtalk is free software.  You can redistribute it and/or modify
it under the terms of the "Artistic License 2.0" as published by 
The Perl Foundation. Consult the "LICENSE.txt" file for details.
================================================================


This file contains detailed instructions for customizing your Logtalk 
installation and working environment. Customization is mostly done on a 
per-user basis by editing configuration files on the Logtalk user folder 
(whose path is stored on the LOGTALKUSER environment variable; this folder 
can be (re)created by running the "cplgtdirs" shell command). The default 
paths for the Logtalk user folder are:

    POSIX systems: $HOME/logtalk
    Windows: My Documents\Logtalk


1. SETTING LIBRARY PATHS

In Logtalk, a library is simply a directory containing source files. Library 
paths can be declared using a dynamic predicate. This allows compiling and 
loading of libraries and library files using the library names instead of the
full library paths.

Inside your Logtalk user folder, you will find a "libpaths" folder containing 
a sample file which, when loaded, defines the library paths for the Logtalk 
standard library and for all the supplied examples. This file may need to be 
edited to match both your Logtalk installation and your Prolog compiler and 
operating-system requirements. For details, see the "libpaths/NOTES.txt" file.


2. CUSTOMIZING LOGTALK SETTINGS

Logtalk interfaces with a specific Prolog compiler using a configuration file 
that can be found on the "configs" folder in the Logtalk installation folder.
These configuration files define default values of the flags that are used by
Logtalk when compiling source files. For a full description of these flags, 
consult the "Writing, Running, and Debugging Logtalk Programs" section of the
User Manual. 

You may customize the Logtalk compiler flags by editing the "settings.lgt"
file in the Logtalk user folder. Settings in this file override the default 
values in the configuration files. Some of the default flag values that you
may want to change include:

* "startup_message" and "report"
- for less verbose startup and compilation reports
* "altdirs", "tmpdir", and "xmldir"
- to chose where to store temporary compilation files and documenting files
* "xmldocs", "xslfile", "xmlspec", and "xmlsref"
- to control the generation of documenting files
* "portability" and "underscore_variables"
- essential if you're writing portable Logtalk applications
* "smart_compilation"
- for avoiding recompilation of unchanged source files

Be sure to read the "configs/NOTES.txt" file for Prolog specific compatibility
notes; some Prolog compilers do not support some of the possible compilation
flags values.


3. CUSTOMIZING DOCUMENTATION PROCESSING SCRIPTS AND SUPPORTING FILES

Inside your Logtalk user folder, you will find a "xml" folder containing a 
set of shell scripts, CSS and XSLT style-sheets, and DTD and XML Schema files 
for processing the XML documenting files that are automatically generated 
when you compile source files. You may want to customize the CSS and XSLT 
files to modify the layout or style of the resulting PDF/(X)HTML files or to 
write new scripts and transformations to generate other formats. You may also 
edit the file "custom.ent" in order to specify XML entities for your personal 
data that can be used on Logtalk documenting directives. For details, see the 
"xml/NOTES.txt" file.


4. ADDING SUPPORT FOR EDITING LOGTALK SOURCE FILES TO TEXT EDITORS

Inside your Logtalk user folder, you will find a "wenv" folder, containing 
configuration files for several text editors, which add support for syntax 
highlighting and other text editing services for Logtalk source files.
For details, see the "wenv/NOTES.txt" file.