Lout 3.36.

git-svn-id: http://svn.savannah.nongnu.org/svn/lout/trunk@41 9365b830-b601-4143-9ba8-b4a8e2c3339c

9 files changed, 247 insertions, 30 deletions

diff --git a/doc/user/README b/doc/user/README
index 5306c33..9b8df78 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -21,11 +21,11 @@ error message output on the last run for A4 size printing:
 
 lout:
         : lout -r beginning run 6:
-lout file "str_indx" (from "str" line 16, from "all" line 38):
-    54,1: 0.3c object too high for 0.1c space; will try elsewhere
-lout file "gra_summ" (from "gra" line 44, from "all" line 46):
+lout file "str_indx" (from "str" line 16, from "all" line 39):
+    53,1: 0.3c object too high for 0.0c space; will try elsewhere
+lout file "gra_summ" (from "gra" line 44, from "all" line 47):
     10,1: 24.1c object too high for 23.6c space; @Scale inserted
-lout file "prg_tabs" (from "prg" line 141, from "all" line 48):
+lout file "prg_tabs" (from "prg" line 141, from "all" line 49):
    66,23: prg2lout 2,1: program text ended within comment
    68,35: prg2lout 2,1: program text ended within comment
 
@@ -41,7 +41,7 @@ repeated failure to converge, caused by footnotes and floating figures
 close to large unbreakable displays.
 
 A copy of the final PostScript output file (A4 paper size) is
-stored at "ftp://ftp.it.usyd.edu.au/jeff/lout/lout-3.35.user.ps.gz".
+stored at "ftp://ftp.it.usyd.edu.au/jeff/lout/lout-3.36.user.ps.gz".
 
 Jeffrey H. Kingston
-13 April 2007
+27 July 2007
diff --git a/doc/user/all b/doc/user/all
index 17726bd..7c75312 100644
--- a/doc/user/all
+++ b/doc/user/all
@@ -2,6 +2,7 @@
 @SysInclude { tab }
 @SysInclude { tbl }
 @SysInclude { eq }
+@SysInclude { math }
 @SysInclude { graph }
 @SysInclude { pie }
 @SysInclude { pas }
@@ -22,8 +23,8 @@ Lout
 Document Formatting System
 }
     @Author { Jeffrey H. Kingston }
-    @Edition { Version 3.35
-April, 2007 }
+    @Edition { Version 3.36
+July, 2007 }
     @Publisher {
 Copyright @CopyRight 1991, 2007 Jeffrey H. Kingston,
 School of Information Technologies,
diff --git a/doc/user/ap_byp b/doc/user/ap_byp
index 18ee641..002f439 100644
--- a/doc/user/ap_byp
+++ b/doc/user/ap_byp
@@ -5,10 +5,10 @@
 @PP
 The `bypass' symbols described in this appendix are intended to be
 bypass.symbols @Index { bypass symbols }
-used only in Lout which is generated by computer programs.  Their
-purpose is to bypass the Lout cross reference database, and so reduce
-the number of passes needed to finalise a document.  These symbols
-should not be used by people, because that would only lead back to the
+used in Lout which is generated by computer programs.  Their purpose
+is to bypass the Lout cross reference database, and so reduce the
+number of passes needed to finalise a document.  These symbols are not
+intended to be used by people, because that would only lead back to the
 consistency problems that prompted the introduction of cross references
 in the first place.
 @PP
@@ -52,9 +52,10 @@ use the @Code "@BypassNumber" option:
 Give the full `path number' (5.2, B.3 or whatever) of the symbol.  There is
 a @Code "@BypassNumber" option for every symbol that has a @Code "@Title"
 option and is usually assigned a number automatically by Lout, plus
-@Code "@Figure" and {@Code "@Table"}.  No changes to the setup file are
-required in order to use {@Code "@BypassNumber"}, and it is permitted
-for some large-scale structure symbols to have this option and others not.
+{@Code "@Figure"}, {@Code "@Table"}, and (since Version 3.36) the numbered
+display symbols.  No changes to the setup file are required in order to use
+{@Code "@BypassNumber"}, and it is permitted for some large-scale structure
+symbols to have this option and others not.
 @PP
 To produce a bypass reference list, set the @Code "@MakeReferences"
 setup file option to @Code "Bypass" and place reference entries at the
diff --git a/doc/user/bas_hyph b/doc/user/bas_hyph
index 288760c..9e9a2f9 100644
--- a/doc/user/bas_hyph
+++ b/doc/user/bas_hyph
@@ -29,8 +29,8 @@ use the @Code "&-" symbol:
 }
 This both allows hyphenation at the point marked and prevents it
 in the adjacent word fragments.  If @Code "&-" occurs directly after
