Lout 3.34.

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

10 files changed, 154 insertions, 46 deletions

diff --git a/doc/user/README b/doc/user/README
index 85e8743..932e3b2 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -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.33.user.ps.gz".
+stored at "ftp://ftp.it.usyd.edu.au/jeff/lout/lout-3.34.user.ps.gz".
 
 Jeffrey H. Kingston
-14 November 2006
+8 March 2007
diff --git a/doc/user/all b/doc/user/all
index e130067..a018cd0 100644
--- a/doc/user/all
+++ b/doc/user/all
@@ -22,10 +22,10 @@ Lout
 Document Formatting System
 }
     @Author { Jeffrey H. Kingston }
-    @Edition { Version 3.33
-November, 2006 }
+    @Edition { Version 3.34
+March, 2007 }
     @Publisher {
-Copyright @CopyRight 1991, 2006 Jeffrey H. Kingston,
+Copyright @CopyRight 1991, 2007 Jeffrey H. Kingston,
 School of Information Technologies,
 The University of Sydney 2006, Australia.  ISBN 0 86758 951 5.
 }
diff --git a/doc/user/bas_hyph b/doc/user/bas_hyph
index 6997f41..288760c 100644
--- a/doc/user/bas_hyph
+++ b/doc/user/bas_hyph
@@ -27,11 +27,13 @@ use the @Code "&-" symbol:
 @IndentedDisplay @Code {
 "after&-math"
 }
-If @Code "&-" occurs directly after a hyphen character, hyphenation
-will be permitted but no extra hyphen will be inserted.  To prevent
-hyphenation of a word, enclose the word in a @Code "@OneCol" 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.
 @PP
-To turn hyphenation off throughout the document, you need to set the
-@Code "@InitialBreak" option to {@Code "nohyphen"}, as described at the
-end of Section {@NumberOf linespace}.
+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
+the @Code "@InitialBreak" option to {@Code "nohyphen"}, as described at
+the end of Section {@NumberOf linespace}.
 @End @Section
