Lout 3.30.

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

12 files changed, 157 insertions, 29 deletions

diff --git a/doc/user/README b/doc/user/README
index f023e85..715d867 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -17,8 +17,8 @@ nearly all beginning with "unresolved cross reference".  These
 should gradually go away on later runs.  The following shows the
 error message output on the later runs for A4 size printing:
 
-lout file "str_glos" (from "str" line 15, from "all" line 38):
-     8,1: 1.0c object too high for 0.4c space; will try elsewhere
+lout file "str_foot" (from "str" line 8, from "all" line 38):
+   11,13: 1.0c object too high for 0.6c space; will try elsewhere
 lout file "str_indx" (from "str" line 16, from "all" line 38):
     54,1: 0.3c object too high for 0.2c space; will try elsewhere
 lout file "dia_synt" (from "dia" line 50, from "all" line 45):
@@ -42,7 +42,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.cs.su.oz.au/jeff/lout/lout-3.29.user.ps.gz".
+stored at "ftp://ftp.it.su.edu.au/jeff/lout/lout-3.30.user.ps.gz".
 
 Jeffrey H. Kingston
-14 August 2003
+27 October 2004
diff --git a/doc/user/all b/doc/user/all
index 343e7fe..937eb4d 100644
--- a/doc/user/all
+++ b/doc/user/all
@@ -22,10 +22,10 @@ Lout
 Document Formatting System
 }
     @Author { Jeffrey H. Kingston }
-    @Edition { Version 3.29
-August, 2003 }
+    @Edition { Version 3.30
+October, 2004 }
     @Publisher {
-Copyright @CopyRight 1991, 2003 Jeffrey H. Kingston,
+Copyright @CopyRight 1991, 2004 Jeffrey H. Kingston,
 School of Information Technologies,
 The University of Sydney 2006, Australia.  ISBN 0 86758 951 5.
 }
