"Linux Gazette...making Linux just a little more fun!"

lout is a markup processor written by Jeffrey Kingston which produces Postscript output instead of a device independent file. It's underlying design was developed by the author and it allows it to offer essentially the capabilities of LaTeX with the simplicity of maintenance and resource requirements of troff. At the same time it is easier to make changes to its behaviour than it is with the other two. The details of the design are beyond the scope of this article. It is described in the documentation and I will discuss where you can read about it in more detail at the end of the article when I discuss documentation.

Basser lout is an implementation of lout for the UNIX operating system and that is the one I will discuss. It is the one that would be installed on Linux. From now on when I say lout, I will mean Basser lout. The package provides special languages for graphics, tables, equations, and graphs as well as macro facilities. It is able to automatically handle cross references, create indexes, tables of contents and bibliographies from a database all in an integrated environment.

Installing Lout

lout can be obtained from ftp//:ftp.cs.su.oz.au/jeff/lout This article is based upon version 3.08 which is in the file lout.3.08.tar.gz.

There might be a newer version by the time you read this, but the author of lout tells me these step-by-step instructions will still apply.

I strongly suggest you also get lout.teq.2.0.tar.gz. You can have a preview of the users' guide if you get lout.3.08.user.ps.gz. This (after it is uncompressed) can be viewed with a postscript previewer or (its two hundred pages) can be printed out.

When you unpack lout.3.08.tar.gz (using tar -zxpf lout.3.08.tar.gz), you will have a directory called lout.3.08 which includes the source files, a makefile, several directories, and a few other files. Binaries are not provided. The makefile is very well written and the source compiles cleanly under Linux. I tried it with a.out using version 1.2.3 and with ELF using versions 1.3.35 and 1.2.20 of the kernel, and none of them gave any trouble. The instructions for how to compile are at the top of the makefile and you need make little changes to the original one. (If you are paranoid like me you will cp makefile makefile.dist before editing this file.) The mandatory changes are to reset the directories BINDIR, LIBDIR, DOCDIR, and MANDIR. If you have root privileges you can set them to whatever you like except that the installation process assumes that BINDIR, and MANDIR already exist. This is a good idea since BINDIR must be on every users' PATH and MANDIR must be in their MANPATH. If you are indecisive, let me suggest:

BINDIR = /usr/local/bin
LIBDIR = /usr/local/lib/lout
DOCDIR = /usr/doc/lout
MANDIR = /usr/local/man/man1

Most of the other macros should be left as is. Make sure OSUNIX is set to 1 and the others, OSDOS and OSMAC are set to 0 (zero). (They already were in my copy). That is:

OSUNIX = 1
OSDOS = 0
OSMAC = 0

CHARIN = 1
CHAROUT = 0
USELOC = 0
#LOC_FR = fr
#LOC_DE = de

Now just do make lout followed by make c2lout when this is finished, followed by make install. This last command does a lot, including customizing the installation to your setup. You have to do some hand editing of some files if your site doesn't use A4 paper. This is a matter of editing a text file with a text editor and it is well documented in the makefile. If you prefer your error messages in a language other than English. You will find instructions in the makefile for this.

The next step is to do make clean to get rid of all the extra files produced in the building of the binaries. This leaves the original sources intact. It also leaves your modified makefile intact. If you understand where the different files go, you might want to try it out before cleaning up, because if the installation procedure is at fault you can fix up your makefile and try again, saving compiler time.

If you have some time on your hands, you can test the installation by making the user's guide. The instructions are in a README in the DOCDIR/user directory. It takes some time, especially on a slow computer. If you follow the instructions the result will be a Postscript file called op. I renamed mine to users.ps and I keep it permanently in the DOCDIR/user directory set to be world readable. This, of course, requires a Postscript viewer. I strongly suggest that you have ghostview installed if you want to use lout seriously. The user's guide is a huge document of about two-hundred pages, complete with a table of contents and an index. You will eventually need it! If you don't want to make it yourself, you can uncompress lout.3.08.user.ps.gz.

