Lout 3.17.

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

1 files changed, 96 insertions, 0 deletions

diff --git a/doc/user/tbl_alig b/doc/user/tbl_alig
new file mode 100644
index 0000000..24b6864
--- /dev/null
+++ b/doc/user/tbl_alig
@@ -0,0 +1,96 @@
+@Section
+    @Title { Aligned columns }
+    @Tag { tbl_alig }
+@Begin
+@PP
+Columns of numbers are often presented with decimal points aligned:
+aligned.columns @Index { aligned columns in tables }
+@CD @OneRow @Tbl
+    marginvertical { 0.5vx }
+    aformat { @Cell A }
+{
+@Rowa A { 5^.46 } marginabove { 0i }
+@Rowa A { 3^.4159 }
+@Rowa A { 5772^ } marginbelow { 0i }
+}
+You can produce this by placing a @Code "^" symbol, which is used
+generally throughout Lout for alignment, just before the alignment point in
+each entry:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    marginvertical { 0.5vx }
+    aformat { @Cell A }
+{
+@Rowa A { 5^.46 }
+@Rowa A { 3^.4159 }
+@Rowa A { 5772^ }
+}
+}
+The equals signs of equations can be aligned in the same way (see the
+example at the start of this chapter).  Aligned cells should have no
+@Code indent option.
+@PP
+Owing to problems behind the scenes, getting a heading over the top
+of an aligned column is a problem with no ideal solution.  What most
+people want is for the heading to be centred in the column, and the
+aligned entries to be centred in the column as a block, but Lout cannot
+do this.  One approximation is to make the heading cell a spanning
+cell with centring, like this:
+@FootNote { Lout does not currently accept single-column tables
+with {@Code "@StartHSpan"}, so we've had to add
+an empty second column. }
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    marginvertical { 0.5vx }
+    aformat { @StartHSpan @Cell indent { ctr } @B A | }
+    bformat { @Cell A | }
+{
+@Rowa A { Heading }
+@Rowb A { 5^.46 }
+@Rowb A { 3^.4159 }
+@Rowb A { 5772^ }
+}
+}
+The spanning frees the heading from alignment, permitting
+@Code "indent { ctr }" to work:
+@CD @OneRow @Tbl
+    marginvertical { 0.5vx }
+    aformat { @StartHSpan @Cell indent { ctr } @B A | }
+    bformat { @Cell A | }
+{
+@Rowa A { Heading } marginabove { 0i }
+@Rowb A { 5^.46 }
+@Rowb A { 3^.4159 }
+@Rowb A { 5772^ } marginbelow { 0i }
+}
+But if the heading cell is wider than the aligned cells, you get this:
+@CD @OneRow @Tbl
+    marginvertical { 0.5vx }
+    aformat { @StartHSpan @Cell indent { ctr } @B A | }
+    bformat { @Cell A | }
+{
+@Rowa A { A Wider Heading } marginabove { 0i }
+@Rowb A { 5^.46 }
+@Rowb A { 3^.4159 }
+@Rowb A { 5772^ } marginbelow { 0i }
+}
+In other words, this will centre a heading with respect
+to aligned entries, but it will not centre aligned entries with
+respect to a heading.  In these cases you could forget about
+@Code "@StartHSpan" and treat the heading as an aligned entry,
+either by placing a @Code "^" within it or by using
+@ID @Code "@Cell 0.5w @HShift A"
+which places the alignment point in the centre of the entry.
+#@CD @OneRow @Tbl
+#    marginvertical { 0.5vx }
+#    aformat { @Cell 0.5w @HShift @B A }
+#    bformat { @Cell A }
+#{
+#@Rowa A { A Wider Heading } marginabove { 0i }
+#@Rowb A { 5^.46 }
+#@Rowb A { 3^.4159 }
+#@Rowb A { 5772^ } marginbelow { 0i }
+#}
+You can move the alignment point about by changing the 0.5.  Of course,
+all this is a poor substitute for the real thing.
+@End @Section