-a hyphen character, hyphenation will be permitted but no extra hyphen
-will be inserted.
+a hyphen or slash character, hyphenation will be permitted but no extra
+hyphen will be inserted.
 @PP
 To prevent hyphenation of a word, enclose the word in a @Code "@OneCol"
 symbol.  To turn hyphenation off throughout the document, you need to set
diff --git a/doc/user/equ b/doc/user/equ
index 0d0b0ca..6ff73ad 100644
--- a/doc/user/equ
+++ b/doc/user/equ
@@ -26,5 +26,6 @@ you, and it provides several hundred mathematical symbols.
 @Include { equ_defs }
 @Include { equ_summ }
 # @Include { equ_tequ } apparently not offered any more, forget why
+@Include { equ_math }
 @EndSections
 @End @Chapter
diff --git a/doc/user/equ_math b/doc/user/equ_math
new file mode 100644
index 0000000..e9ab835
--- /dev/null
+++ b/doc/user/equ_math
@@ -0,0 +1,212 @@
+# Written by Ludovic Courtès <ludo@gnu.org>, July 2007.
+#
+# Based on:
+# http://lists.planix.com/pipermail/lout-users/2007q2/004355.html .
+
+@Section
+  @Title { The @Code { "@Math" } package }
+  @Tag   { math_package }
+@Begin
+
+equations.math @SubIndex { @Code "@Math" }
+
+@PP
+
+The @Code { "@Math" } package provides features similar to those found
+in @Code { "@Eq" } but with improved formula layout.  For instance, the
+@Code { "@M" } symbol offers better rendering of equations within
+paragraphs than @Code { "@E" }.  To that end, @Code { "@Math" }
+implements the four equation layout styles described by Donald E. Knuth in
+@I { The { @TeX }book } along with the corresponding transition rules
+@Cite { $knuth1984tex }.  Namely, depending on its rendering context,
+a math formula may be in one of the following styles:
+
+@BulletList
+@LI { ``display'' style, for formulas displayed on lines by
+themselves; }
+@LI { ``text'' style, for formulas embedded in text; }
+@LI { ``script'' style, for formulas used in superscripts and
+subscripts; }
+@LI { ``subscript'' style, for second-order superscripts and
+subscripts. }
+@EndList
+
+In addition, formulas can be ``cramped'', meaning that exponents are
+lower than usual.
+
+@PP
+Fortunately, you usually don't need to be familiar with these display
+styles and corresponding layout algorithm to use @Code { "@Math" }.
+The sections below summarize the differences from @Code { "@Eq" } as
+well as the new features.
+
+@BeginSubSections
+
+@SubSection @Title { Differences from @Code { "@Eq" } }
+@Begin
+
+@PP
+First and foremost, the Lout definitions for the @Code "@Math" symbol
+are accessed via a setup file called {@Code "math"}, which you must
+include at the start of your document in the usual way:
+
+@ID @OneRow @Code {
+"@SysInclude { math }"
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"..."
+"@End @Text"
+}
+
+Note that it is possible to include both @Code "eq" and { @Code "math"
+}.  Instead of typing formulas within { @Code "@Eq" } or { @Code "@E" },
+they must be embedded in { @Code "@Math" } or { @Code "@M" },
+respectively.
+@PP
+
+In @Code { "@Math" }, sums, products, integrations and similar large
+operations are laid out according to the current style.  For instance,
+the limits of a sum are laid out differently depending on the context:
+
+@BeginAlignedDisplays
+@CAND {
+  @Math { { sum from { i = 0 } to { n } { i sup 2 } } over { x + y } } }
+@CAND {
+  @Math { sum from { i = 0 } to { n } { i sup 2 } } }
+@EndAlignedDisplays
+
+Similarly, the @Code { "big" } symbol that is used in @Code { "@Eq" } to
+display sums, integrations, etc. is usually not needed: the size of the
+``sigma'' or other symbol automatically adapts to the context.
+@PP
+
+The @Code { "from" } and @Code { "to" } stand-alone symbols found in
+@Code { "@Eq" } are not available.  Instead, symbols such as @Code {
+"sum" } that require them have @Code { "from" } and @Code { "to" }
+options instead.  For example, instead of
+@ID { @Code { "@Eq { sum from i = 0 to n { i sup 2 } }" } }
+it is necessary to write
+@ID { @Code { "@Math { sum from { i = 0 } to { n } { i sup 2 } }" } }
+The braces are necessary now because @Code { "from" } and @Code { "to" }
+are options of @Code { "sum" }, and it is a general rule of Lout that
+the values of options have to be enclosed in braces.
+@PP
+
+Unlike those of @Code { "@Eq" }, mathematical operators obey standard
+precedence rules.  Thus, to get @M { { n + 1 } over 2 }, one must write
+@Code { "@M { { n + 1 } over 2 }" } instead of just
+@Code { "@E { n+1 over 2 }" }.
+
+@PP
+@Code "@Math" generally produces better mathematical layout than
+@Code { "@Eq" }.  Consider the following examples rendered with
+@Code "@Math" (on the left) and with @Code "@Eq" (on the right):
+
+@ID { @Math { 2 sup { 2 sup { 2 sup x } } }
+|8ct
+@Eq { 2 sup { 2 sup { 2 sup x } } } }
+
+//
+@RID { @Math { x supp { z supp d on c } on { y supp a on b } }
+|8ct
+@Eq { x supp { z supp d on c } on { y supp a on b } } }
+
+@ID { @Math { { { n + 1 } over 2 } over x }
+|8ct
+@Eq { { { n + 1 } over 2 } over x } }
+
+//
+@RID {
+@Math { a sub 0 + 1 over {
+        a sub 1 + 1 over {
+          a sub 2 + 1 over {
+            a sub 3 + 1 over {
+              a sub 4 } } } } }
+|8ct
+@Eq { a sub 0 + 1 over {
+        a sub 1 + 1 over {
+          a sub 2 + 1 over {
+            a sub 3 + 1 over {
+              a sub 4 } } } } } }
+
+@End @SubSection
+
+@SubSection @Title { New symbols and options }
+@Begin
+
+@LP
+The @Code { "@Math" } symbol has a few options not found in
+@Code { "@Eq" }.  The @Code "symbolfont" and @Code "basefont" options
+denote, respectively, the font where symbols are searched for and the font
+where other characters are searched for.  These fonts default to Symbol
+and Times, respectively.  Note that @Code "@Math" is currently tailored
+to use these fonts so using other fonts may require manual adaptation of
+equation layout.
+
+@PP
+Besides, @Code "@Math" provides several new symbols.  Symbols @Code
+"atop" and @Code "below" behave similarly to @Code "from" and @Code
+"to" in @Code "@Eq", respectively.  In other words, @Code "atop" prints
+its left parameter on top of its right parameter, while @Code "below"
+does the opposite operation:
+
+@ID { @Code { "@M { { a atop f } + { z below b } }" }
+|8ct
+@M { { a atop f } + { z below b } } }
+
+@ID {
+{ @Code {
+"@Math { sum from { { 1 <= i <= p } atop"
+"                 { 1 <= j <= q } atop"
+"                 { 1 <= k <= r } }"
+"        { a sub { ij } b sub { jk } c sub { ki } } }" }
+|8ct
+@Math { sum from { { 1 <= i <= p } atop
+                 { 1 <= j <= q } atop
+                 { 1 <= k <= r } }
+        { a sub { ij } b sub { jk } c sub { ki } } } } }
+
+@Code "@Math" produces spacing around operators that depends on the type
+of operator (see Section @NumberOf { "equ_spacing" }) and also on the
+current style.  When defining new operators for @Code "@Math", it is
+usually desirable to make sure they use spacing consistent with other
+operators.  To that end, @Code "@Math" provides spacing symbols similar
+to those found in @Code "@Eq", namely @Code { rel }, @Code { bin } and
+@Code { punct }.  However, these symbols differ from their @Code "@Eq"
+counterpart in that they take three parameters:  a left parameter, an
+@Code "op" option, and a right parameter.  For example,
+@ID @Code "@Math { x bin op { ! } y }"
+produces
+@ID @Math { x bin op { ! } y }
+The left and right parameters are laid out around the operator specified
+by the @Code { op } option, including appropriate spacing.
+
+@PP
+
+Finally, @Code "@Math" offers additional symbols that allow users to
+explicitly specify the style under which part of a math formula is to be
+laid out.  These low-level primitives may be useful in specific
+situations such as the one illustrated below:
+
+@ID { @Code {
+"@Math {"
+"  lim atop @SubScriptStyle { i --> infinity }"
+"     f(x) = { g(x) } over { h(x) } }"
+}
+|8ct
+@Math {
+  lim atop @SubScriptStyle { i --> infinity }
+      f(x) = { g(x) } over { h(x) } }
+}
+
+@Code "@SuperScriptStyle" and @Code "@SubScriptStyle" lay out their
+right parameter under the ``script'' or ``subscript'' style,
+respectively.  @Code "@NumeratorStyle" and @Code "@DenominatorStyle" lay
+out their right parameter as if it where the numerator or denominator of
+a fraction, respectively.  Likewise, @Code "@SquareRootStyle" lays out
+its right parameter as if it were below a square root.
+
+@End @SubSection
+
+@EndSubSections
+@End @Section
diff --git a/doc/user/equ_spac b/doc/user/equ_spac
index 47aff3b..c87e9a6 100644
--- a/doc/user/equ_spac
+++ b/doc/user/equ_spac
@@ -1,5 +1,6 @@
 @Section
    @Title { Spacing }