diff --git a/doc/user/bas_par2 b/doc/user/bas_par2
index 2de99e9..f57a0ef 100644
--- a/doc/user/bas_par2
+++ b/doc/user/bas_par2
@@ -10,7 +10,7 @@ width.  Lout works out suitable column widths and performs paragraph
 breaking automatically, finding an `optimal' break with the method
 used by the @TeX
 tex.paragraph @SubIndex { paragraph breaking }
-system.  It offers nine styles of paragraph breaking,
+system.  It offers ten styles of paragraph breaking,
 which we will explore with the aid of this example:
 @ID @OneRow @Code {
 It is a truth universally
@@ -25,7 +25,7 @@ breakzzz.sym @Index { @Code "@Break" symbol }
 This example causes every paragraph in the following object to be
 broken using the @Code ragged style, of which more below.
 @PP
-The first two of the nine styles perform @I { line adjustment }, which
+The first two of the ten styles perform @I { line adjustment }, which
 line.adjustment @Index { line adjustment }
 means that they enlarge the spaces between the objects making up each
 line so as to fill the lines completely:
@@ -129,10 +129,11 @@ recommended way is to separate them by an @Code "~" symbol:
 It's best not to bother about this until you actually get a bad line
 break, since chances are good that the words will fall on one line anyway.
 @PP
-The last three styles differ from the first five in breaking the
+The last four styles differ from the first six in breaking the
 paragraph at the points where it is broken in the original input:
 lines. @Index { @Code lines paragraph breaking style }
 clines. @Index { @Code clines paragraph breaking style }
+olines. @Index { @Code olines paragraph breaking style }
 rlines. @Index { @Code rlines paragraph breaking style }
 @IndentedList
 @LI @Tab
@@ -171,9 +172,21 @@ in possession of a good fortune,
 must be in want of a wife.
 }}
 }
+@LI @Tab
+    @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B }
+{
+@Rowa
+    A { "olines @Break ..." }
+    B { olines @Break {
+It is a truth universally
+acknowledged, that a single man
+in possession of a good fortune,
+must be in want of a wife.
+}}
+}
 @EndList
-The lines are left-justified, centred, or right-justified with respect
-to each other in the same way as for the ragged styles.
+The lines are left-justified, centred, right-justified, or outdented
+with respect to each other in the same way as for the ragged styles.
 @PP
 When using the @Code lines style, there are some fine points concerning
 the proper use of white space.  Consider this example:
@@ -233,9 +246,9 @@ Serves to'advance an honest minde.
 }
 as desired.
 @PP
-When using {@Code lines}, {@Code clines}, and {@Code "rlines @Break"},
-blank lines are respected and ordinarily appear at their full height.
-However, it often looks better to give somewhat
+When using {@Code lines}, {@Code clines}, {@Code rlines}, and
+{@Code "olines @Break"}, blank lines are respected and ordinarily appear
+at their full height.  However, it often looks better to give somewhat
 blanklinescale. @Index { @Code blanklinescale }
 less than this to blank lines.  For this there is the {@Code blanklinescale}
 option to {@Code "@Break"}:
diff --git a/doc/user/bas_verb b/doc/user/bas_verb
index d7f2904..6165878 100644
--- a/doc/user/bas_verb
+++ b/doc/user/bas_verb
@@ -1,12 +1,15 @@
 @Section
-   @Title { Verbatim text }
+   @Title { Verbatim and piped text }
    @Tag { verbatim }
 @Begin
 @PP
 The @Code "@Verbatim" symbol
-@FootNote { Prior to Version 3.13 the @Code "@Verbatim" symbol was
-implemented in a way that restricted its availability to Unix
-systems only.  This restriction no longer applies. }
+@FootNote {
+Prior to Version 3.13 the @Code "@Verbatim" symbol was restricted to Unix
+systems only.  This restriction no longer applies to @Code "@Verbatim" and
+{@Code "@RawVerbatim"}, but it does apply to {@Code "@Pipe"},
+{@Code "@PipeVerbatim"}, and {@Code "@PipeRawVerbatim"}.
+}
 prints the following object exactly as
 verbatim.sym @Index @Code "@Verbatim"
 it appears in the input file.  All special meanings for characters,
@@ -47,4 +50,55 @@ all white spaces preceding the closing brace.  However, the alternative
 raw.verbatim.sym @Index @Code "@RawVerbatim"
 as soon as a newline character is reached; in other words, it will
 preserve all white spaces following the first newline.
+@PP
+The @Code "@Pipe" symbol (available on Unix-style systems only) may be
+pipe.sym @Index @Code "@Pipe"
+used to pipe some text through a Unix command.  For example,
+@ID @Code lines @Break @Verbatim {
+@ID lines @Break "sort" @Pipe {
+Gaskell, Elizabeth
+Lawrence, D. H.
+Austen, Jane
+Dickens, Charles
+}
+}
+will cause the object between braces following @Code "@Pipe" to be
+piped without interpretation through the Unix @Code "sort" command; its
+output is the result of the @Code "@Pipe" command, here made into a
+display preserving the line breaks in the output.  The final result will
+be the four authors, one per line, in alphabetical order.  We can't show
+this result to you because that would make this manual not compilable on
+non-Unix systems.
+@PP
+The double quotes around @Code sort are not necessary in this example,
+but may be in more complex ones.  For example, one can see just the
+first few lines of the sorted result using
+@ID @Code @Verbatim { "sort | head" @Pipe ... }
+and here the quotes are necessary because @Code "|" is one of the special
+characters that need quoting, according to Section {@NumberOf characters}.
+The quotes also serve to group the command into a single Lout object.
+@PP
+Some Unix commands don't need any input, and then the object following
+@Code "@Pipe" may be empty.  For example,
+@ID @Code @Verbatim { "ls" @Pipe {} }
+will list the files of the current directory.
+@PP
+Any Lout symbols in the result of the @Code "@Pipe" symbol, such as
+{@Code "@PP"}, {@Code "@Box"}, and so on, will be interpreted in the
+usual way.  This is convenient because it allows you to write your
+own Unix commands that include Lout symbols in their output.  However,
+sometimes it is preferable if the output is treated verbatim.  For
+example,
+@ID @Code @Verbatim { "pwd" @Pipe {} }
+attempts to print the current working directory, but this will not
+come out well because the output contains {@Code "/"} symbols, which
+Lout will then attempt to interpret as Lout symbols.  To avoid this
+problem, use @Code "@PipeVerbatim" instead of {@Code "@Pipe"}:
+pipeverbatim.sym @Index @Code "@PipeVerbatim"
+piperawverbatim.sym @Index @Code "@PipeRawVerbatim"
+@ID @Code @Verbatim { "pwd" @PipeVerbatim {} }
+This causes the output of the command to be enclosed in
+@Code "@Verbatim @Begin" and {@Code "@End @Verbatim"}.  There is
+also a @Code "@PipeRawVerbatim" symbol which encloses the output in
+@Code "@RawVerbatim" rather than the ordinary {@Code "@Verbatim"}.
 @End @Section
diff --git a/doc/user/dia_link b/doc/user/dia_link
index f3a80fb..fb44c8c 100644
--- a/doc/user/dia_link
+++ b/doc/user/dia_link
@@ -244,6 +244,10 @@ of possible values for @Code "arrowstyle" is
     B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
 	// @Link from { A } to { B } arrow { yes } arrowstyle { solid } } }
 @Rowa
+    A { solidwithbar }
+    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
+	// @Link from { A } to { B } arrow { yes } arrowstyle { solidwithbar } } }
+@Rowa
     A { halfopen }
     B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
 	// @Link from { A } to { B } arrow { yes } arrowstyle { halfopen } } }
@@ -285,6 +289,18 @@ path, at the appropriate width (although never dashed or dotted), from its
 base to its point, and hence can and does ensure that the link path does
 not overstrike and thicken the point of the arrow.
 }
+The arrow with style @Code solidwithbar has a bar at the tip of the
+arrowhead, whose length equals the width of the arrow and whose
+width is {@Code pathwidth}, like this:
+@ID @Diag {
+A:: @Box margin { 0i } outlinestyle { noline } 3c @Wide
+//
+@Link from { A@W } to { A@CTR } arrow { forward } arrowstyle { solidwithbar }
+@Link from { A@CTR } to { A@E } arrow { back } backarrowstyle { solidwithbar }
+}
+This example shows that half of the bar extends beyond the area
+allocated to the arrow, so that if two of these arrows meet from
+opposite directions, their bars will exactly overstrike.
 @PP
 Corresponding with {@Code arrowstyle}, {@Code arrowwidth}, and
 {@Code arrowlength}, there are {@Code backarrowstyle},
diff --git a/doc/user/dia_node b/doc/user/dia_node
index 068bca1..52f6b4d 100644
--- a/doc/user/dia_node
+++ b/doc/user/dia_node
@@ -94,23 +94,34 @@ file option may be overridden at any node by giving the option again there.
 Sometimes a diagram contains several different node types, each with
 its own combination of options (for example, the syntax diagrams of
 Section {@NumberOf dia_synt} have three node types).  To handle these
-cases there are three alternative versions of the @Code "@Node"
-symbol, called {@Code "@ANode"}, {@Code "@BNode"}, and
+cases there are five alternative versions of the @Code "@Node"
+symbol, called {@Code "@ANode"},
 diagrams. @RawIndex { diagrams }
 diagrams.anode @SubIndex { @Code "@ANode" symbol }
 anode.diagrams @Index { @Code "@ANode" symbol (diagrams) }
+{@Code "@BNode"},
 diagrams. @RawIndex { diagrams }
 diagrams.bnode @SubIndex { @Code "@BNode" symbol }
 bnode.diagrams @Index { @Code "@BNode" symbol (diagrams) }
+{@Code "@CNode"},
 diagrams. @RawIndex { diagrams }
 diagrams.cnode @SubIndex { @Code "@CNode" symbol }
 cnode.diagrams @Index { @Code "@CNode" symbol (diagrams) }
-{@Code "@CNode"}.  These have exactly the same options as
+{@Code "@DNode"},
+diagrams. @RawIndex { diagrams }
+diagrams.dnode @SubIndex { @Code "@DNode" symbol }
+dnode.diagrams @Index { @Code "@DNode" symbol (diagrams) }
+and
+diagrams. @RawIndex { diagrams }
+diagrams.enode @SubIndex { @Code "@ENode" symbol }
+enode.diagrams @Index { @Code "@ENode" symbol (diagrams) }
+{@Code "@ENode"}.  These have exactly the same options as
 {@Code "@Node"}, but the @I default values of these options
 are different, in that they come from @Code "@Diag" options,
 or else setup file options, that have an extra letter in front
-of their name:  @Code { a }, @Code { b }, or @Code { c }.  Here is
-a small example (see later in this section for the @Code font option):
+of their name:  @Code { a }, @Code { b }, @Code { c },
+@Code { d }, or @Code { e }.  Here is a small example (see later
+in this section for the @Code font option):
 @ID @OneRow {
 @Code @Verbatim {
 @Diag
@@ -137,9 +148,10 @@ a small example (see later in this section for the @Code font option):
 }
 }
 Note that when giving an option directly to {@Code "@ANode"},
-{@Code "@BNode"}, and {@Code "@CNode"}, the initial @Code { a },
-@Code { b }, or @Code { c } used with @Code "@Diag" and in the
-setup file is omitted.
+{@Code "@BNode"}, {@Code "@CNode"}, {@Code "@DNode"}, and
+{@Code "@ENode"}, the initial @Code { a }, @Code { b },
+@Code { c }, @Code { d }, or @Code { e } used with @Code "@Diag"
+and in the setup file is omitted.
 @PP
 To save time in simple cases, @Code "@Diag" provides nine other
 node symbols called
diff --git a/doc/user/dia_synt b/doc/user/dia_synt
index 614cc54..48f341b 100644
--- a/doc/user/dia_synt
+++ b/doc/user/dia_synt
@@ -54,6 +54,11 @@ where @Code { ... } stands for the rest of the diagram, as we are about
 to describe.  For completeness there are also @Code "@StartLeft" and
 @Code "@StartUp" symbols, but diagrams never start off in these directions.
 @PP
+If you accidentally omit the starting symbol ({@Code "@StartRight"} or
+whatever), you will get several error messages, the first of which
+should mention @Code { diag_dirn }; it is trying to tell you, in a
+cryptic way, that it doesn't know which direction you want to go in.
+@PP
 The @Code title option is optional; if given, the effect is as shown
 (this option is also available with {@Code "@Diag"}).  Subsequent
 examples will omit the enclosing {@Code "@SyntaxDiag { ... }"}.
@@ -76,13 +81,13 @@ Lout will insert the appropriate arrows, taking account of which
 direction (right, up, left, or down) the diagram is currently
 moving.  This is true for all the syntax diagram symbols; we
 won't mention it again.
-@FootNote {
-This wonderfully useful effect is achieved by a dirty trick, one
-of whose consequences is that if you see an error message
-similar to `@Code { replacing unknown "@Case" option 0p by 1p }'
-it means you've forgotten the initial @Code "@StartRight" or
-whatever.
-}
+# @FootNote {
+# This wonderfully useful effect is achieved by a dirty trick, one
+# of whose consequences is that if you see an error message
+# similar to `@Code { replacing unknown "@Case" option 0p by 1p }'
+# it means you've forgotten the initial @Code "@StartRight" or
+# whatever.
+# }
 @PP
 Occasionally, instead of a cell one wants the horizontal or
 vertical line to continue uninterrupted.  For this there is