As a quicker and far less exhaustive test you can use the file sample.lt that I use for illustrating the language below. It is complete and self contained. lout writes a few files and leaves them on the disc when it is finished, for future use with the same document, so choose a directory where you have write privilege and will be able to easily locate and remove these extra files when you are through testing and experimenting with them. Here is sample.lt:

(1) @SysInclude{doc}
(2) @Doc @Text @Begin 
(3) @LD @Heading{Hello World}
(4) 
(5) Hello 
(6) -90d @Rotate{World Hello World 1.5 @Scale Hello}
(7) World Hello
(8) +45d @Rotate{World}
(9) Hello World Hello World Hello World
(10) @ShadowBox{Hello World} 
(11) .7 @Scale{Hello .7 @Scale{ World .7 @Scale{Hello}}}
(12) World
(13) red @Color Hello World! Hello World
(14) @Box paint{grey} white @Color{Hello World Hello World}
(15) green @Color 120p @Font .
(16) @End @Text

lout sample.lt>sample.ps

The Language

Like TeX, lout partitions characters into the categories: letters, punctuation, space, quote, escape, and comment. Letters are the upper and lower alphabetic and the character @. Punctuation characters are the usual ones including the various forms of braces and funnily enough, the numerals. Spaces are the space, tab, and newline characters. The last three categories have only one member each. Quote has ' , escape has \, and comment has #. The comment character at any place on a line in the source file causes lout to ignore the rest of the line.

You will deduce from the file sample.lt that commands start with @. That is a custom rather than a law. A command can be named by any string of letters. If you wish to write filters later to manipulate your source file using regular expressions, I suggest that you keep to the custom. This naming freedom comes with responsibility. Remember in sample.tex there were concatenations of commands with no space between them. TeX will deduce that a command has ended when it sees the sign of a new one beginning. This is not the case with lout. If lout sees a string starting with @ that it doesn't recognize as a command it notify you of the fact on the screen for your information. Look at last line of sample.lt. There are two commands @End and @Text. If you were to forget the space between them and write @End@Text, lout would see that the string is not bound to a known command and would treat it like text. Seeing that it starts with an @ it would politely warn you that the command is unknown. On the other hand if line (13) were to start with red@Color, the string would just be typeset literally with no warning. There is no command \Color as part of standard TeX but if there were and you wrote red\Color, TeX would still know that \Color was a command.

Another unusual feature of the lout markup language is that its commands take arguments on both the left and on the right. The command Color takes the color as the left argument and the text to bear this color as a right one. Our example at the beginning of line (13) will print "Hello" in red. In general arguments that control things go on the left and arguments representing things acted upon go on the right, but again this is custom rather than law. The name of a command is delimited on the left and on the right by either a space or a punctuation symbol. So, as a matter of fact, line (15) could have been written green @Color 120p @Font. (No space between "Font" and ".".) The same would be true if the period were replaced by the numeral 1, but if the period were replaced by the letter "a" the space would be necessary.

lout works recursively by creating more complex objects out of simpler objects. A character is an object. A catenation of characters form an object. A command applied to a string of characters forms an object, and so on. The whole document is an object. The general rule for lout is that a space in the source file between objects produces a space in the final document, but space needed to delimit objects does not. This is consistent for any character in the space category. That is "Hello" separated from "World" by five space characters will be the same as if they were separated by five newlines which is the same as if they were separated by five tabs. All would result in there being five spaces in the final document.

