SQLTeX documentation - Installing SQLTeX

SQLTeX documentation - Installing SQLTeX

Installing SQLTEX

Before installing SQLTEX, you need to have it. The latest version can always be found at http://freeware.oveas.com/sqltex. The download consists of this documentation, an installation script for Unix (install), and the Perl script SQLTeX, and a replace- file (SQLTeX_r.dat) for manual installation on non- unix platforms.

On a Unix system, make sure the file install is executable by issueing the command:
bash$ chmod +x install
then execute it with:
bash$ ./install

The script will ask in which directory SQLTEX should be installed. If you are logged in as `root', the default will be /usr/local/bin, otherwise the current directory.
Make sure the directory where SQLTEX is installed is in your path.

For other operating systems, there is no install script, you will have to install it manually.

On OPENVMS it would be something like:
$ SET FILE/PROTECTION=(W:RE) SQLTEX.²
$ COPY SQLTEX. SYS$SYSTEM:
$ COPY SQLTEX_R.DAT SYS$SYSTEM:
However, on OPENVMS you also need to define the command SQLTEX by setting a symbol, either in the LOGIN.COM for all users who need to execute this script, or in some group- or system wide login procedure, with the command:
$ SQLTEX :== "PERL SYS$SYSTEM:SQLTEX."

Configuration

The program starts with a configuration section. The default values are displayed here:

#
################################################################################
# Configurable part
#
$main::texex       = "tex";    # default tex- file extension
$main::stx         = "_stx";   # file name extension to insert before the last '.'
#
$main::cmd_prefix  = "sql";    # prefix for sql-commands (\sql<command>[]{})
$main::sql_open    = "db";     # database declaration, e.g. \sqldb[user,passw]{database}
$main::sql_field   = "field";  # select a single field from db, e.g. \sqlfield{select field from....}
$main::sql_row     = "row";    # select rows from db, e.g. \sqlfield{select * from....}
#
$main::less_av     = 1;        # Is the command 'less' available on this system ?
$main::more_av     = 1;        # Is the command 'more' available on this system ?
#
$main::repl_step   = "OSTX";   # Temporary value for replace
#
################################################################################
# Do not make any modifications below this line                                #
################################################################################

These values are default values; most values can be overwritten using command line options. When the command line options are omitted, the default values from the configuration section will be used.

$main::texex

The default file extension for L^ATEX file. When SQLTEX is called, the first parameter should be the name of the input file. If this filename has no extension, SQLTEX looks for one with the default extension.

 

$main::stx

An output file can be given explicitly using the `-o' option. When omitted, SQLTEX composes an output file name using this string.
E.g, if your input file is called db-doc.tex, SQLTEX will produce an outputfile with the name db-doc_stx.tex.

 

$main::cmd_prefix

SQLTEX looks for SQL commands in the input file. Commands are specified in the same way all L^ATEX commands are specified: a backslash (\) followed by the name of the command.
All SQLTEX commands start with the same string. By default, this is the string sql. When user commands are defined that start with the same string, this can be changed here to prevent conflicts.

 

$main::sql_open

This string is appended to the $main::cmd_prefix to form the complete SQLTEX for opening a database.
With the default configuration this command is ``\sqldb''.

 

$main::sql_field

This string is appended to the $main::cmd_prefix to form the complete SQLTEX to read a single field from the database.
With the default configuration this command is ``\sqlfield''.

 

$main::sql_row

This string is appended to the $main::cmd_prefix to form the complete SQLTEX to read one or more rows from the database.
With the default configuration this command is ``\sqlrow''.

 

$main::less_av & $main::more_av

These settings are used to determin how the help output should be displayed. If the command `less' is available on the current system, the output will be parsed through this program. Otherwise the output will be parsed through the program `more' if availeble. Both programs are usually available on Unix system (more is standard on most Unix systems), but ports for other operating systems are available as well.
Set the values to ``0'' for the program(s) that is (are) not available, or if you don't want to use it.
If none of these programs is available, the help output is plain echoed to the display.

 

$main::repl_step

Replacing strings is done two steps, to prevent values from being replaced twice. This setting--followed by a three-digit integer - ``000'' to ``999''--is used in the first step and replaces values from the first column. In the second step, values from the second column replace the temporary value.
If the first column in the replace file contains a character sequence that occurs in this temporary value, or if query results might contain the full string followed by three digits, this value might need to be changed in something unique.

 

Create replace files

Replace files can be used to substitute values in the output of your SQL commands with a different value. This is especially usefull when the database contains characters that are special characters in L^ATEX, like the percent sign (`%'), underscore (`_') etc.

When SQLTEX is installed, it comes with a standard file--SQLTeX_r.dat--which is located in the same directory where SQLTeX is installed, with the following replacements:

$       \$
_       \_
%       \%
&       \&
<       \texttt{<}
>       \texttt{>}
{       \{
}       \}
#       \#
~       \~{}
\       \ensuremath{\backslash}

These are all single character replacements, but you can add your own replacements that consist of a single character or a character sequence. To do so, enter a new line with the character(string) that should be replaced, followed by a TAB- charater (not blanks!) and the character(string) it should be replaced with.

If the first non-blank character is a semicolon (`;'), the line is considered a comment line. Blank lines are ignored.

The contents of the file are case sensitive, so of you add the line:
LaTeX \LaTeX\
the word ``LaTeX'' will be changed, but ``latex'' is untouched.

Different replace files can be created. To select a different replace file for a certain SQLTEX source, use the commandline option `-r filename'. To disable the use of replace files, use `-rn'.