@@ -555,9 +560,12 @@ symbols of @@Diag to construct its three types of cells.  In fact, the
 So any of the other @Code "@Diag" options can be used freely with
 {@Code "@SyntaxDiag"}; and the format of the three cell types can be
 changed by using @Code "@Diag" instead of {@Code "@SyntaxDiag"}, and
-choosing new values for these (and other) options.
+choosing new values for these (and other) options.  For example, if
+you need four or five types of cell, just set some @Code { d } and
+@Code { e } options and use @Code "@DCell" and @Code "@ECell" in
+addition to {@Code "@ACell"}, {@Code "@BCell"}, and {@Code "@CCell"}.
 @PP
-If there are more than three cell types, it is necessary to fall back
+If there are more than five cell types, it is necessary to fall back
 on the {@Code "@XCell"} symbol, which produces a cell without nominating
 any particular cell type.  After @Code "@XCell" there must be a regular
 @Code "@Diag" node, like this:
@@ -570,12 +578,13 @@ any particular cell type.  After @Code "@XCell" there must be a regular
 @StartRight @XCell @Ellipse INIT
 }
 }
-This way there is no limit to the number of different kinds of cells.  Also,
-since (for example) @Code "@ACell" is merely an abbreviation for
+This way there is no limit to the number of different kinds of cells.
+Also, since (for example) @Code "@ACell" is merely an abbreviation for
 @ID @OneRow @Code @Verbatim { @XCell @ANode }