+   @Tag { equ_spacing }
 @Begin
 @PP
 There is a basic rule governing the use of white space characters (space,
diff --git a/doc/user/preface b/doc/user/preface
index 4f9a212..09e54bf 100644
--- a/doc/user/preface
+++ b/doc/user/preface
@@ -18,7 +18,7 @@ gnu. @Index { GNU Public License }
 primary source is directory
 @ID @Code "ftp://ftp.it.usyd.edu.au/jeff/lout"
 containing a gzipped tar file of the current version
-(currently {@Code "lout-3.35.tar.gz"}), and various other things including
+(currently {@Code "lout-3.36.tar.gz"}), and various other things including
 a PostScript version of this guide.  The distribution contains source code,
 libraries, documentation, license, and installation instructions.
 @PP
@@ -52,7 +52,8 @@ E. Knuth's @TeX system @Cite { $knuth1984tex }, and the optimal paragraph
 breaking algorithm was applied to the problem of producing optimal page
 breaks.  The first implementations of horizontal galleys and optimal
 page breaking were by my student Gabor Inokai.  Vincent Tan contributed
-the PDF back end.  Valeriy E. Ushakov smoothed the path for many
+the PDF back end.  Ludovic Court{@Char egrave}s contributed the
+@Code "@Math" package.  Valeriy E. Ushakov smoothed the path for many
 people, by his contributions to improving Lout's robustness, and his
 tireless management of and responses to the Lout mailing list.  The
 current mailing list maintainer is Greg Woods.  The number of other
diff --git a/doc/user/str_indx b/doc/user/str_indx
index a68fc5d..40c7649 100644
--- a/doc/user/str_indx
+++ b/doc/user/str_indx
@@ -21,15 +21,14 @@ Galileo Galilei
     telescope, his use of, 201--203
     trial of, 205--211, @I 242, 395
 }
