1. Introduction

1.1 What is BRL and Why Should I Care?

BRL stands for Beautiful Report Language.

• Beautiful: It is easy to write BRL code that is understandable and maintainable, appealing to a programmer's sense of aesthetics.

• Report: BRL is particularly suitable for constructing output that is a mix of static and dynamic content, e.g. web pages, e-mail messages. Its greatest strength is constructing output from SQL databases.

• Language: The full power of a general-purpose programming language is there when needed. Simple examples are trivial uses of the language, but look more like templates than programming. The template system and programming language are more tightly integrated in BRL than in any other system.

Given this glowing description, a fair question is, why aren't more people using BRL instead of the 20 or so more prevalent tools out there for server-side web programming? There are several answers.

People haven't heard of BRL. There is no aggressive marketing campaign for it, other than this manual. Few people actually read this manual, because they think all server-side web tools are essentially the same. Why look at one more? Examples in this manual will show how BRL is different.

People use a win-stay, lose-shift strategy in their choice of software tools. Once they are familiar with one tool's strengths and weaknesses, they avoid the unknown. They develop strategies to work around systematic problems with the tool. Only when they see someone else doing better work in less time will they get the perception that they're "losing" and consider "shifting" to a different tool.

People hold misconceptions about Scheme. BRL is a "gentle-slope" dialect of the Scheme programming language. Scheme is taught in hundreds of universities, colleges and secondary schools worldwide. Scheme uses a syntax that is much less complicated than the C/Java/Perl family of syntaxes. It is popular for teaching Computer Science (CS) because instructors can spend a short time teaching the language itself, leaving more time to teach CS principles.

Here are answers to the most common misconceptions:

1. Scheme is a difficult language. This is true only when it is used to solve difficult problems. For simple tasks, its simplicity is hard to beat. Students who use Scheme in a CS course that tackles difficult problems often leave thinking it's the language that's difficult.

2. Scheme is slow. This may have been true in 1986, but isn't true today. In a simple benchmark, BRL outperformed PHP3, a tool used in many successful web sites. Even more performance could have been gained by choosing a faster servlet engine (JServ was used).

3. Scheme lacks an extensive function library. It's true that the standard Scheme specification is small. However, individual implementations invariably include more, including a "foreign function interface" allowing use of C or Java libraries. See section 4.10 Connection Pools and Other Java Objects, for an example of using Java objects while keeping individual BRL pages "pure."

   SLIB

4. Since Scheme is not prevalent in industry, it will be hard to find programmers. Programmers need to learn new tools throughout their careers. Those involved with server-side Java in particular must expose themselves to a constantly-changing variety of tools designed to keep Java code out of web pages. The time needed to learn enough Scheme for BRL programming is only a small addition to the time needed to get up to speed on a new project. A programmer with a Computer Science degree has likely done Scheme programming already. College is less likely to expose a student to WebMacro, Velocity or Tea.

1.2 About This Manual

This manual must cater to two audiences. One audience is investigating whether BRL is worth installing and trying out, and is interested in comparing BRL with competing tools. Another audience has already decided to use BRL and just wants to know how.

See section 4. Learning BRL by Example, if you're casually investigating BRL for comparison with other tools. If you get lost, skip back to the Intoducing Scheme chapter.

If you want to learn how to program with BRL, take this manual sequentially. While reading the BRL by Example chapter and the BRL Reference chapter, stop frequently to try out what you've learned.

In either case, please do give feedback as to how well the manual is working for you, or about additional features you would like to see in BRL. E-mail is appreciated. To: brlewis@users.sourceforge.net

Advocacy: This label at the beginning of a paragraph indicates material that is only useful for comparing BRL to other tools. If you've already decided on BRL and are just trying to learn how to use it, skip ahead to the next section break.

1.2.1 Further Help

If at any point in this manual you need further help, ask on Usenet. If you don't know what Usenet is, see Harley Hahn's What Is Usenet?

Different sections in this manual will mention different Usenet groups to consult. But if no other group is mentioned, BRL questions can be directed to `comp.lang.scheme', and comments to `comp.infosystems.www.databases'. Be sure to put BRL in the subject line to make sure your posting is not overlooked.

If you did not see a URL in parentheses after "What Is Usenet" above, you are probably looking at a printout of the PDF version of this manual. Look at the PDF version online to be able to follow the hyperlinks.

For those who cannot or do not want to post on Usenet, there are also BRL mailing lists.