-any node options may follow {@Code "@ACell"}, {@Code "@BCell"}, and
-{@Code "@CCell"}.  The appearance of the arrows can be changed in the usual
-way, by setting options as has been done above for {@Code "arrowlength"}.
+any node options may follow {@Code "@ACell"}, {@Code "@BCell"},
+{@Code "@CCell"}, {@Code "@DCell"}, and {@Code "@ECell"}.  The
+appearance of the arrows can be changed in the usual way, by
+setting options as has been done above for {@Code "arrowlength"}.
 @PP
 There are three options specifically related to syntax diagrams:
 @ID @OneRow @Code @Verbatim {
diff --git a/doc/user/preface b/doc/user/preface
index 505b0d3..b3a4466 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.33.tar.gz"}), and various other things including
+(currently {@Code "lout-3.34.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
diff --git a/doc/user/str_figs b/doc/user/str_figs
index 60e2677..c5897de 100644
--- a/doc/user/str_figs
+++ b/doc/user/str_figs
@@ -28,6 +28,8 @@ captions.figures @SubIndex { in @Code "@Figure" and @Code "@Table" }
 can see this example at the top of page {@PageOf figex}.  Tables are
 table. @Index @Code "@Table"
 obtained in the same way using {@Code "@Table"} instead of {@Code "@Figure"}.
+There is a third symbol called {@Code "@Floater"}.  It won't be mentioned
+again, but it works exactly like like @Code "@Figure" and {@Code "@Table"}.
 @PP
 @Code "@Figure" and @Code "@Table" each have an @Code "@InitialLanguage"
 option which determines the language of the figure or table.  If this is