Lout FAQ/HOWTO by Eric Marsden emarsden@mail.dotcom.fr v1.0, October 1997 This document contains information about the Lout text formatting sys­ tem. It includes a collection of questions frequently asked on the Lout mailing list. ______________________________________________________________________ Table of Contents 1. Introduction 2. What is Lout? 2.1 What platforms does Lout run on? 2.2 Where can I get Lout? 2.3 So is Lout like a word processor? 2.4 Why use Lout instead of LaTeX or troff? 3. Lout Packages 3.1 Can I produce HTML from my Lout documents? 3.2 Is there an Emacs mode for Lout? 3.3 Is there an archive of user-contributed document formats? 4. Lout Problems 4.1 Lout produces ugly output in Ghostscript 5. How do I ... ? 5.1 How do I get quotes ( 5.2 How do I use accented characters in Lout? 5.3 How do I print only a selection of pages of a Lout document? 5.4 LaTeXisms 5.5 Whah! I want Lout to do this! Lout shouldn't work this way! 6. Simple Examples 7. Advanced Examples 8. Further information ______________________________________________________________________ 1. Introduction This document contains information about the Lout text formatting system. It includes a collection of questions frequently asked on the Lout mailing list. Please read through this document before posting a question to the Lout mailing list. The latest version of this file is available at http://www.chez.com/emarsden/lout/, in Postscript and ASCII formats. There is also an online version with embedded hyperlinks. This document is Copyright 1997 by Eric Marsden. Feel free to copy or distribute this document in whole or in part for any purpose and on any medium you choose, provided you do not omit this notice. Feedback is welcome; please send remarks, suggestions and corrections to 2. What is Lout? Lout is a high-level language for document formatting. It includes facilities for typesetting complex documents containing floating figures, tables, diagrams, rotated and scaled text or graphics, footnotes, running headers, footers, an index, table of contents and bibliography, cross-references, mathematical equations and statistical graphs. Lout's capabilities can be extended with definitions which are easier to write than similar markup languages. Lout is multilingual, supporting (with hyphenation) Czech, Danish, Dutch, English, Finnish, French, German, Norwegian, Russia, Slovenian, Spanish and Swedish. Some of these languages are available as separate packages because they need more than 13 standard Adobe fonts. Further languages can be added easily. Lout is free software distributed under the GNU Public License. It was designed and implemented by Jeffrey H. Kingston at the University of Sydney. 2.1. What platforms does Lout run on? The Basser Lout (the lout compiler written by Jeffrey Kingston) is written in ANSI C. It runs best on a real operating system like Un*x, but has been ported to · MS-DOS : see the next section "Where can I get Lout?" · MS-Windows NT · OS/2 · BeOS · QNX (thanks to Chris Herborth ) · MacOS users have several choices. Lout is reported to compile under the MPW shell, which is distributed with several C compilers. You may want to consider a Un*x such as MkLinux (a free, high-powered Un*x for PowerPC Macintoshes), or MacMiNT (a freeware Un*x lookalike which runs as an ordinary Macintosh application concurrently with others), or MachTen (similar but commercial). A standalone port is underway by Robert Marsa . Several of these ports have problems reading Lout .li database files. Lout produces Postscript, a page description language understood by most laser printers. Postscript can also be printed on pretty much any printer (and previewed on the screen) by using the Ghostscript interpreter, which is distributed under the GNU Public License. See the Postscript FAQ (available by anonymous ftp at wilma.cs.brown.edu:pub/comp.lang.postscript/FAQ.txt) for more details. Lout can also produce plain text output, though any graphics details will be lost. 2.2. Where can I get Lout? The primary site for Lout is Jeffrey Kingston's ftp site, at ftp.cs.su.oz.au:/jeff. This site is in Australia; most users will be better off using one of the following mirror sites : · CTAN mirrors such as http://www.text.ac.uk/tex- archive/support/lout/lout (say thank you to the TeX people for supporting this) ; · A mirror of Jeff's site in Sweden at ftp.sunet.se:/pub/text- processing/lout/lout ; · Another mirror is sunsite.aux.dk:/pub/text/lout ; · sunsite.unc.edu:/pub/Linux/apps/wp/lout ; · In France at ftp.inria.fr:/textproc (this isn't a mirror) ; · For users of Debian GNU/Linux, there is a prepackaged binary distribution available in the text section on Debian mirrors all over the world ; · Users of Red Hat Linux will find Lout packaged as an .rpm on Red Hat CDs or ftp mirrors ; · A binary of lout 3.09 compiled for MS-DOS by Bunno Lim is available from ftp.ptc.spbu.ru:/pub/unix/text/lout/msdos/. This site is in Russia with a slow Internet connection, so please download overnight local time (the ftp server prints local time in its banner) ; · Archives of the Usenet group comp.sources.misc. All distributions should include (either in the main package or separately) complete documentation : the Users' Guide with a Quick Reference, and the Expert's Guide. To build from a source distribution you will need an ANSI C compiler (such as gcc). 2.3. So is Lout like a word processor? Lout is not a word processor like WordPerfect or MS-Word. These programs are WYSIWYG (what you see is what you get); the text displayed on your computer's screen is an approximation to what will appear on the printed page. Lout, in contrast, is a markup language. This means that if you want bold or italic text, you write (with your favorite text editor) if you want @B{bold} or @I{italic} text, Other symbols are used to identify headings, paragraphs, footnotes and so on. The lout interpreter reads these commands and produces nicely formatted output. The comp.text FAQ contains a more complete discussion of the relative merits of markup and WYSIWYG ; for starters you may wish to ask yourself how many different (and incompatible) .doc formats Microsoft has unleashed upon the unsuspecting users of successive releases of MS-Word. 2.4. Why use Lout instead of LaTeX or troff? Lout is similar in function to LaTeX and troff. Indeed, it borrows ideas, techniques and conventions from these typesetting systems. For example, Lout uses Knuth's (the author of TeX, on which LaTeX is based) optimal line breaking algorithm, and has extended it to paragraph breaking across pages. For simple documents, Lout, LaTeX and troff offer much the same functionality, with different syntax (see the "Simple Examples" section). Lout is much more "programmer friendly" than TeX's macros (and ŕ fortiori than incomprehensible troff macros). See the "Advanced Examples" section. Lout makes it easy to mix text and graphics. You can draw lines, arrows and boxes, scale and rotate objects, use color commands. While many of these things are possible in LaTeX by including Postscript files generated by utility programs such as xfig, you have to specify the size of each included figure, losing a lot of Lout's flexibility. The Lout distribution is very easy to compile and maintain, which certainly is not the case of many TeX distributions. The Lout distribution is much smaller (it fits onto a floppy disk) than LaTeX, and doesn't require storing tfm and pk font outlines (since Postscript fonts are used). Lout Postscript files are more compact than those produced from the process .tex -TeX-> .dvi -dvips-> .ps. Lout is multi-lingual out of the box, and understands ISO-8859 latin-1 characters. On the other hand, TeX/LaTeX is much more widely used than Lout (TeX has been around since 1969, Lout only since 1991). It will be easier to find a local TeXpert than a Louter, and there are many more user- contributed packages for LaTeX than for Lout. Many academic journals request (or require) that papers be submitted in LaTeX. Lout uses more memory than TeX, up to 10 Mb to compile large documents. Lout is more friendly to advanced users. LaTeX style sheets are written in a twisted, diabolical manner apparently designed to make all but trivial changes to a document's appearance difficult ; it's internals are packaged as a "black box" which ordinary mortals aren't meant to understand. Lout styles are much easier to design and modify according to your needs. The Lout formatting language is conceptually cleaner and higher level than TeX (which was designed to run efficiently on computers from an other era). For example, Lout has no built-in notion of a "page". 3. Lout Packages 3.1. Can I produce HTML from my Lout documents? The short answer is no, not easily. The problem is that Lout is quite different from HTML. Lout is a powerful language which allows you to place text or graphics at a specific point on the page, and the ease with which this is possible is one of its nicest features. HTML is (purposefully) very poor in this respect. This being said, in the same way that Lout can be told to produce plain text output rather than Postscript, it could also produce HTML. As Jeff Kingston has pointed out, this would require writing another backend which produces HTML equivalents for all the Lout formatting tags, ignoring those it can't render correctly. Another way of proceeding would be to use a postprocessor (a Perl script, for example) to carry out the conversions, stripping out unconvertible information. This is the way latex2html works. You may want to consider using another package if you need to export to many different formats. Other packages you might use include · SGML-Tools is an SGML DTD (Document Type Definition) and a set of tools which convert the SGML to HTML, Postscript (via Lout), GNU info, ASCII and RTF (see http://pobox.com/~cg/sgmltools) ; · Texinfo lets you produce info files (the GNU hypertext format), Postscript (via TeX) and HTML. 3.2. Is there an Emacs mode for Lout? Thanks to Valeriy Ushakov : ______________________________________________________________________ ;; Oversimplified lout mode. Suggestions are welcome. ;; I use FSF v19.29, may be this works for XEmacs ;; Imagine standard GNU boilerplate here. :-) (require 'derived) (define-derived-mode lout-mode text-mode "Lout" "Major mode to edit Lout documents (*not* definitions!!!)" ;; Customize syntax table (modify-syntax-entry ?@ "w" lout-mode-syntax-table) (modify-syntax-entry ?\" "\"" lout-mode-syntax-table) (modify-syntax-entry ?\\ "\\" lout-mode-syntax-table) (modify-syntax-entry ?\# "<" lout-mode-syntax-table) (modify-syntax-entry ?\n ">" lout-mode-syntax-table) ;; Comment syntax (make-local-variable 'comment-start) (setq comment-start "#") (make-local-variable 'comment-end) (setq comment-end "") (make-local-variable 'comment-start-skip) (setq comment-start-skip "#+ *") ;; Customize paragraphs. Any ideas how to do this better. I don't ;; want to mention all @PP ... etc symbols explicitly (make-local-variable 'paragraph-start) (setq paragraph-start "[\n@}]") (make-local-variable 'paragraph-separate) (setq paragraph-separate "[@}]")) ;; Hilit19 (if (not (featurep 'hilit19)) () (hilit-set-mode-patterns 'lout-mode '(("#[^][+]" "$" comment) (hilit-string-find ?\" string) ("@\\w*" nil keyword) ("@\\(Sys\\)?Include\\>" nil include)))) ______________________________________________________________________ 3.3. Is there an archive of user-contributed document formats? There isn't, but it would be great for there to be one. Any volunteers? 4. Lout Problems 4.1. Lout produces ugly output in Ghostscript > When I view the output from lout using Ghostview, a well known > front end to Ghostscript, the spacing is all screwed up. Words > appear run together as though they were a single word, yet printing > on a laser, postscript printer always produces beautiful results. The problem comes from poor font descriptions included with older versions of Ghostscript, or from an incompatibility with them. If the font formats used by Lout for calculating word and letter spacing don't match those used by the Ghostscript interpreter, obviously you lose. Recent versions of Ghostscript use higher quality fonts and support antialiasing : it's well worth upgrading. 5. How do I ... ? 5.1. How do I get quotes ( " ) or backslashes ( ) in Lout? Rodrigo Vanegas (former maintainer of the Lout mailing list) writes Quotes are explained in the reference manual, section 2.1. To get this You type this " \" \ \\ but these things only work inside "...". So the way to print quoted strings in source code listings is like this (for example) : puts("hello\n"); puts("\"hello\\n\""); In other words, you replace the opening " by "\", you replace the closing quote by \"", and any \ inside you replace by \\. 5.2. How do I use accented characters in Lout? The best way is to compile Lout in 8-bit mode and to use an editor which allows the insertion of accents. In GNU Emacs, for example, you can use iso-accents-mode. If this isn't possible you can use a simple script to transform "prefixed-accents" to Lout @Char form. For French accents, for example : ______________________________________________________________________ #!/usr/local/bin/perl while( <> ) { s/'e/\@Char{eacute}/g; s/`e/\@Char{egrave}/g; s/`a/\@Char{agrave}/g; s/`u/\@Char{ugrave}/g; s/\^e/\@Char{ecircumflex}/g; s/\^o/\@Char{ocircumflex}/g; s/\^u/\@Char{ucircumflex}/g; # etc print; } ______________________________________________________________________ 5.3. How do I print only a selection of pages of a Lout document? This sort of task is best left to a Postscript postprocessor. Lout outputs Postscript which conforms closely to the Adobe Document Structuring Conventions (see the file notes.dsc included with the Lout distribution). This means, among other things, that it includes page numbering information in its output, which is why Postscript previewers permit you to skip to an arbitrary page in the document, and which makes it possible to select specific pages from Lout's output. PS Utils by Angus Duggan is a great postprocessor for Postscript documents. Some of the programs in the suite are psresize alter document paper size psselect selects pages and page ranges psbook rearranges pages into signatures psnup put multiple pages per physical sheet of paper pstops performs general page rearrangement and selection 5.4. LaTeXisms A person coming to Lout from LaTeX will notice several differences between the systems. With its default settings, Lout takes into account all inter-word white space (as does troff). You can ask Lout to use the LaTeX conventions (multiple spaces are treated as a single space) with the @InitialSpace option (see the User's Guide section 1.18). LaTeX lets you signal non-breaking spaces (as in Dr. Watson, where you don't want a line break between Dr. and Watson) with a ~ (tilde). The same effect can be obtained in Lout with the following definition (predefined in recent versions of Lout) : def "~" left x right y { @OneRow { x &1s y } } LaTeX considers that an empty line signals the start of a new paragraph, whereas Lout waits for an explicit @PP (indented paragraph) or @LP (non-indented paragraph) symbol. You can simulate TeX glue with the following definitions def @VFill { @VExpand {} } def @HFill { @HExpand {} } 5.5. Whah! I want Lout to do this! Lout shouldn't work this way! Unlike TeX (which Don Knuth has frozen for eternity now that he considers that most bugs have been detected), Lout is evolving. For example, the treatment of whitespace was changed in 1995 (two options were added at users' request). If you have a suggestion for improvement, gripe loutly and Jeff will hear you (to quote Uwe :-). 6. Simple Examples To be completed ... 7. Advanced Examples To be completed ... 8. Further information Valeriy Ushakov maintains a home page for Lout at http://www.ptc.spbu.ru/~uwe/lout/. He also runs a public mailing list for discussion of Lout. To subscribe to the list, send mail to lout-request@ptc.spbu.ru containing the word subscribe in the subject line. To unsubscribe, send mail to lout-request@ptc.spbu.ru containing the word unsubscribe in the subject line (not in the body). To post an item, send mail to lout@ptc.spbu.ru. It will be forwarded by email to all current subscribers. You can view recent messages on the list on the Web at http://www.ptc.spbu.ru/~uwe/lout/list.html. End of the Lout FAQ/HOWTO.