en/File Designation in lxr.conf

Writing adequate file paths in lxr.conf is a bit cumbersome but is the key to a faultless configuration: when to write absolute paths? when to write relative paths? what is the origin of relative paths?

To answer these questions, one must understand how the different files paths are used.

LXR relies on:

A "pure" HTML page generator
File references from pure HTML code can be written HTML-absolute (starting with a slash /) or HTML-relative (no initial slash).

So-called HTML-absolute references are relative to DocumentRoot, while HTML-relative start from the directory of the current document (omitting the partial path between DocumentRoot and this directory).
Note that the "current document" may not exist if the pure HTML code is embedded in a dynamically generated page. Depending on the web server, it may or it may not be the script file. Due to this uncertainty, HTML-absolute form should be used in dynamic pages.
With some complex web server configurations (e.g. a server with AliasMatch rules to a directory distinct from DocumentRoot), neither paradigm is sufficient without help of <base> information in the headers of the page. This HTML tag tells the web server how to resolve HTML-relative references.
To anticipate complex configuration, LXR systematically emits a <base> entity rooted at the LXR root directory.
Its own Perl scripts
Perl scripts are executed in their own environment. They know from which directory they were invoked, but this one has no implied relationship with DocumentRoot. To avoid as much as possible OS-absolute paths (which would prevent easy relocation of the scripts), they use a feature by which files are referenced relative to the script directory (called the LXR root directory in other pages of this site). These references will be called LXR-relative.
Users of Debian based distributions, amongst these Ubuntu, have reported malfunctions when using OS-relative paths. Consequently, considering relocation of LXR scripts to be rather rare, it is recommended to use systematically OS-absolute file paths.
The 2.0.3 configuration wizard has been modified to emit only OS-absolute paths.
Some auxiliary programs (such as glimpse)
These auxiliary programs are stored really anywhere in the computer, totally unaware of the web server, Perl or LXR. They are also executed as independant processes. The only way of designating them is to use OS-absolute paths.

Now, we can classify the file parameters.

Pure HTML parameters
Since these parameters are used virtually in any page whose location is unpredictable, you are strongly advised to use an HTML-absolute form for their designation. You must then move the file/directory under the DocumentRoot hierarchy if it is not the same as the LXR root directory (which can be the case if you want LXR to be a subpart of a wider site, not its own dedicated site).

Alternatively, leave the file/directory under the LXR root directory and use an HTML-relative form. Thanks to the <base> resolution, HTML-relative and LXR-relative forms happen to be the same.

'stylesheet' 'alternate_stylesheet'

copied in a <LINK REL="alternate stylesheet" … > tag of the page <HEAD> section, which means you may have to move the lxr.css file to an adequate location.

'sourceaccess'

used to access files through the Web server.

'iconfolder'

directory containing the file-type icons.
LXR-relative parameters (see recommendation above)

'html*' '*head' '*tail'

All templates are read by the LXR Perl scripts and internally processed to emit afterwards pure HTML code.

'filetypeconf'

read by initialisation code.

'genericconf'

read by the generic parser when initialising.
OS-absolute parameters

'tmpdir'

place where LXR can write temporary files

'glimpsebin' 'glimpseindex' 'glimpsedirbase' 'glimpsedir'

everything needed to use glimpse.

'swishbin' 'swishdirbase' 'swishdir' 'swishconf'

everything needed to use swish-e.

'ectagsbin' 'ectagsconf'

Everything needed to use ectags. Note that, although ectags.conf may be stored deeply inside LXR library, it is used exclusively by ectags, which explains why it needs an OS-absolute path.

'cvspath' 'gitpath' 'svnpath' 'hgpath' 'bkpath'

a collection of paths where to find the storage engine tools (cvs, git, Subversion, Mercurial or BitKeeper).

'sourceroot' 'sourcetext'

source-tree location (repository and check-out directory).

Other parameters, like 'virtroot', look like file paths but are partial URL paths.