-Each line shows off one of Lout's four tricks:  the first is a
-@I { raw entry } (no page number attached); the second is a
-@I sub-entry (indented); the third has a @I { page number range }
-instead of a single page number; and the fourth is a @I { merged entry }
-(several page numbers or ranges within one entry) with a
-@I { special element } (the page number in italics).
-@PP
-We'll take each of them in turn in a moment, but first, let's see how
-to get a basic entry, like this one:
+These lines show off Lout's five tricks:  the first is a @I { raw entry }
+(no page number attached); the second is a @I sub-entry (indented); the
+third has a @I { page number range } instead of a single page number; and
+the fourth has a @I { merged entry } (several page numbers or ranges within
+one entry) and a @I { special element } (the page number in italics).
+@PP
+We'll get to them in a moment, but first, let's see how to get a basic
+entry, like this one:
 @ID { Galileo Galilei, 201 }
 To get this into your index, type
 @ID @Code "galileo @Index { Galileo Galilei }"
@@ -106,7 +105,7 @@ result of {@Code "@PageOf"}).  If both ends of the range fall on the
 same page, the @Code "to" option is ignored:  you will never get
 201--201.
 @PP
-Our fourth and final trick is the merged entry:
+Our fourth trick is the merged entry:
 @ID { trial of, 205--211, 242, 395 }
 The main thing to grasp is that this merged entry was originally three
 separate entries (sub-entries in this case):
@@ -255,7 +254,8 @@ Although the page numbers in index entries will be kept up to date
 automatically as the document changes, as all cross references are, 
 it is best to refrain from inserting index entries until the document
 is complete and an overall plan of the structure of the index can
-be made.
+be made.  Place index entries for floating figures and tables within
+their captions.
 @PP
 Large indexes may benefit from {@I spacers} -- empty spaces or
 spacers. @Index { spacers in indexes }