Let me go through sample.lt. Line (1) tells lout to read the file doc in the directory LIBDIR/include. This is called a setup file. It gives the general layout parameters such as margins, spaces above and below headers, style of page number, etc. It also calls in two other files called docf and dl in the same directory. These provide the standard commands. You can copy any of these to your working directory and modify them. You would then call them by the command @Include instead of @SysInclude[footnote 8. If you know something about SGML you will see a similarity.. If they are in a different directory from the working one, you must give an absolute pathname. There are no environment variables to specify your private cache of setup files, but a directory can be specified on the command line with the -I flag. I suggest that you make a directory called something like myinclude in your home directory and alias the command lout to lout -I ~/myinclude. Then invocations of lout will cause a search in myinclude for any files specified by the @Include command. The next line contains a standard invocation to begin the text part of a file. These three commands or longer substitutes must be in each file.

Line (2) is the statutory declaration for the actual text to begin and line (3)is the first line of the document. The string @LD there is the command for a Left Display. This groups its argument into an object and leaves suitable vertical space above and below it. The default is one line above and one line below. It justifies its argument with the left margin. If @LD were replaced by @D, the display would be centered. The @Heading{Hello World} makes a new object consisting of the string Hello World with the font size and face for a heading. By default this simply is bold face at the same size as the body. This illustrates lout's behaviour with respect to arguments. A string up to a white space is considered a single argument. Here is an analysis of the formation of the header. {Hello World} is an object. Thus @Heading acts upon the object {Hello World} to make a new object which is the string "Hello World" placed in bold face. Then @LD acts on this object to place it vertically the way a display should be placed and to align it with the left margin. The net result using the default settings will be "Hello World" in bold face with a blank line under it.

Line (4) is blank. Recall that this will produce a single space in the document. Since the header ends the line, this won't be visible so the blank line has no effect. In contrast, the other formatters treat two newlines differently from one. I like this consistency, but I have the same complaint about taking newlines literally as I do with troff. lout offers the option of using either TeX's or troff's treatment of white spaces instead of the default one. The TeX rule consistently collapses multiple spaces into one space. Unlike "real" TeX, a blank line will just produce a space in the document and not a new paragraph. In my opinion this is the best of all worlds. If you want to go this route then you have to write a macro equivalent to TeX's \hspace which requests that a specific amount of horizontal space be left. I will show you one such later when I discuss macros.

Line (5) begins the body of the section. Line (6) uses a facility that is unique to lout. The command @Rotate rotates the object appearing as the right argument by the amount specified in the left one. I haven't discussed the units of measure used by lout but you can guess that d denotes degrees. Rotations are by default counter-clockwise so -90d means rotate ninety degrees clockwise. The object to rotate is the complicated one to the right in curly brackets. I have put other geometric operations inside this object. The last "Hello" in the rotated string is the subject of the command @Scale which means to scale it. The argument on the left says how much, in this case a factor of 1.5. A scaling factor being a pure number needs no units. Note that the victim of the scaling has no curly braces around it. This is because it is automatically delimited by a white space.

Line (7) consists of simple text, because it is on a new line, it is separated from the rotated object by a space and so is a new object with a space before lt in the final document.

Line (8) is another rotation, this time forty-five degrees counter clockwise. The brackets around its argument "World" are not necessary, I just put them there to show that you can if you want.

Line (9) is just plain text. So far everything I have described will be set on the same line. It is indeed a high and very deep line because of the rotated objects, but nonetheless a line. The horizontal and vertical spacing needed for it has been taken care of automatically.

Line (10) puts "Hello World" in a shadow box. One of those things that have a shadow in the lower right corner to give a three dimensional effect.

On line (11) "@Scale" has as its argument the object {.7 @Scale{ World .7 @scale{Hello}} and .7 as a parameter. This, in turn has the object .7 @Scale {World .7 @Scale {Hello}} as its argument and .7 as its parameter, and so on. The net result is of the three words "Hello", "World", and "Hello" each one smaller than the one on its left. This illustrates the recursive nature of lout in building new objects out of already created objects. (I chose those particular ones to taper off because this is the end of the first line using the default page setup.

You can guess that line (12) adds a bit of color to the document. The only thing to remember is that only the "Hello" will be red. The use of the colors offered by Postscript are built in to the formatter. With a black and white printer the color just won't show up, but there will be no error generated.

Line (14) looks complicated, but it follows the rules of lout syntax and is hence was not hard to create with the documentation in front of me. The first command is @Box which draws a rectangular box around its argument. Some commands can take options and @Box is one of them. The paint option specifies what color to "paint" the inside of the box. The next part is the object inside the box. The thing in the box is a white colored string "Hello World Hello World". Note that there is no need to put curly braces around the whole thing because white is an argument to @Color and the whole shebang just makes a white object.

This is further illustrated on line (15) where a huge period is colored green. The new command is @Font which takes a left and a right argument. The left one is the size and the right argument is the subject of the font change. In this case we produce a period in a one hundred-twenty point font and color it green. You might have noticed that troff allows relative font changes to be additive. That is you can ask that a font be made larger or smaller by so many points. Although I didn't illustrate it, TeX on the other hand favors multiplicative relative changes, that is you can change to a multiple of the font size. lout offers both. You can specify an additive change by +2p @Font, which will add two points to the current font size, or you can specify a multiplicative change by 1.2f @Font. The unit f denotes the current font size and 1.2f means the current font size multiplied by a factor of 1.2. Line (16) contains the compulsory command to end a document. It must be put in all documents.

If you have ghostview installed, and if you have the file sample.lt on disk, you can preview it by first doing lout sample.lt > sample.ps and then ghostview sample.ps when the prompt returns. If you have a color monitor and a color X server you should see the color effects. You can, of course, print the Postscript file.

There are packages provided as part of the distribution for tables, equations, graphics, and graphs. These are more integrated than they are in troff. The equation one is very similar to the eqn of troff. The example I gave for troff will work with lout almost verbatim. In the section on installation I strongly suggested getting lout.teq.2.0.tar.gz. This is a modified equation package using Computer Modern Fonts for the mathematical symbols. I have made some tests and I think the results do look better using it. There are instructions on how to use it in the documentation. If you plan to do a lot of mathematical typesetting you should install it. It is dead easy to do. Just edit the makefile that comes with the package to tell it where the various files for lout have been installed. and do make. No compiling or linking is performed and the process is quick. According to the literature that comes with the distribution, this packages has not been included in the lout distribution for legal reasons. The creator of the fonts requires conditions in the license that are not compatible with the GNU license under which lout is distributed.

The tables package has a different syntax from that of troff, but seems to operate with the same philosophy. The results are good with the examples I played with but it doesn't offer the scope and flexibility of tbl for making really complex non-standard tables; but then again, what does?

As I said, graphics are built into lout. Nonetheless there is a graphics package to provide you with advanced features. It provides the basic objects usually found in drawing packages such as squares, circles, ellipses, and Bezier curves. These are all parameterized to allow relevant specification of size and shape. Many of the commands and parameters are lout versions of Postscript command. The important difference is that lout does the formatting whereas Postscript requires you (with the help of its programming constructs) to account for every point on the page. troff's pic package offers two levels of drawing. One is a "user-friendly" level in which you describe the drawing verbally and one that is more complicated to use which serves as a basis for the other level, and which allows automating some drawing operations which would otherwise be tedious. lout's instruction set seems to lie somewhere in between. On the other hand it is more manageable for the casual user than TeX's xypic package.

There is also a package for producing graphs, and one for formatting C and Pascal code from the sources. My line of work doesn't involve using them and I haven't tried them as yet.

lout as it is distributed is not likely to require extra macro packages. You can do just about any job you need by modifying the existing ones. It, of course, also has facilities for writing your own commands. Let me give you a simple one called @Hspace. If you take my advice and use the TeX spacing option you will find it useful:

def @Hspace
right x
{|x}

The documentation that comes with lout instruct you to put definitions (macros) in a file called mydefs which is automatically read in when lout processes a document. I have experimented with putting them in source file along with the text with varying success. Ones that only use primitives, like @Hspace, can be put at the very top of a document before the SysInclude command. Others that use commands like @Color seem not to work unless they are in mydefs.

A consequence of the liberality of naming commands is that if you write the definition

def teh
{the}

I have used the word recursive in an informal sense above, but lout is recursive in the technical sense also. You can call a command within itself. This is the underlying principle behind its design. There are useful recursive examples given in the expert's guide. Reading it will give you some idea of how lout is implemented. I recommend chapter 1 of the expert's guide for general reading. I will give a useless but fun example here that I hope will illustrate the point. The lines

def @Banner
{red @Colour Hello blue @Color World @Banner}
@Banner

This recursive behaviour is used more seriously in the implementation of lout. It is one of the "secret ingredients" that allows lout to offer so many facilities in such little space. See the "Expert's Guide" that comes with the distribution for more details.

lout like LaTeX is a logical markup language. The author indicates what textual elements he or she wants at a given point and the formatter will take care of the details. With different kinds of documents these details might be different. For example a section in a book is numbered differently from one in a simple article. Like LaTeX, lout takes care of these differences by providing different style files for different document structures. The ones offered in the distribution are the doc, report, book, and slides. The doc style is for simple basic documents such as a scholarly article. The report style is for technical reports. The book style is obviously for books, and the slides style is for making one or a series of overhead projector slides. If you have a color printer, you can use the color facilities in lout to great advantage with the slides style. There are variants of each of these files for output other than Postscript.

It is difficult to change the defaults in LaTeX style files. I gave an indication of such a change. It is easier in troff except for the somewhat artificial devices of setting registers with strings of numbers. Syntactically, lout is dead easy to change. The only difficulty is in knowing where to put the changes. You are told this in the documentation.

Let me give an example. Suppose you want to change the doc style so that it more closely imitates the output of troff's mm macros. (Not that I recommend doing this!) In particular you want to set the default font size to ten points, you want to make block style paragraphs the default style, and you want the headings to be in italics. Assume that you wish to do this locally rather than system-wide. Then you have to make yourself a new style file to change the paragraph style. First copy LIBDIR/include/doc to the working directory call it troffdoc. Now open up the file with a text editor. You will see the following near the top of the file.

@Use { @DocumentLayout
 # @InitialFont { Times Base 12p        } # initial font
 # @InitialBreak        { adjust 1.20fx hyphen  } # initial break
 # @InitialSpace        { lout  }# initial space style
 # @InitialLanguage     { English       } # initial language
 # @InitialColour       { black } # initial colour
 # @OptimizePages       { No    } # optimize page breaks?
 # @HeadingFont { Bold  } # font for @Heading
 # @ParaGap     { 1.30vx        } # gap between paragraphs
 # @ParaIndent  { 2.00f } # first-line indent for @PP
 # @DisplayGap  { 1.00v } # gap above, below displays
 # @DisplayIndent       { 2.00f } # @IndentedDisplay indent
 # @DefaultIndent       { 0.5rt } # @Display indent
 ........

All three formatters offer facilities for making cross references and a table of contents. LaTeX and troff offer an interface with programs that will automatically produce bibliographies from databases and indexes. lout is unique in offering these two built in. Given that you want these features, lout is the easiest of the three formatters to install, maintain and use. My installation takes up 4.3Mb and this includes the teq package that I recommended and a package for producing bar codes. This makes it a pretty modest formatter.

I spoke about the ensemble of the other two programs. There is not much to say about that for lout. Everything is built in and is accomplished by using flags on the command line or by requesting that the relevant files be read in. Each setup file has a list of parameters at its beginning. You can change them, or you can change this parameter in your source file. For example, I made some changes to how the section headers would look in both LaTeX and troff. To change spacing above and below the header in lout I would simply put @DisplayGap{.75v} at the beginning of my file. This would change the default spacing of one space to three-quarters of a space and make the document more compact. This is considerably simpler than what must be done for LaTeX. It is easier to remember than the somewhat artificial method in troff of setting a string register.

One problem with TeX has always been that it takes an expert to manage. Unfortunately most system administrators are not interested in test formatting and so in many sites an "off-the-shelf" version is installed and the users accept the defaults or learn to change them themselves. On the other hand, a system administrator who knows nothing about lout could change the relevant line in the LIBDIR/include/doc file to read as above and the change will be universal. Ordinary users can make their private default by writing out the parameters to be changed in a file on the path specified by the -I flag described earlier. In extreme cases they can even copy the default setup file to such a place and modify any or all the parameters. With a modified doc in a private directory @Include{doc} is placed at the top of the document instead of @SysInclude{doc}.

I mentioned earlier that lout produces a Postscript file where the other two produce device independent ones. This means that the lout language can offer equivalents of all of the Postscript geometric and color commands. Since these commands are programmed into the formatter, it puts the objects created by them in a first class box. This is as opposed to Tex and troff which allow Postscript commands to be sent to a suitable driver while ignoring them during the creation of the device independent file. In this case it is up to you to provide a second class box to make room for objects created and/or transformed by the Postscript commands. The price you pay for this is a loss of device independence. ghostscript fixes a lot of this problem (see the section on Postscript) but if you have a high quality non-postscript laser printer with resident fonts, you have to abandon those fonts and get new ones. Your gain is the added flexibility of Postscript though.

The new version of LaTeX, LaTeX2[epsilon], has a package called graphics that extends the markup language to allow for rotation and scaling. There is another package called color that extends the language for employing color. Packages come out as the need for them becomes clear. For example there is one called fancybox that makes shadow boxes. However, graphics and color will only work with certain Postscript drivers at present. Thus you have to give up device independence when you use them. (I can't give you the complete collection of packages needed to match lout's capabilities. The documentation with some of them is scant. Keep in mind, however, that LaTeX2[epsilon] is in an experimental version. LaTeX3 when it comes out might have a complete package for graphic which can then be documented in the "standard literature".)

I have been assuming that documents consist mainly of text with incidental graphics inserted. There are other kinds of documents, such as advertising layouts, that should be looked at as graphics with incidental text inserted. For the reasons given in the last paragraph, lout has to be considered as the best tool for this. Closely related to this is the option of producing Encapsulated Postscript (EPS) which produces graphics files meant to be included inside a larger document. This option is invoked with the -EPS flag.

lout also offers the option of producing ASCII output. In order to do this you use the -P flag on the command line and change whichever setup file you are using to one with an "f" attached to its name. (So you would have @SysInclude{docf} in place of line (1) of sample.lt. This will not be necessary in the next version, doc will work with both outputs. If one is to judge from the text newsgroups, being able to produce both ASCII for on-line documentation, and high quality hard copy with the same source file is a very desirable feature. It is one shared by troff but not by LaTeX.

There is a trend to use fonts other than the standard Adobe fonts provided with Postscript printers. Traditional fonts like Garamond and various exotic fonts for special purposes can be bought for a reasonable price nowadays. lout is the easiest formatter in which to install new fonts and I will close this lout specific section by outlining how to do this.

First of all, with your new fonts you should have a set of outline (glyph) files. They have the extension .pfa or .pfb and they are of no concern to lout. They are installed in your postscript printer or in ghostscript. See the earlier section on Postscript for instructions on how to do the latter.

Secondly you should have a set of metric files. These are what lout wants to work with. These files have the extension .afm for "Adobe font metrics". lout uses these without modifications.

I will continue to use LIBDIR to denote the directory in which the lout library has been installed (/usr/local/lib/lout by default.) There is a directory called LIBDIR/font and that is where the font metric files are placed. You can give them any name you like that doesn't coincide with the ones already there. The default fonts have names in mostly in capitals without an extension. They are abbreviations that describe the font. For example Times Roman is denoted by TI-Rm and Times Italic is denoted by TI-It. To make things more concrete let me use the same Charter fonts that I installed in ghostscript earlier as a running example.

There are four files for the Charter fonts (at least in my version): bchr.afm, bchri.afm, bchb.afm, bchbi.afm. (By the way, the initial "b" in the name is for Bitstream the producers of the font.) These are the metrics for Roman, Italics, Bold and Bold Italics respectively. I have decided to call them CH-R, CH-I, CH-B, and CH-BI in the lout installation. I copy the files into LIBDIR/font with their new names. For example cp bchr.afm LIBDIR/font/CH-R. If you are sure you won't need them for something else, such as installing them in TeX or groff then you can move them instead of copying them. They are now installed and the next step is to tell lout about them.

Change to the directory LIBDIR/include and open the file fontdefs with a text editor. This file has long lines that should not be broken so make sure your editor is not set to automatically break lines. The file will be hard to read with a standard eighty column screen, but there is not much to it. If you are using X you can elongate the window.

The general format of the file is all in one line:

fontdef <lout family> <lout face> {<zPostscript> <font-metric file> <character map file> <Recode?>}

Next, where to put the entries for your new font. The existing fontdefs file starts out with all of the font definitions that come with lout. Put you new ones right after them. So scroll down the file until you see the last line starting with fontdef and put yours right underneath. Comments are denoted by # at the beginning of the line so you complete entry can look like:

### Added by me 1 December 1996
fontdef Charter Base    {CharterBT-Roman        CH-R    LtLatin1.LCM    Recode }
fontdef Charter Slope   {CharterBT-Italic       CH-I    LtLatin1.LCM    Recode }
fontdef Charter Bold    {CharterBT-Bold CH-B    LtLatin1.LCM    Recode  }
fontdef Charter BoldSlope       {CharterBT-BoldItalic   CH-BI   LtLatin1.LCM Recode }

@SysInclude{doc}
@Document
 @InitialFont{Charter Base 12p}
//
@Text @Begin

Note that you are free to assign lout font families to any set of font files as with the virtual font construction in Tex. That is you can take Base from the font foo with official Postscript name foo-Roman and Slope from the font bar with official Postscript name bar-Italic. If you call this new font Newfoo, your entry in the fontdefs file will begin like this

fontdef Newfoo Base {foo-Roman ...
fontdef Newfoo Slope {bar-Italic ...

All that I have said about installing fonts assume that the fonts are encoded with eight bits. This means that eight bit words are used to describe each character in the font, allowing a font to contain 256 characters. If you use TeX you might be aware that the original version only used seven bit words to name the characters in a font. This was changed in later versions, but the Computer Modern fonts weren't recoded for this change. The result is that each standard TeX font can only have 128 characters. What gets left out are the European special characters that are not used in English (various accents, crossed out els, etc). Instead they are formed by digraphs--the overstriking of two different characters. lout assumes that these extra characters are available and it is not set up to form digraphs[footnote 9. Of course macros can be written to form them.]. Other symbols that are on the ordinary alphabetical fonts in Postscript are to be found on the Computer Modern symbol font and code has to be written to point lout in the right direction. Thus if you want to install a Postscript version of the Computer Modern fonts in lout, such as the free BaKoMa ones, you have to do a lot more work. There is an eight bit encoding of the Computer Modern font now, sometimes known as the "Cork encoding", and when a Postscript version of these comes out, it will be easy to install Computer Modern in lout.

Summary

In a nutshell, lout offers all of the capabilities of LaTeX requiring considerably less resources. It doesn't do quite as good a job putting together the fragments that make up large delimiters, large square root signs, and the like, but it still does a good job. The difference is small enough so that I wouldn't use it as a criterion for choosing one above the other. All three of the formatters I described do a good job with bread and butter typesetting, that is line and paragraph breaking and and sane hyphenation. I wouldn't make my choice on this basis either.

lout seems to run slower than LaTeX for an equivalent job and requires more passes to resolve references that are written to an extra file, such as cross-references. If you have a slow machine, or do huge documents with a lot of cross-references, tables of contents, and so on, and if time is a factor, then you might find lout to slow for you. On the other hand, lout allocates memory dynamically and so you won't run out of memory with a complex document as you can with LaTeX.

Like LaTeX, lout offers logical markup and it is far easier to customize the layout files than it is to customize LaTeX style files. On the other hand, TeX offers a more convenient macro interface. You can write them anywhere in the document or in a separate file to be input at any point of the document, whereas with lout you have to write some in a separate file which is kept in the working directory. (There do seem to be comands that change the scoping rules, but they are not well documented.) This is hardly a disadvantage if you use one directory per document, or if you group small documents that need the same macros in the same directory, but if you keep several documents in the same directory, each needing macros with the same name, but with different actions, then you will have to do some editing of the layout file. It also makes it difficult to send a document in a single file if it uses user-defined macros. Many TeX-perts feel that it is a bad idea to put all of the macros in one file anyway; for the same reason it is not a good idea to have all of the source in one file for a large programming project. In the case of TeX, there is enough difference in different installations so that often a large document produced in one site has to be mildly edited before it is processsed or printed at another. It is far easier to find these problems if the document is logically divided into modules. (I tend to tar, gzip and then uuencode my documents before sending them by email. They pass safely through the most primitive mailing routes this way. It does depend upon the person on the other end having versions of uudecode, gunzip and tar, but there are versions of these for most operating systems.)

Of the three formatters that I described, "Barefoot" LaTeX is the weakest for drawing facilities lout is the strongest. LaTeX with suitable packages and lout as it is produce geometric transformations of objects in first-class boxes, lout is the more versatile. The gpic package that comes with groff falls down in that department, but it is by far the most user-friendly package for drawing. It can be used to produce pictures that can be imported into LaTeX with the -t option which turns it into a GNU version of tpic (as usual with more features than the original.) Pictures made with gpic can be saved as Postscript files and easily imported into lout.

You have to buy troff and LaTeX documentation. There are standard books for LaTeX which I mentioned earlier. The other book that should be on your shelf if you use LaTeX is "The TeXbook" by Donald Knuth, also published by Addison Wesley. A new version of LaTeX2[epsilon] is issued every six months so there is no chance that any book can keep up-to-date. New packages usually come with documentation, but sometimes it is pretty scant and requires considerable knowledge of TeX to decipher. Problems and solutions are usually posted in the comp.text.tex newsgroup. Good books on troff, and especially the mm macros are getting hard to find. My favorite, which is out of print at present, is "UNIX Text Processing" by Dougherty and O'Reilly, published by Hayden. O'Reilly and Associates also publish the Berkeley 4.4BSD User's Supplementary Documents which contains documentation on troff but doesn't discuss pic or the mm macros. There is no newsgroup for troff specifically, but it problems and solutions are often posted to the comp.text group.

lout comes with its own documentation. The user's guide is a book and compares with the textbooks for the other processors. If you want to go deeper into its internal workings there is the expert's guide. There are examples in both of them. I have bound the user's guide in two parts. The first comprises chapters 1-5 which contains the document formatting information and the second comprises chapters 6-11 which contains information on the individual packages. You won't see textbooks on lout on the shelves of bookstores and so if don't like the documentation provided, you are stuck. There is sometimes discussion on comp.text about lout and there is a mailing list. To subscribe send an email to [email protected] with subscribe in the Subject field.

I haven't said much about recovery from error. All of the formatters are pretty cryptic in this department. lout and troff are both the strong silent type that only say something when they need to. If lout runs into an error it will give you the line and the relative place on the line where it is detected. Raw troff gives nothing away except that there is an error. It does provide macro writers with a mechanism for error reporting and the mm package is pretty informative. TeX gives you a running commentary of what pages are being output, and what files are being read in. When it comes upon an error it gives tells you in what file and in what line of the file the error was found. It also opens an interactive window and offers several options for handling the error. I mentioned some of the more interesting ones earlier. This constant activity on the screen while TeX is running might make it appear to finish faster than lout which leaves you staring at a blank screen until something goes wrong. Just as you have to learn how to write markup, you must learn how to interpret error messages. I know from experience that you get better with experience.

There are what I would call external disadvantages to using lout. By that I mean those that are caused by the fact that it is relatively new and not used by a large number of people. This means, first of all, that you won't find, for instance a "lout mode" written for the emacs editor. Although the drawing facilities that come with lout are pretty extensive, they need some "sugar coating". For example, it is a nuisance to draw commutative diagrams in the present language[footnote 9, I assume from browsing the site ftp://ftp.cs.su.oz.au/jeff/lout that there is a commutative diagrams package in the offing.]. I would like a more user friendly way of putting named blocks of graphics together. (See Chapter 9 of the User's guide for how it needs be done at the present.)

The other external disadvantage is that publishers are most likely not equipped to handle lout source code. For camera-ready documents this is no problem, but if the camera-ready source is to be produced by the publisher, then the entire document will have to be re-keyed. Similarly if you want to email a source file to a colleague, he or she will have to have lout installed to read it.

To some extent these are problems that can fix themselves with time. For all we know somebody might be writing an Emacs mode for lout at this very moment. As far as publishers are concerned; over the years I have heard bitter complaints from fellow mathematicians that so-and-so publisher won't accept TeX document with such-and-such macro packages. The situation changes as the package gets more popular and proves its usefulness.