# Direc­tory support/nlatexdb

Nlatexdb Version 0.03
Database Access in LaTeX
Copyright (C) 2011 Robin H�ns, Integranova GmbH

This program is free software: you can redistribute it and/or modify
the Free Software Foundation, either version 3 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.  If not, see <http://www.gnu.org/licenses/>.

1. Why nlatexdb? The history...

A few years ago, I wanted to do database reports, and MS Reporting
Services appeared rather inconvenient to me. So I figured I'd use the
typesetting power of Latex, and I found latexdb by Hans-Georg E�er
(http://privat.hgesser.com/software/latexdb/). The idea was great, but
unfortunately I couldn't make it run under Windows, so I wrote a clone
in Ruby, called ratexdb.

At the time, Ruby had a convenient and powerful database access
package called DBI, so I really didn't have to write much code in
order to support a whole bunch of data sources. Great! In the next few
years, I fixed some bugs, added some nice features at the request of
helpful users (thank you!), -- and then I got a new computer.

I installed Latex, I installed Ruby, and it turned out DBI wouldn't
work any more. It seems that people have chosen than from now on DBI
shall be deprecated, there is a new thing called RDBI, and everybody
should use that. I tried it, it didn't work. It depended on some
packages, and those packages on some other packages, and I can't
really claim I had a good time installing all these packages.

So what did I do? Well, I had a good time rewriting the whole thing in
C# -- since my Ruby code was rather ugly anyway, I decided this time
I'd do it a bit more cleanly. Most of the code was written in a
delayed train, so thanks to the Deutsche Bahn for making this program
possible.

2. I know latexdb, and I'm in a hurry. What are the improvements over
latexdb?

- You can connect to a wide variety of data sources, as supported by
.Net DbProviderFactories.

- One executable only, one language. Works under Microsoft .Net 2.0 or
above as well as under Mono.

- Latexdb writes a series of output files for nested queries. Nlatexdb
writes one output file only, nested queries are done by recursion.

- Added the \texdbif{##query}{latex stuff} command: Include "latex
stuff" only if the query returns at least one row. This is useful
for table headings, which can be omitted if there is no data anyway.


(To be read: First any string, then a point, then a second string, to
be replaced by the first string only.)

(Note: In ratexdb the regex syntax was a bit different. E.g. referring
to a matched group was done with "\1", not "\$1". Go figure.)

Regular expressions are a very powerful tool. If you don't know them,
look them up on the web.

The regular expression replace strings may contain Latex commands. The
special characters in these will not be replaced. For example:

\texdbdef{##sexample}{select sex from
person}{##sex/\Am\Z/\textbf{male}/\Af\Z/\textbf{female}}

(Note the \A and \Z which stand for beginning and end of the
string. Without these, "m" would be replaced by "\textbf{male}" and
afterwards by "\textb\textbf{female}{male}"!)

4.3.3. \texdbfor

This works just like in Latexdb.

\texdbfor{queryname}{latex stuff} will connect to the database,
execute the query (previously defined with \texdbdef) and for each
returned row write the latex stuff to the output.

All variables defined for the query will be replaced by the values
read from the database. They can be used in Latex as well as in nested
SQL queries.

4.3.4. \texdbif

This is a new command that does not exist in Latexdb. It processes a
Latex block if the given query returns at least one row. This is
useful for tabular heads which should not even appear when there is no
data at all.

Here's an example:

\texdbif{##q3}{
\subsection*{File attachments}

\begin{tabular}{lr}
Name & Size \\
\hline
\texdbfor{##q3}{##att_name & ##att_size \\ }
\end{tabular}
}

If there are no file attachments, the whole subsection will be
omitted.

4.3.5. \texdbforfile

Usually, nlatexdb writes only one input file. If you need to produce
multiple output files, the command \texdbforfile is just for you. If
not, disregard this section.

It takes three parameters:
\texdbforfile{queryname}{filename pattern}{latex stuff}

The queryname and latex stuff work just like in \texdbfor. The
filename pattern contains the paths for the output files. It should
contain at least one variable from the query to be inserted into the
file name (Otherwise the same file will be overwritten again and
again... not good).

Note that as opposed to \texdbfor, the "latex stuff" should contain a
complete Latex file, from "\documentclass" till "\end{document}".
Of course, this will definitely confuse any Latex frondend you might
use. If you rely on one of those, I hope you don't need multiple
output files.

There is a small, clarifying example for this in the "examples"
directory, called testfile.tex.

This command works fine with the arguments -l and -p for Latex
postprocessing. Each output file will be processed by Latex. But of
course, unlike the normal way, the resulting dvi/pdf won't be renamed
to match the input file name.

4.3.6. \texdbcommand

This allows to send non-query SQL commands to the database. It is
especially useful for "SET" statements. E.g. if you wish to access a
MySQL database in UTF-8 mode, you can add this line to the TeX file:

\texdbcommand{SET NAMES utf8}

Of course, this command is only allowed after the \texdbconnection,
otherwise an error is issued.

5. Invoking nlatexdb

nlatexdb is called like this:

nlatexdb [-l|-p] [-v] [-o filename] [-e encoding] [-h] [-P]
<texfile.tex> [par1] [par2]...

If you give the -l parameter, the resulting texfile1.tex is processed
with latex, and the resulting texfile1.dvi is renamed as texfile.dvi.

If you give the -p parameter, the resulting texfile1.tex is processed
with pdflatex, and the resulting texfile1.pdf is renamed as
texfile.pdf.

If you give neither of these, only texfile1.tex is generated.

If you don't like the name texfile1.tex, you can give a different
output file name using the argument -o <filename>.

By default, encoding of input and output file is set to CP-1252. You
can change it with the -e argument. E.g. "-e utf-8" sets it to UTF-8.
In this case, don't forget to add "\usepackage[utf8]{inputenc}" to the
input file.

The -v argument turns on a rudimentary debug mode; some debug output
will be written to the standard console.

Behind the name of the .tex file, you can give optional parameters,
which can be referred to in the tex file as ##1, ##2 etc. This is
useful to generate a report for a special row, the ID of which can be
given on the command line. Of course only up to nine parameters are
possible, since the parameter names must be prefix-free.

6. Configuration

You can use the nlatexdb.exe.config file to change a few settings.
Currently there are the following possibilities:

The attribute "CmdLineArgumentVarPrefix" defines the prefix for
referencing the command-line arguments in the tex file. E.g. is you
set CmdLineArgumentVarPrefix="??", they will be referenced by ??1,
??2, etc.

The attribute "RegexSplitter" defines the character to separate the
variable names and the Regex search/replace pairs. By default this is
the character "/", but if you need it in one of your regular
expressions, you can change the splitter to something you don't need.

Similarly, the variables in the \texdbdef variable list are separated
by commas, but you can change that, too. Just change the attribute
"VariableSplitter" in nlatexdb.exe.config, if you need the comma in

But please, watch out you don't wreak havoc with these settings. If
you make them too crazy, you might not understand anything any more.

The <LatexCharReplace> section allows to add more characters to be
replaced by Latex commands. Thus, if the database contains characters
which will break Latex, you can add them here, so they will be
replaced by appropriate commands, like this:
<LatexCharReplace>
</LatexCharReplace>

7. Contact

Please, if you have a question, find a bug or like to propose an
improvement, contact me at robin@hoens.net.

8. Acknowledgements

Many thanks to Hans-Georg E�er for LatexDb.

9. Release history

2011-08-16 nlatexdb 0.03

More debug output.

2011-08-16 nlatexdb 0.02

Compiled under Mono for .Net 2.0. Should be more platform-independent.

Added exe.config file for some configuration possibilities.

Renamed from natexdb to nlatexdb (turns out there is somebody calling
himself natexdb... no need to create name clashes)

2011-08-05 natexdb 0.01

Initial release.

Down­load the con­tents of this pack­age in one zip archive (153.8k).

## nla­texdb – Database re­ports us­ing LaTeX and .Net (or Mono)

This is a com­pat­i­ble rewrite of DB (by Hans-Ge­org Eßer) or ra­texdb (by this pack­age's au­thor) in C#/.Net. It works un­der Mono, too.

It is a pre­pro­ces­sor which per­forms SQL queries on a database and cre­ates code for the re­sult­ing rows. Ra­texdb im­ple­ments a few im­prove­ments, e.g. reg­exp post­pro­cess­ing, com­mand-line op­tions, some pro­tec­tion against SQL in­jec­tion, re­place­ment of re­served char­ac­ters.

 Pack­age nla­texdb Ver­sion 0.03 Li­cense GNU Gen­eral Public Li­cense Main­tainer Robin Höns Topics pre­pro­cesses source be­fore us­ing TeX ac­cess database for doc­u­ment con­tents See also LaTeXDB