diff --git a/doc/user/bas_font b/doc/user/bas_font
index 1241966..dd8442d 100644
--- a/doc/user/bas_font
+++ b/doc/user/bas_font
@@ -662,5 +662,10 @@ kerning. @Index { kerning }
 letters closer together, for example in `VA.'  Lout considers
 ligatures and kerning to be integral parts of each font; you can prevent
 them from happening only by enclosing one of the letters in a
-@Code "@OneCol" symbol, as in {@Code "@OneCol { V }A" }.
+@Code "@OneCol" symbol, as in {@Code "@OneCol { V }A" }.  Alternatively,
+to turn off ligatures you can write
+@ID @Code "nolig @Font { ... }"
+and then ligatures will not be used within the object following
+{@Code "@Font"}.  Should you ever need to turn ligatures on
+within a region where they are turned off, use {@Code "lig @Font"}.
 @End @Section
diff --git a/doc/user/bgr b/doc/user/bgr
index c0dedbf..9855287 100644
--- a/doc/user/bgr
+++ b/doc/user/bgr
@@ -16,6 +16,7 @@ get them beyond the usual @Code "@SysInclude { doc }" or whatever.
 @Include { bgr_outl }
 @Include { bgr_rota }
 @Include { bgr_scal }
+@Include { bgr_mirr }
 @Include { bgr_incl }
 @EndSections
 @End @Chapter
diff --git a/doc/user/bgr_mirr b/doc/user/bgr_mirr
new file mode 100644
index 0000000..6474ba6
--- /dev/null
+++ b/doc/user/bgr_mirr
@@ -0,0 +1,38 @@
+@Section
+   @Title { Mirror reflections }
+   @Tag { mirroring }
+@Begin
+@PP
+The @Code "@HMirror" symbol produces a horizontal mirror reflection
+reflect. @Index { Reflected objects }
+mirror. @Index { Mirror images }
+hmirror. @Index @Code "@HMirror"
+of the following object:
+@ID @Code {
+"@HMirror AMBULANCE"
+}
+produces
+@ID @HMirror AMBULANCE
+The @Code "@VMirror" symbol produces a vertical mirror reflection
+vmirror. @Index @Code "@VMirror"
+of the following object:
+@ID @Code {
+"@VMirror 5c @Wide @Box {"
+"@B { Pond life. }  Pond life includes"
+"frogs, tadpoles, newts, salamanders,"
+"eels, and mosquito larvae."
+"}"
+}
+produces
+@ID @VMirror 5c @Wide @Box {
+@B { Pond life. }  Pond life includes
+frogs, tadpoles, newts, salamanders,
+eels, and mosquito larvae.
+}
+As this example shows, the object to be mirror reflected may be
+arbitrary.  We have used a @Code "@Wide" symbol in this example
+to restrict the width of the result to be five centimetres wide.
+See the description of the @Code "@VShift" symbol in
+Section {@NumberOf include} for what to do if your reflected
+object is not aligned properly with adjacent objects.
+@End @Section
diff --git a/doc/user/fmt_size b/doc/user/fmt_size
index 04ebb5e..7fd138e 100644
--- a/doc/user/fmt_size
+++ b/doc/user/fmt_size
@@ -27,6 +27,7 @@ option to the name of the paper you use:
 @Rowa A { Legal  }	B {  612p }  C { 1008p }
 @Rowa A { Statement }	B {  396p }  C {  612p }
 @Rowa A { Executive }	B {  540p }  C {  720p }
+@Rowa A { A2 }		B { 1190p }  C { 1884p }
 @Rowa A { A3 }		B {  842p }  C { 1190p }
 @Rowa A { A4 }		B {  595p }  C {  842p }
 @Rowa A { A5 }		B {  420p }  C {  595p }
diff --git a/doc/user/gra_over b/doc/user/gra_over
index 5bffe08..b459da8 100644
--- a/doc/user/gra_over
+++ b/doc/user/gra_over
@@ -17,9 +17,11 @@ axes. @Index { axes in graphs }
 graph, whose value may be either {@Code "frame"}, {@Code "none"},
 or {@Code "axes"}.  The default value is {@Code "frame"}, and it produces
 a frame around the graph with ticks and labels along its left and bottom
-edges, as in previous examples.  The {@Code "none"} style prints
-nothing (no frame, no ticks, no labels), which is useful for producing
-graphs that don't look like graphs, as it were.
+edges, as in previous examples.  Value @Code "grid" is similar except
+that the ticks are converted into grid lines crossing the entire
+frame.  The {@Code "none"} style prints nothing (no frame, no ticks,
+no labels), which is useful for producing graphs that don't look like
+graphs, as it were.
 @PP
 If the other value, {@Code "axes"}, is chosen, two other options called
 {@Code xorigin} and {@Code yorigin} become compulsory:
diff --git a/doc/user/preface b/doc/user/preface
index 9e4ba4e..e9c9bab 100644
--- a/doc/user/preface
+++ b/doc/user/preface
@@ -18,17 +18,16 @@ 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.29.tar.gz"}), and various other things including
+(currently {@Code "lout-3.30.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
 A mailing list has been set up for discussion of all topics related to
-Lout.  To subscribe, send email to @Code "lout-request@ptc.spbu.ru"
-containing the word @Code "subscribe" in the Subject line.  To post an
-item, send email to {@Code "lout@ptc.spbu.ru"}; it will be forwarded to
-all subscribers via email.  To unsubscribe, send email to
-@Code "lout-request@ptc.spbu.ru" containing the word @Code "unsubscribe"
-in the Subject line.
+Lout.  To subscribe (or unsubscribe), visit
+@ID @Code "http://lists.planix.com/mailman/options.cgi/lout-users/"
+After subscribing, to post an item send email to
+{@Code "lout-users@lists.planix.com"}; it will be forwarded to all
+subscribers via email.
 @PP
 Lout began in 1984 as a research project into the design of a high-level
 language for document formatting.  At that time my name for the subject
@@ -56,8 +55,9 @@ page breaking were by my student Gabor Inokai.  Vincent Tan contributed
 the PDF back end.  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
-number of other people who have offered comments and suggestions to me is so
-great that it is quite out of my power to acknowledge them individually.  I
+current mailing list maintainer is Greg Woods.  The number of other
+people who have offered comments and suggestions to me is so great
+that it is quite out of my power to acknowledge them individually.  I
 hope that seeing their ideas adopted will be thanks enough.
 @DP
 @RLD lines @Break {
diff --git a/doc/user/ref_sett b/doc/user/ref_sett
index fe6b99d..da8e8fe 100644
--- a/doc/user/ref_sett
+++ b/doc/user/ref_sett
@@ -65,6 +65,13 @@ won't want it in the same directory as any one of them.  A Unix
 pathname will be more appropriate:
 @ID @Code "@Database @Reference { \"/usr/jeff/lib/refs\" }"
 or whatever.  Quotes are needed because of the @Code "/" characters.
+A separate directory is probably safest anyway, since Lout creates
+files ending in @Code ".ld" in the document directory when sorting out
+cross references (Section {@NumberOf cross}), and clearing these out
+using the Unix command
+@ID @Code "rm lout.li *.ld"
+will destroy your valuable database file if it is kept in the same
+directory.
 @PP
 With the database file created and the @Code "@Database" line in place,
 you are ready to start citing references.  The first time that the
diff --git a/doc/user/str_indx b/doc/user/str_indx
index e836588..a68fc5d 100644
--- a/doc/user/str_indx
+++ b/doc/user/str_indx
@@ -329,6 +329,7 @@ their default values:
 @IndexTypeOrdinary { @PageNum }
 @IndexTypeMain { @B @PageNum }
 @IndexTypeSpecial { @I @PageNum }
+@IndexRangeFormat { @From--@To }
 @IndexColumnNumber { 2 }
 @IndexColumnGap { 1.00c }
 @IndexCtd { Yes }
@@ -387,6 +388,15 @@ If the value of a @Code pnformat option is not {@Code Ordinary},
 itself is printed; it too may contain a @Code "@PageNum" symbol,
 as explained earlier.
 @PP
+{@Code "@IndexRangeFormat"} gives the format to use when a page
+number range, such as 5--8, is to be included in an index entry.
+Within it the symbols @Code "@From" and @Code "To" stand for
+the first and last page numbers respectively.  These will always
+be different when {@Code "@IndexRangeFormat"} is used; Lout knows
+never to insert a range when the two end points are equal.  The
+default value just separates the two numbers by an en-dash with
+no space.
+@PP
 @Code "@IndexColumnNumber" and @Code "@IndexColumnGap" determine the
 indexcolumnnumber. @Index @Code "@IndexColumnNumber"
 indexcolumngap. @Index @Code "@IndexColumnGap"
diff --git a/doc/user/str_list b/doc/user/str_list
index e87a637..7888554 100644
--- a/doc/user/str_list
+++ b/doc/user/str_list
@@ -68,7 +68,8 @@ has result
 swathe of destruction through the State of Georgia? }
 @RawEndList
 }
-The generated labels are added at the left margin.  Here is the full set
+The generated labels are added at the left margin.
+Here is the full set
 of label-generating list symbols, showing the first label produced by each:
 parennumberedlist. @Index @Code "@ParenNumberedList"
 pnl. @Index @Code "@PNL"
@@ -261,6 +262,53 @@ Although @Code "@ListInterruptItem" is written like a list item, the
 result appears to be an interruption to the list.  It may be used
 in any kind of list.
 @PP
+Yet another kind of list item symbol is
+paragraph.item. @Index @Code "@ParagraphItem"
+pi. @Index @Code "@PI"
+{@Code "@ParagraphItem"}, which introduces a list item
+whose labels are integrated into a paragraph:
+@ID @OneRow @Code @Verbatim {
+@Heading { Extract from GNU General Public License }
+@LeftList
+@ParagraphItem {
+You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty ...
+}
+@ParagraphItem {
+You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you ...
+}
+@EndList
+}
+has result
+@ID @OneRow {
+@Heading { Extract from GNU General Public License }
+@LeftList
+@ParagraphItem {
+You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty ...
+}
+@ParagraphItem {
+You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you ...
+}
+@RawEndList
+}
+Since the numbers are part of the item, the kind of list to use
+is just {@Code "@LeftList"} rather than {@Code "@NumberedList"}.
+It would be better if @Code "@ListItem" could be used, but problems
+behind the scenes prevent this.  @Code "@ParagraphItem" has a
+@Code "style" option that works much like the @Code "style" option
+of {@Code "@List"} described just below.
+@PP
 Every symbol introduced in this section has an abbreviated form
 consisting of @Code "@" followed by its capital letters only.  For
 example, @Code "@RawNumberedList" abbreviates to {@Code "@RNL"},
diff --git a/doc/user/typ_book b/doc/user/typ_book
index dec1e20..1e9c081 100644
--- a/doc/user/typ_book
+++ b/doc/user/typ_book
@@ -150,10 +150,19 @@ preface. @Index @Code "@Preface"
 "@End @Preface"
 }
 Since the title of most prefaces is simply Preface, that is the default
-value in English of the @Code "@Title" option.  After the preface there
-will automatically appear a table of contents listing the introduction,
-chapters, sections, subsections, appendices, sub-appendices, bibliography,
-and index as appropriate.
+value in English of the @Code "@Title" option.  Within the preface,
+just before {@Code "@End @Preface"}, there may optionally be a sequence
+of sub-prefaces enclosed in @Code "@BeginSubPrefaces" and
+{@Code "@EndSubPrefaces"}, like this:
+@ID @OneRow @Code @Verbatim {
+@BeginSubPrefaces
+@SubPreface ... @End @SubPreface
+@SubPreface ... @End @SubPreface
+@EndSubPrefaces
+}
+After the preface there will automatically appear a table of contents
+listing the introduction, chapters, sections, subsections, appendices,
+sub-appendices, bibliography, and index as appropriate.
 @PP
 The pages up to this point will be numbered in lower case Roman
 numerals; subsequent pages will be numbered in Arabic starting from
@@ -164,9 +173,9 @@ a setup file option for changing this to a single numbering sequence
 Next comes an optional abbreviations sections, exactly like the
 preface except that its name is @Code "@Abbreviations" and the
 abbreviations. @Index @Code "@Abbreviations"
-default title in English is Abbreviation.  There is no support for
-what goes inside; you need to use a list or table to lay out the
-abbreviations, in the usual way.
+default title in English is Abbreviation.  There are no
+sub-abbreviations, and no support for what goes inside; you need to
+use a list or table to lay out the abbreviations, in the usual way.
 @PP
 Next comes an optional introduction, exactly like the preface except that
 its name is @Code "@Introduction" and the default title in English is
@@ -179,7 +188,14 @@ Introduction:
 "..."
 "@End @Introduction"
 }
-After that comes a sequence of chapters in the usual style:
+It may have sub-introductions, exactly like sub-prefaces:
+@ID @OneRow @Code @Verbatim {
+@BeginSubIntroductions
+@SubIntroduction ... @End @SubIntroduction
+@SubIntroduction ... @End @SubIntroduction
+@EndSubIntroductions
+}
+After the introduction comes a sequence of chapters in the usual style:
 chapter. @Index @Code "@Chapter"
 @ID @OneRow @Code {
 "@Chapter"