diff options
Diffstat (limited to 'doc/user')
115 files changed, 5381 insertions, 1660 deletions
diff --git a/doc/user/README b/doc/user/README index 86f6ce2..85c95c7 100644 --- a/doc/user/README +++ b/doc/user/README @@ -17,22 +17,14 @@ 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 "typ_repo" (from "typ" line 19, from "all" line 38): - 38,1: 1.0c object too high for 0.2c space; will try elsewhere -lout file "typ_over" (from "typ" line 21, from "all" line 38): - 8,1: 1.0c object too high for 0.0c space; will try elsewhere -lout file "gra_summ" (from "gra" line 44, from "all" line 45): - 8,1: 23.6c object too high for 23.6c space; @Scale inserted -lout file "prg_tabs" (from "prg" line 108, from "all" line 46): - 58,23: prg2lout 2,1: program text ended within comment - 60,35: prg2lout 2,1: program text ended within comment - -The first two warnings are about footnotes whose first lines did not -fit on the bottom of the current page, so had to begin on the following -page. The third warning is about a large table that had to be scaled -down very slightly to fit on the page (lengths are printed to one -decimal place, which in this case gives the misleading impression -that the table did actually fit to begin with). The last two warnings +lout file "gra_summ" (from "gra" line 44, from "all" line 46): + 10,1: 23.7c object too high for 23.6c space; @Scale inserted +lout file "prg_tabs" (from "prg" line 112, from "all" line 48): + 66,23: prg2lout 2,1: program text ended within comment + 68,35: prg2lout 2,1: program text ended within comment + +The first warning is about a large table that had to be scaled +down very slightly to fit on the page. The last two warnings point to two places where a C program text ended inside a comment, which in these cases was deliberate. If you set the document in Letter size paper, you will get a somewhat different set of warning @@ -43,7 +35,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.26.user.ps.gz". +stored at "ftp://ftp.cs.su.oz.au/jeff/lout/lout-3.27.user.ps.gz". Jeffrey H. Kingston -16 October 2002 +22 November 2002 diff --git a/doc/user/all b/doc/user/all index a10e5c6..b92514b 100644 --- a/doc/user/all +++ b/doc/user/all @@ -1,8 +1,9 @@ +@SysInclude { xrgb } @SysInclude { tab } @SysInclude { tbl } @SysInclude { eq } -@SysInclude { fig } @SysInclude { graph } +@SysInclude { pie } @SysInclude { pas } @SysInclude { diag } @SysInclude { cprint } @@ -21,11 +22,11 @@ Lout Document Formatting System } @Author { Jeffrey H. Kingston } - @Edition { Version 3.26 -October, 2002 } + @Edition { Version 3.27 +November, 2002 } @Publisher { Copyright @CopyRight 1991, 2002 Jeffrey H. Kingston, -Basser Department of Computer Science, +School of Information Technologies, The University of Sydney 2006, Australia. ISBN 0 86758 951 5. } @InitialLanguage { English } @@ -43,7 +44,9 @@ The University of Sydney 2006, Australia. ISBN 0 86758 951 5. @Include { bgr } @Include { dia } @Include { gra } +@Include { pie } @Include { prg } @Include { pascal } @Include { ap_qck } @Include { ap_byp } +@Include { ap_col } diff --git a/doc/user/ap_byp b/doc/user/ap_byp index a1c1bd7..18ee641 100644 --- a/doc/user/ap_byp +++ b/doc/user/ap_byp @@ -4,6 +4,7 @@ @Begin @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 diff --git a/doc/user/ap_col b/doc/user/ap_col new file mode 100644 index 0000000..36306d1 --- /dev/null +++ b/doc/user/ap_col @@ -0,0 +1,581 @@ +@Appendix + @Title { Lots more colours } + @Tag { morecolours } +@Begin +Here is the long list of extra colours, said to be from the +xrgb @Index { @Code "@Xrgb" symbol } +X windows system, that you can get by placing +@Code "@SysInclude { xrgb }" at the start of your document and +using the @Code "@Xrgb" symbol. For example, you might write +@ID @Code "{@Xrgb oldlace} @Colour ..." +or +@ID @Code "@Box paint { @Xrgb oldlace } ..." +You can't get these colours just by giving their +names; you have to use the @Code "@Xrgb" symbol. Wherever +@Code "grey" appears it may also be spelt {@Code gray}. +@PP +There are 541 colours here. I've removed capitalized alternative +spellings and hyphens from the information provided to me. Thanks +to Mark Summerfield for providing this information. +@DP +@XRGBTest black +@XRGBTest snow +@XRGBTest ghostwhite +@XRGBTest whitesmoke +@XRGBTest gainsboro +@XRGBTest floralwhite +@XRGBTest oldlace +@XRGBTest linen +@XRGBTest antiquewhite +@XRGBTest papayawhip +@XRGBTest blanchedalmond +@XRGBTest bisque +@XRGBTest peachpuff +@XRGBTest navajowhite +@XRGBTest moccasin +@XRGBTest cornsilk +@XRGBTest ivory +@XRGBTest lemonchiffon +@XRGBTest seashell +@XRGBTest honeydew +@XRGBTest mintcream +@XRGBTest azure +@XRGBTest aliceblue +@XRGBTest lavender +@XRGBTest lavenderblush +@XRGBTest mistyrose +@XRGBTest white +@XRGBTest darkslategrey +@XRGBTest dimgrey +@XRGBTest slategrey +@XRGBTest lightslategrey +@XRGBTest grey +@XRGBTest lightgrey +@XRGBTest midnightblue +@XRGBTest navy +@XRGBTest navyblue +@XRGBTest cornflowerblue +@XRGBTest darkslateblue +@XRGBTest slateblue +@XRGBTest mediumslateblue +@XRGBTest lightslateblue +@XRGBTest mediumblue +@XRGBTest royalblue +@XRGBTest blue +@XRGBTest dodgerblue +@XRGBTest deepskyblue +@XRGBTest skyblue +@XRGBTest lightskyblue +@XRGBTest steelblue +@XRGBTest lightsteelblue +@XRGBTest lightblue +@XRGBTest powderblue +@XRGBTest paleturquoise +@XRGBTest darkturquoise +@XRGBTest mediumturquoise +@XRGBTest turquoise +@XRGBTest cyan +@XRGBTest lightcyan +@XRGBTest cadetblue +@XRGBTest mediumaquamarine +@XRGBTest aquamarine +@XRGBTest darkgreen +@XRGBTest darkolivegreen +@XRGBTest darkseagreen +@XRGBTest seagreen +@XRGBTest mediumseagreen +@XRGBTest lightseagreen +@XRGBTest palegreen +@XRGBTest springgreen +@XRGBTest lawngreen +@XRGBTest green +@XRGBTest chartreuse +@XRGBTest mediumspringgreen +@XRGBTest greenyellow +@XRGBTest limegreen +@XRGBTest yellowgreen +@XRGBTest forestgreen +@XRGBTest olivedrab +@XRGBTest darkkhaki +@XRGBTest khaki +@XRGBTest palegoldenrod +@XRGBTest lightgoldenrodyellow +@XRGBTest lightyellow +@XRGBTest yellow +@XRGBTest gold +@XRGBTest lightgoldenrod +@XRGBTest goldenrod +@XRGBTest darkgoldenrod +@XRGBTest rosybrown +@XRGBTest indianred +@XRGBTest saddlebrown +@XRGBTest sienna +@XRGBTest peru +@XRGBTest burlywood +@XRGBTest beige +@XRGBTest wheat +@XRGBTest sandybrown +@XRGBTest tan +@XRGBTest chocolate +@XRGBTest firebrick +@XRGBTest brown +@XRGBTest darksalmon +@XRGBTest salmon +@XRGBTest lightsalmon +@XRGBTest orange +@XRGBTest darkorange +@XRGBTest coral +@XRGBTest lightcoral +@XRGBTest tomato +@XRGBTest orangered +@XRGBTest red +@XRGBTest hotpink +@XRGBTest deeppink +@XRGBTest pink +@XRGBTest lightpink +@XRGBTest palevioletred +@XRGBTest maroon +@XRGBTest mediumvioletred +@XRGBTest violetred +@XRGBTest magenta +@XRGBTest violet +@XRGBTest plum +@XRGBTest orchid +@XRGBTest mediumorchid +@XRGBTest darkorchid +@XRGBTest darkviolet +@XRGBTest blueviolet +@XRGBTest purple +@XRGBTest mediumpurple +@XRGBTest thistle +@XRGBNoTest +@XRGBNoTest +@XRGBNoTest +@XRGBNoTest +@DP +@XRGBTest snow1 +@XRGBTest snow2 +@XRGBTest snow3 +@XRGBTest snow4 +@XRGBTest seashell1 +@XRGBTest seashell2 +@XRGBTest seashell3 +@XRGBTest seashell4 +@XRGBTest antiquewhite1 +@XRGBTest antiquewhite2 +@XRGBTest antiquewhite3 +@XRGBTest antiquewhite4 +@XRGBTest bisque1 +@XRGBTest bisque2 +@XRGBTest bisque3 +@XRGBTest bisque4 +@XRGBTest peachpuff1 +@XRGBTest peachpuff2 +@XRGBTest peachpuff3 +@XRGBTest peachpuff4 +@XRGBTest navajowhite1 +@XRGBTest navajowhite2 +@XRGBTest navajowhite3 +@XRGBTest navajowhite4 +@XRGBTest lemonchiffon1 +@XRGBTest lemonchiffon2 +@XRGBTest lemonchiffon3 +@XRGBTest lemonchiffon4 +@XRGBTest cornsilk1 +@XRGBTest cornsilk2 +@XRGBTest cornsilk3 +@XRGBTest cornsilk4 +@XRGBTest ivory1 +@XRGBTest ivory2 +@XRGBTest ivory3 +@XRGBTest ivory4 +@XRGBTest honeydew1 +@XRGBTest honeydew2 +@XRGBTest honeydew3 +@XRGBTest honeydew4 +@XRGBTest lavenderblush1 +@XRGBTest lavenderblush2 +@XRGBTest lavenderblush3 +@XRGBTest lavenderblush4 +@XRGBTest mistyrose1 +@XRGBTest mistyrose2 +@XRGBTest mistyrose3 +@XRGBTest mistyrose4 +@XRGBTest azure1 +@XRGBTest azure2 +@XRGBTest azure3 +@XRGBTest azure4 +@XRGBTest slateblue1 +@XRGBTest slateblue2 +@XRGBTest slateblue3 +@XRGBTest slateblue4 +@XRGBTest royalblue1 +@XRGBTest royalblue2 +@XRGBTest royalblue3 +@XRGBTest royalblue4 +@XRGBTest blue1 +@XRGBTest blue2 +@XRGBTest blue3 +@XRGBTest blue4 +@XRGBTest dodgerblue1 +@XRGBTest dodgerblue2 +@XRGBTest dodgerblue3 +@XRGBTest dodgerblue4 +@XRGBTest steelblue1 +@XRGBTest steelblue2 +@XRGBTest steelblue3 +@XRGBTest steelblue4 +@XRGBTest deepskyblue1 +@XRGBTest deepskyblue2 +@XRGBTest deepskyblue3 +@XRGBTest deepskyblue4 +@XRGBTest skyblue1 +@XRGBTest skyblue2 +@XRGBTest skyblue3 +@XRGBTest skyblue4 +@XRGBTest lightskyblue1 +@XRGBTest lightskyblue2 +@XRGBTest lightskyblue3 +@XRGBTest lightskyblue4 +@XRGBTest lightsteelblue1 +@XRGBTest lightsteelblue2 +@XRGBTest lightsteelblue3 +@XRGBTest lightsteelblue4 +@XRGBTest lightblue1 +@XRGBTest lightblue2 +@XRGBTest lightblue3 +@XRGBTest lightblue4 +@XRGBTest lightcyan1 +@XRGBTest lightcyan2 +@XRGBTest lightcyan3 +@XRGBTest lightcyan4 +@XRGBTest paleturquoise1 +@XRGBTest paleturquoise2 +@XRGBTest paleturquoise3 +@XRGBTest paleturquoise4 +@XRGBTest cadetblue1 +@XRGBTest cadetblue2 +@XRGBTest cadetblue3 +@XRGBTest cadetblue4 +@XRGBTest turquoise1 +@XRGBTest turquoise2 +@XRGBTest turquoise3 +@XRGBTest turquoise4 +@XRGBTest cyan1 +@XRGBTest cyan2 +@XRGBTest cyan3 +@XRGBTest cyan4 +@XRGBTest aquamarine1 +@XRGBTest aquamarine2 +@XRGBTest aquamarine3 +@XRGBTest aquamarine4 +@XRGBTest darkseagreen1 +@XRGBTest darkseagreen2 +@XRGBTest darkseagreen3 +@XRGBTest darkseagreen4 +@XRGBTest seagreen1 +@XRGBTest seagreen2 +@XRGBTest seagreen3 +@XRGBTest seagreen4 +@XRGBTest palegreen1 +@XRGBTest palegreen2 +@XRGBTest palegreen3 +@XRGBTest palegreen4 +@XRGBTest springgreen1 +@XRGBTest springgreen2 +@XRGBTest springgreen3 +@XRGBTest springgreen4 +@XRGBTest green1 +@XRGBTest green2 +@XRGBTest green3 +@XRGBTest green4 +@XRGBTest chartreuse1 +@XRGBTest chartreuse2 +@XRGBTest chartreuse3 +@XRGBTest chartreuse4 +@XRGBTest olivedrab1 +@XRGBTest olivedrab2 +@XRGBTest olivedrab3 +@XRGBTest olivedrab4 +@XRGBTest darkolivegreen1 +@XRGBTest darkolivegreen2 +@XRGBTest darkolivegreen3 +@XRGBTest darkolivegreen4 +@XRGBTest khaki1 +@XRGBTest khaki2 +@XRGBTest khaki3 +@XRGBTest khaki4 +@XRGBTest lightgoldenrod1 +@XRGBTest lightgoldenrod2 +@XRGBTest lightgoldenrod3 +@XRGBTest lightgoldenrod4 +@XRGBTest lightyellow1 +@XRGBTest lightyellow2 +@XRGBTest lightyellow3 +@XRGBTest lightyellow4 +@XRGBTest yellow1 +@XRGBTest yellow2 +@XRGBTest yellow3 +@XRGBTest yellow4 +@XRGBTest gold1 +@XRGBTest gold2 +@XRGBTest gold3 +@XRGBTest gold4 +@XRGBTest goldenrod1 +@XRGBTest goldenrod2 +@XRGBTest goldenrod3 +@XRGBTest goldenrod4 +@XRGBTest darkgoldenrod1 +@XRGBTest darkgoldenrod2 +@XRGBTest darkgoldenrod3 +@XRGBTest darkgoldenrod4 +@XRGBTest rosybrown1 +@XRGBTest rosybrown2 +@XRGBTest rosybrown3 +@XRGBTest rosybrown4 +@XRGBTest indianred1 +@XRGBTest indianred2 +@XRGBTest indianred3 +@XRGBTest indianred4 +@XRGBTest sienna1 +@XRGBTest sienna2 +@XRGBTest sienna3 +@XRGBTest sienna4 +@XRGBTest burlywood1 +@XRGBTest burlywood2 +@XRGBTest burlywood3 +@XRGBTest burlywood4 +@XRGBTest wheat1 +@XRGBTest wheat2 +@XRGBTest wheat3 +@XRGBTest wheat4 +@XRGBTest tan1 +@XRGBTest tan2 +@XRGBTest tan3 +@XRGBTest tan4 +@XRGBTest chocolate1 +@XRGBTest chocolate2 +@XRGBTest chocolate3 +@XRGBTest chocolate4 +@XRGBTest firebrick1 +@XRGBTest firebrick2 +@XRGBTest firebrick3 +@XRGBTest firebrick4 +@XRGBTest brown1 +@XRGBTest brown2 +@XRGBTest brown3 +@XRGBTest brown4 +@XRGBTest salmon1 +@XRGBTest salmon2 +@XRGBTest salmon3 +@XRGBTest salmon4 +@XRGBTest lightsalmon1 +@XRGBTest lightsalmon2 +@XRGBTest lightsalmon3 +@XRGBTest lightsalmon4 +@XRGBTest orange1 +@XRGBTest orange2 +@XRGBTest orange3 +@XRGBTest orange4 +@XRGBTest darkorange1 +@XRGBTest darkorange2 +@XRGBTest darkorange3 +@XRGBTest darkorange4 +@XRGBTest coral1 +@XRGBTest coral2 +@XRGBTest coral3 +@XRGBTest coral4 +@XRGBTest tomato1 +@XRGBTest tomato2 +@XRGBTest tomato3 +@XRGBTest tomato4 +@XRGBTest orangered1 +@XRGBTest orangered2 +@XRGBTest orangered3 +@XRGBTest orangered4 +@XRGBTest red1 +@XRGBTest red2 +@XRGBTest red3 +@XRGBTest red4 +@XRGBTest deeppink1 +@XRGBTest deeppink2 +@XRGBTest deeppink3 +@XRGBTest deeppink4 +@XRGBTest hotpink1 +@XRGBTest hotpink2 +@XRGBTest hotpink3 +@XRGBTest hotpink4 +@XRGBTest pink1 +@XRGBTest pink2 +@XRGBTest pink3 +@XRGBTest pink4 +@XRGBTest lightpink1 +@XRGBTest lightpink2 +@XRGBTest lightpink3 +@XRGBTest lightpink4 +@XRGBTest palevioletred1 +@XRGBTest palevioletred2 +@XRGBTest palevioletred3 +@XRGBTest palevioletred4 +@XRGBTest maroon1 +@XRGBTest maroon2 +@XRGBTest maroon3 +@XRGBTest maroon4 +@XRGBTest violetred1 +@XRGBTest violetred2 +@XRGBTest violetred3 +@XRGBTest violetred4 +@XRGBTest magenta1 +@XRGBTest magenta2 +@XRGBTest magenta3 +@XRGBTest magenta4 +@XRGBTest orchid1 +@XRGBTest orchid2 +@XRGBTest orchid3 +@XRGBTest orchid4 +@XRGBTest plum1 +@XRGBTest plum2 +@XRGBTest plum3 +@XRGBTest plum4 +@XRGBTest mediumorchid1 +@XRGBTest mediumorchid2 +@XRGBTest mediumorchid3 +@XRGBTest mediumorchid4 +@XRGBTest darkorchid1 +@XRGBTest darkorchid2 +@XRGBTest darkorchid3 +@XRGBTest darkorchid4 +@XRGBTest purple1 +@XRGBTest purple2 +@XRGBTest purple3 +@XRGBTest purple4 +@XRGBTest mediumpurple1 +@XRGBTest mediumpurple2 +@XRGBTest mediumpurple3 +@XRGBTest mediumpurple4 +@XRGBTest thistle1 +@XRGBTest thistle2 +@XRGBTest thistle3 +@XRGBTest thistle4 +@XRGBNoTest +@XRGBNoTest +@XRGBNoTest +@XRGBNoTest +@DP +@XRGBTest grey0 +@XRGBTest grey1 +@XRGBTest grey2 +@XRGBTest grey3 +@XRGBTest grey4 +@XRGBTest grey5 +@XRGBTest grey6 +@XRGBTest grey7 +@XRGBTest grey8 +@XRGBTest grey9 +@XRGBTest grey10 +@XRGBTest grey11 +@XRGBTest grey12 +@XRGBTest grey13 +@XRGBTest grey14 +@XRGBTest grey15 +@XRGBTest grey16 +@XRGBTest grey17 +@XRGBTest grey18 +@XRGBTest grey19 +@XRGBTest grey20 +@XRGBTest grey21 +@XRGBTest grey22 +@XRGBTest grey23 +@XRGBTest grey24 +@XRGBTest grey25 +@XRGBTest grey26 +@XRGBTest grey27 +@XRGBTest grey28 +@XRGBTest grey29 +@XRGBTest grey30 +@XRGBTest grey31 +@XRGBTest grey32 +@XRGBTest grey33 +@XRGBTest grey34 +@XRGBTest grey35 +@XRGBTest grey36 +@XRGBTest grey37 +@XRGBTest grey38 +@XRGBTest grey39 +@XRGBTest grey40 +@XRGBTest grey41 +@XRGBTest grey42 +@XRGBTest grey43 +@XRGBTest grey44 +@XRGBTest grey45 +@XRGBTest grey46 +@XRGBTest grey47 +@XRGBTest grey48 +@XRGBTest grey49 +@XRGBTest grey50 +@XRGBTest grey51 +@XRGBTest grey52 +@XRGBTest grey53 +@XRGBTest grey54 +@XRGBTest grey55 +@XRGBTest grey56 +@XRGBTest grey57 +@XRGBTest grey58 +@XRGBTest grey59 +@XRGBTest grey60 +@XRGBTest grey61 +@XRGBTest grey62 +@XRGBTest grey63 +@XRGBTest grey64 +@XRGBTest grey65 +@XRGBTest grey66 +@XRGBTest grey67 +@XRGBTest grey68 +@XRGBTest grey69 +@XRGBTest grey70 +@XRGBTest grey71 +@XRGBTest grey72 +@XRGBTest grey73 +@XRGBTest grey74 +@XRGBTest grey75 +@XRGBTest grey76 +@XRGBTest grey77 +@XRGBTest grey78 +@XRGBTest grey79 +@XRGBTest grey80 +@XRGBTest grey81 +@XRGBTest grey82 +@XRGBTest grey83 +@XRGBTest grey84 +@XRGBTest grey85 +@XRGBTest grey86 +@XRGBTest grey87 +@XRGBTest grey88 +@XRGBTest grey89 +@XRGBTest grey90 +@XRGBTest grey91 +@XRGBTest grey92 +@XRGBTest grey93 +@XRGBTest grey94 +@XRGBTest grey95 +@XRGBTest grey96 +@XRGBTest grey97 +@XRGBTest grey98 +@XRGBTest grey99 +@XRGBTest grey100 +@XRGBNoTest +@XRGBNoTest +@XRGBNoTest +@XRGBNoTest +@DP +@XRGBTest darkgrey +@XRGBTest darkblue +@XRGBTest darkcyan +@XRGBTest darkmagenta +@XRGBTest darkred +@XRGBTest lightgreen +@XRGBNoTest # makes a dummy last line to ensure adjusting on all lines +@XRGBNoTest +@XRGBNoTest +@XRGBNoTest +@End @Appendix diff --git a/doc/user/bas_font b/doc/user/bas_font index c59225f..1241966 100644 --- a/doc/user/bas_font +++ b/doc/user/bas_font @@ -4,7 +4,6 @@ @Begin @PP A @I font is a collection of characters that may be printed. For -font. @Index { font } example, here is the Times Roman font: @ID @OneRow { Times Base } @Font 0.05c @Space { { @Char space } @@ -574,7 +573,7 @@ to have a @Code { Slope } face that is guaranteed to exist no matter which family is used. @PP The @Code "@Font" symbol changes the font of the following object. For -font.sym @Index @Code "@Font" +font.sym @Index { @Code "@Font" symbol } example, @ID @Code "{ Helvetica Slope } @Font { Hello World }" produces @@ -607,7 +606,7 @@ through the baseline, causing this awkward alignment. This was done because it makes equation formatting easy, and examples like the above look poor anyway. However, if you want to do this and so require alignment through the baseline, you can get it, with the @Code baselinemark -option to the @Code "@Font" symbol like this: +option to the @Code "@Font" symbol: @ID @Code "baselinemark @Font { Here's a 20p @Font big word }" which produces @ID @Code { baselinemark @Font { Here's a 20p @Font big word } } @@ -615,20 +614,18 @@ If you want it this way throughout your document, you can put @Code { baselinemark } in your initial font (see below). Lout's equation formatter contains the opposite option, which is @Code "xheight2mark @Font { ... }" -(meaning that the alignment goes through a point half the height of +(which aligns through a point half the height of an x character) so you won't disrupt equation formatting if you do -this, although you will have a problem if you put an equation inside -a paragraph, since its axis will be aligned with the baseline of -the adjacent words. +this, although if you put an equation inside a paragraph, its +axis will be aligned with the baseline of the adjacent words. @PP -For the convenience of people who use fixed width fonts such as -Courier, there is an @Code "@F" symbol which switches to a -fixed width font family: +There is an @Code "@F" symbol which switches to a fixed width font +family: @ID @Code "@F { Hello world }" -produces +produces the equivalent of @Code "{ Courier Base -1p } @Font ...", +like this: @ID @F { Hello world } -It is the same as writing @Code "{ Courier Base -1p } @Font ..." -with the @Code "-1p" included to compensate for the relatively +The @Code "-1p" is included to compensate for the relatively large appearance of the Courier font. @PP The document as a whole will be set in @Code { Times Base 12p }. To diff --git a/doc/user/bas_head b/doc/user/bas_head index 4410c08..485c2a2 100644 --- a/doc/user/bas_head +++ b/doc/user/bas_head @@ -25,8 +25,7 @@ change this by changing the @Code "@HeadingFont" option in the setup headingfont. @Index @Code "@HeadingFont" file (Section {@NumberOf setup}). @PP -The @Code "@Heading" symbol may be used with any type of document, but it -is really intended only for simple ones. In complex documents, large-scale -structure symbols (Section {@NumberOf largescale}) are usually more -appropriate. +In complex documents, large-scale structure symbols +(Section {@NumberOf largescale}) are usually more appropriate +than the @Code "@Heading" symbol. @End @Section diff --git a/doc/user/bas_lang b/doc/user/bas_lang index fec9a63..fea9f3f 100644 --- a/doc/user/bas_lang +++ b/doc/user/bas_lang @@ -14,23 +14,6 @@ language. @Index @Code "@Language" Changing language is quite analogous to changing font using the @Code "@Font" symbol. @PP -Since accented characters (Section {@NumberOf characters}) are always -available irrespective of the language, at first sight it might seem -that there is no need to bother informing Lout what language you are -writing in. However, words are hyphenated differently depending on the -hyphenation.languages @SubIndex { in languages other than English } -language, and some symbols have different results in different -languages. For example, -@ID @Code "Danish @Language @Date" -produces -@ID { Danish @Language @Date } -date.languages @SubIndex { in languages other than English } -time.languages @SubIndex { in languages other than English } -lists.languages @SubIndex { in languages other than English } -and the alphabetic list symbols of Section {@NumberOf lists} also -vary with the current language. So it's worth doing for the sake of -knowing that non-English parts will appear as they should. -@PP At the time of writing, the following languages were available: @ID @OneRow @Code { Croatian Hrvatski @@ -60,6 +43,23 @@ names, all equally acceptable to the @Code "@Language" symbol. @Code "EnglishUK" differs from @Code "English" only by applying hyphenation rules said to be more appropriate for British English. @PP +Since accented characters (Section {@NumberOf characters}) are always +available irrespective of the language, at first sight it might seem +that there is no need to bother informing Lout what language you are +writing in. However, words are hyphenated differently depending on the +hyphenation.languages @SubIndex { in languages other than English } +language, and some symbols have different results in different +languages. For example, +@ID @Code "Danish @Language @Date" +produces +@ID { Danish @Language @Date } +date.languages @SubIndex { in languages other than English } +time.languages @SubIndex { in languages other than English } +lists.languages @SubIndex { in languages other than English } +and the alphabetic list symbols of Section {@NumberOf lists} also +vary with the current language. So it's worth doing for the sake of +knowing that non-English parts will appear as they should. +@PP If your entire document is in a language other than English, you need to change the @Code "@InitialLanguage" option: initiallanguage. @Index @Code "@InitialLanguage" diff --git a/doc/user/bas_par1 b/doc/user/bas_par1 index 0cee5f8..e5ce503 100644 --- a/doc/user/bas_par1 +++ b/doc/user/bas_par1 @@ -34,7 +34,7 @@ is usually equal to {@Code "@DP"}. The {@Code "@NP"} `new page' symbol causes the following paragraph to page. @Index { page, skipping to next } new.page @Index { new page } -np. @Index @Code "@NP" +np. @Index { @Code "@NP" (new page) } begin on a new page or column. Of course, Lout starts a new page or column automatically when the old one is full, so @Code "@NP" is needed only rarely. diff --git a/doc/user/bas_par2 b/doc/user/bas_par2 index 51f674c..b836648 100644 --- a/doc/user/bas_par2 +++ b/doc/user/bas_par2 @@ -5,7 +5,7 @@ @PP @I { Paragraph breaking } is the process of paragraph.breaking @Index { paragraph breaking } -inserting line breaks into praragraphs at places appropriate to the column +inserting line breaks into paragraphs at places appropriate to the column width. Lout works out suitable column widths and performs paragraph breaking automatically, finding an `optimal' break with the method used by the @TeX @@ -20,7 +20,7 @@ must be in want of a wife. } Changing the paragraph breaking style is similar to changing the font, colour, or language, and is done using the @Code "@Break" symbol: -break. @Index @Code "@Break" +breakzzz.sym @Index { @Code "@Break" symbol } @ID @Code "ragged @Break ..." This example causes every paragraph in the following object to be broken using the @Code ragged style, of which more below. @@ -255,7 +255,7 @@ invoked in the @Code "@InitialBreak" option, like this: You can turn them off with @Code "breakablefirst @Break" and @Code "breakablelast @Break". In both cases Lout makes it happen by breaking at the previous place, either between paragraphs or two lines from -the end of a paragraph. Alternatively, both features are compatible with -Lout's @Code "@OptimizePages" option, which will optimize the overall page -layout of the document subject to these requirements. +the end of a paragraph. Both features are compatible with Lout's +@Code "@OptimizePages" option, which optimizes the overall page +layout subject to these requirements. @End @Section diff --git a/doc/user/bas_spac b/doc/user/bas_spac index b7546c2..0a120a8 100644 --- a/doc/user/bas_spac +++ b/doc/user/bas_spac @@ -72,7 +72,8 @@ apply to all of it. For example, leaving the braces out of {@Code "Hello"}. @PP When an object-consuming symbol like @Code "@I" is followed by an -braces. @Index { braces, effect of } +braces. @RawIndex { braces } +braces.in.lout @SubIndex { in Lout text } object enclosed in braces, that is the object consumed. For example, @ID @Code "This is @I { absolutely necessary }, since otherwise ..." produces diff --git a/doc/user/bas_star b/doc/user/bas_star index d2c6653..ec6eb3b 100644 --- a/doc/user/bas_star +++ b/doc/user/bas_star @@ -100,7 +100,7 @@ between words (Section {@NumberOf spaces}), but it will mimic the spacing rules of two other systems, troff and @TeX, if you prefer (Section {@NumberOf white}). @PP When Lout runs, you might see some error messages containing the words -error.messages @Index { error messages } +errors. @Index { errors } `unresolved cross reference' and `no destination point' -- not on file @Code "intro" above, but on more complicated ones (anything with a footnote, for example). These just mean that you have to run the @Code "lout" command diff --git a/doc/user/bgr b/doc/user/bgr index 86e0af4..c0dedbf 100644 --- a/doc/user/bgr +++ b/doc/user/bgr @@ -3,12 +3,15 @@ @Tag { graphics } @Begin @LP -This chapter introduces some basic graphics symbols for colour, rotation, -scaling, and included illustrations. These are all from the standard -BasicLayout package, so no @Code "@SysInclude" line is needed to -get them. +This chapter introduces some basic graphics symbols for colour, texture, +graphics. @Index { graphics (basic) } +graphics.see @RawSubIndex { @I { see also } diagrams, graphs, pie graphs } +rotation, scaling, and included illustrations. These are all from the +standard BasicLayout package, so no @Code "@SysInclude" line is needed to +get them beyond the usual @Code "@SysInclude { doc }" or whatever. @BeginSections @Include { bgr_colo } +@Include { bgr_text } @Include { bgr_boxs } @Include { bgr_outl } @Include { bgr_rota } diff --git a/doc/user/bgr_boxs b/doc/user/bgr_boxs index 54b78a3..775e305 100644 --- a/doc/user/bgr_boxs +++ b/doc/user/bgr_boxs @@ -23,6 +23,8 @@ individual student's name be the work of that student alone. showing that a box may enclose an arbitrarily complicated object. @PP The @Code "@Box" symbol has a @Code margin option which determines the +box. @RawIndex @Code "@Box" +box.margin @SubIndex { @Code "margin" option } margin between the box and what it encloses. For example, @ID @OneRow @Code { "@Box" @@ -38,6 +40,7 @@ is very useful to tie the margin to the font size in this way, because large headings (in overhead transparencies, say) need large margins. @PP There is a @Code "linewidth" option which determines the width +box.linewidth @SubIndex { @Code "linewidth" option } (thickness) of the line drawn around the boundary of the box: @ID @OneRow @Code { "@Box" @@ -60,6 +63,7 @@ value @Code "none" for @Code "linewidth" ensures that no line is drawn around the box at all. @PP There is also a @Code "paint" option which paints a background of the +box.paint @SubIndex { @Code "paint" option } nominated colour: @ID @Code "@Box paint { grey } WARNING!" has result @@ -78,6 +82,61 @@ the moment, with white text inside: This works because the box is painted before the object it encloses is drawn on the page. @PP +Wherever there is a @Code paint option in Lout for painting the background +of something, there is always an accompanying @Code texture option for +box.texture @SubIndex { @Code "texture" option } +applying that paint with the textures described in +Section {@NumberOf textures}. For example, +@ID @Code "@Box paint { black } texture { brickwork } 50p @Font WARNING!" +produces +@FootNote { As explained in Section {@NumberOf textures}, if you can't +see any textures the problem is probably with your PostScript viewer. } +@ID @Box paint { black } texture { brickwork } 50p @Font WARNING! +If @Code paint is absent or @Code none then @Code texture will have no +effect. Since textures are naturally lighter than solid colour, you +will usually need darker paint when using textures than when not. +@PP +To set options on a texture within a @Code "texture" option, you can write +@ID @Code "texture { striped @Texture angle { 45d } scale { 2 } }" +mimicking the @Code "@Texture" symbol from Section {@NumberOf textures}, +but without any following object. However, it's clunky to have to type +both @Code texture and {@Code "@Texture"}, so by special arrangement you +can omit the @Code "@Texture" symbol within the @Code "texture" option: +@ID @Code "texture { striped angle { 45d } scale { 2 } }" +The value of the @Code "texture" option may also be an expert's texture +as required by {@Code "@SetTexture"}. Incidentally, there is no +significance in our laying out all the options along one line. As always +in Lout, the end of a line and a space mean the same. We've done it this +way because we think it's the clearest way to lay out the @Code texture option. +@PP +Let's just summarize the painting and texturing possibilities for boxes. +A box has three components: its outline, its background, and its content +(what appears inside). You can actually set the colour and texture of +all three components independently of each other, with a little trouble: +@ID @OneRow @Code @Verbatim { +black @Colour striped @Texture angle { 45d } +@Box + paint { lightgrey } + linewidth { 2p } + texture { striped angle { 90d } } +darkgrey @Colour striped @Texture scale { 2 } 50p @Font ABC +} +produces +@CD { +black @Colour striped @Texture angle { 45d } +@Box + paint { lightgrey } + linewidth { 2p } + texture { striped angle { 90d } } +darkgrey @Colour striped @Texture scale { 2 } 50p @Font ABC +} +The outline colour and texture are the colour and texture from outside +the box; the background colour and texture are always determined by the +@Code paint and @Code texture options; and the colour and texture of +the contents are inherited from outside the box, but can be changed as +shown if desired. Notice what happens when two textures overstrike: the +lower one shows through the unpainted parts of the upper one. +@PP There are @Code "@CurveBox" and @Code "@ShadowBox" symbols that curvebox. @Index @Code "@CurveBox" shadowbox. @Index @Code "@ShadowBox" @@ -89,9 +148,10 @@ produce other kinds of boxes: A { @CurveBox { A curve box } } B { @ShadowBox { A shadow box } } } -These also have @Code "margin" and @Code "paint" options, and -@Code "@ShadowBox" has a @Code "shadow" option which determines -the thickness of the shadow (its default value is {@Code "0.2f"}). +These also have {@Code "margin"}, {@Code "linewidth"}, {@Code "paint"}, +and @Code "texture" options, and @Code "@ShadowBox" has a @Code "shadow" +option which determines the thickness of the shadow (its default value +is {@Code "0.2f"}). @PP Boxes are quite at home inside paragraphs, as @Box { a box }, @CurveBox { a curve box }, and @ShadowBox { a shadow box } @@ -116,8 +176,28 @@ across the whole page: "@OddPageTop { { My lovely document @LP @LocalWidthRule } @Right @PageNum }" } will draw a rule under just the three words. Of course, underlining using -the @Code "@Underline" symbol might be a better way to do this. Both -symbols have a @Code "linewidth" option which works like the one for -boxes described above. In particular, Lout leaves zero space for the -line, no matter how wide you make it. +the @Code "@Underline" symbol might be a better way to do this. +@PP +These two rule symbols are handled behind the scenes like the outlines +of boxes. Both symbols have a @Code "linewidth" option which works +like the one for boxes described above. In particular, Lout leaves +zero space for the line, no matter how wide you make it. And to change +the colour or texture of a rule, it must be enclosed in @Code "@Colour" +and @Code "@Texture" symbols: +@ID @Code "chessboard @Texture scale { 2 } @FullWidthRule linewidth { 8p }" +produces +@DP +chessboard @Texture scale { 2 } @FullWidthRule linewidth { 8p } +@DP +Notice how we have made sure that the rule is wide enough to +accommodate two rows of the chessboard texture. The author's +printer places a thin row of solid colour along the top of +this pattern. Logically it should not be there; it can be got +rid of by reducing the line width: +@ID @Code "chessboard @Texture scale { 2 } @FullWidthRule linewidth { 7.5p }" +produces +@DP +chessboard @Texture scale { 2 } @FullWidthRule linewidth { 7.5p } +@DP +We can only guess that the problem might be roundoff error. @End @Section diff --git a/doc/user/bgr_colo b/doc/user/bgr_colo index 7da8eeb..ca4f019 100644 --- a/doc/user/bgr_colo +++ b/doc/user/bgr_colo @@ -12,7 +12,7 @@ produces @ID grey @Colour { Hello, world } The @Code "@Colour" symbol will accept any of the following colours: @QD @HAdjust @Tab - vmargin { 0.7vx } + vmargin { 0.5vx } hmargin { 0.2c } @Fmta { @Col A @Colour @FilledBox ! @Col @Code A ! @Col ! @Col B @Colour @FilledBox ! @Col @Code B ! @Col ! @@ -32,11 +32,13 @@ The @Code "@Colour" symbol will accept any of the following colours: @Rowb A { black } B { white } } Monochrome output devices will render them as shades of grey. Colouring -something @Code white makes it invisible (unless it is being printed -on a coloured background), which is sometimes useful. +something @Code white makes it invisible (unless printed on a coloured +background), which is sometimes useful. See Appendix {@NumberOf morecolours} +to get many more colour names, using the @Code xrgb include file +and its @Code "@Xrgb" symbol. @PP In addition to the list of colours given above, there is a special -colour called {@Code nochange} which produces whatever colour you already +{@Code nochange} colour which produces whatever colour you already happen to be using; you can also use an empty object to ask for this. And you can get lots more colours by specifying them using numbers, like this: @ID @Code "{ rgb 0.5 0.5 1.0 } @Colour { Hello, world }" @@ -44,8 +46,7 @@ which means use red at intensity 0.5, green at intensity 0.5, and blue at intensity 1.0, producing @ID { rgb 0.5 0.5 1.0 } @Colour { Hello, world } In the strange world of colour coordinates, in which 0 is dark and 1 is -light, this is a light blue. You can also use the CMYK system if you -know what that is: +light, this is a light blue. You can also use the CMYK system: @ID @Code "{ cmyk 0.5 0.5 1.0 1.0 } @Colour { Hello, world }" produces @ID { cmyk 0.5 0.5 1.0 1.0 } @Colour { Hello, world } @@ -53,7 +54,7 @@ Wherever in this document it says that that you can use any colour from this section, it means any of the names above, or {@Code nochange}, or an object beginning with @Code "rgb" or @Code "cmyk" as shown. @PP -Whether or not the colours produced by @Code "@Colour" actually +Whether the colours produced by @Code "@Colour" actually correspond with the names depends on the output device; the same nominal colour can look quite different on screen and on paper. @End @Section diff --git a/doc/user/bgr_rota b/doc/user/bgr_rota index e4bcc72..4a35764 100644 --- a/doc/user/bgr_rota +++ b/doc/user/bgr_rota @@ -16,11 +16,11 @@ should be broken it is best to define the object's width explicitly, using the @Code "@Wide" symbol: wide @RawIndex { @Code "@Wide" } wide.rotate @SubIndex { with @Code "@Rotate" } -@ID @OneRow @Code { -"-90d @Rotate 4.5c @Wide {" -"Papal initiatives and influence from the crowning of" -"Charlemagne to the First Crusade" -"}" +@ID @OneRow @Code @Verbatim { +-90d @Rotate 4.5c @Wide { +Papal initiatives and influence from the crowning of +Charlemagne to the First Crusade +} } The result here is @ID { diff --git a/doc/user/bgr_text b/doc/user/bgr_text new file mode 100644 index 0000000..2c56022 --- /dev/null +++ b/doc/user/bgr_text @@ -0,0 +1,258 @@ +@Section + @Title { Textures } + @Tag { textures } +@Begin +@PP +The @Code "@Texture" symbol works in the same kind of way as @Code "@Font" +texture.sym @Index { @Code "@Texture" symbol } +and @Code "@Colour" do. It causes the object to its right to be printed +in a texture specified by the object to its +left: +@ID @Code "striped @Texture 50p @Font ABC" +produces +@FootNote { +If you can't see the result here, or if you can see it but without +texture, then the fault is probably in your PostScript viewer. +The PostScript viewer used by the author (a 1997 version of @I { gv }) +shows a blank space here and throughout this section wherever a +texture is supposed to appear, but when printed on his printer +the textures appear correctly. +} +@CD striped @Texture 50p @Font ABC +The object to the right of @Code "@Texture" may be arbitrary as usual. +@PP +# Textures are harder to specify than colours, and only a few +# texture names are widely used. +Only a handful of textures +are offered by the @Code "@Texture" symbol; but, as some +compensation, there are options which allow any texture to +be scaled, printed at any angle, +texture.sym @RawIndex { @Code "@Texture" symbol } +texture.sym.scale @SubIndex { @Code "scale" option } +texture.sym.angle @SubIndex { @Code "angle" option } +texture.sym.hshift @SubIndex { @Code "hshift" option } +texture.sym.vshift @SubIndex { @Code "vshift" option } +and shifted: +@ID @OneRow @Code @Verbatim { +striped @Texture + scale { 2 } + angle { 45d } + hshift { 1p } + vshift { 3p } +50p @Font ABC +} +produces +@CD striped @Texture + scale { 2 } + angle { 45d } + hshift { 1p } + vshift { 3p } +50p @Font ABC +with the texture scaled by a factor of 2, printed at an angle of 45 +degrees, and shifted one point horizontally and three points +vertically. The @Code scale option causes equal scaling in the +horizontal and vertical directions; there is also {@Code hscale} +which scales horizontally only, and @Code vscale which scales +vertically only. As you would expect, the default values of these +options are @Code 1 for the scaling options, {@Code 0d} for {@Code angle}, +and {@Code 0p} for {@Code hshift} and {@Code vshift}. +# @PP +# Stripes would rarely need to be shifted in practice, but some of the other +# textures described below can benefit from shifting. +@PP +Here is the list of all textures offered by the @Code "@Texture" +symbol, with the options specific to each kind of texture, their +default values, and sample default output. Remember, all textures +take the {@Code angle}, {@Code scale}, {@Code hscale}, {@Code vscale}, +{@Code hshift}, and {@Code vshift} options as well. +@ID @OneRow @Tbl + mv { 0.5v } + aformat { @Cell ml { 0i } A | @Cell @Code B | @Cell mr { 0i } @I lines @Break C } +{ + +@Rowa + ma { 0i } + A { @TextureSample solid } + B { +"solid @Texture" +solid."texture" @Index { @Code "solid" "texture" } +} + +@Rowa + A { @TextureSample striped } + B { +"striped @Texture" +" width { 1p }" +" gap { 1p }" +} + C { "" +The width of each stripe +The width of each gap between stripes +striped."texture" @Index { @Code "striped" "texture" } +} + +@Rowa + A { @TextureSample grid } + B { +"grid @Texture" +" width { 1p }" +" gap { 1p }" +} + C { "" +The width of each stripe +grid."texture" @Index { @Code "grid" "texture" } +The width of each gap between stripes +} + +@Rowa + A { @TextureSample dotted } + B { +"dotted @Texture" +" radius { 0.5p }" +" gap { 2p }" +} + C { "" +The radius of each dot (filled circle) +dotted."texture" @Index { @Code "dotted" "texture" } +The gap between the centres of adjacent dots +} + +@Rowa + A { @TextureSample chessboard } + B { +"chessboard @Texture" +" width { 2p }" +} + C { "" +The width of each square +chessboard."texture" @Index { @Code "chessboard" "texture" } +} + +@Rowa + A { @TextureSample brickwork } + B { +"brickwork @Texture" +" width { 6p }" +" height { 2p }" +" linewidth { 0.5p }" +} + C { "" +The width of each brick +The height of each brick +brickwork."texture" @Index { @Code "brickwork" "texture" } +The width of the brickwork lines +} + +@Rowa + A { @TextureSample honeycomb } + B { +"honeycomb @Texture" +" radius { 2p }" +" linewidth { 0.5p }" +} + C { "" +The radius of each hexagon +honeycomb."texture" @Index { @Code "honeycomb" "texture" } +The width of the lines +} + +@Rowa + A { @TextureSample triangular } + B { +"triangular @Texture" +" radius { 4p }" +" linewidth { 0.5p }" +} + C { "" +The side length of each triangle +triangular."texture" @Index { @Code "triangular" "texture" } +The width of the lines +} + +@Rowa + mb { 0i } + A { @TextureSample string } + B { +"string @Texture" +" width { 12p }" +" height { 12p }" +" font { Times-Roman }" +" size { 10p }" +" value { \"*\" }" +} + C { "" +The width at which the string repeats +The height at which the string repeats +The font used to display the string (see below) +The font size used to display the string +string."texture" @Index { @Code "string" "texture" } +The characters to be displayed +} + +} +This last example seems like a good one for experimenting with +the {@Code hshift} and {@Code vshift} options, so here goes: +texture.sym.hshift @SubIndex { @Code "hshift" option } +texture.sym.vshift @SubIndex { @Code "vshift" option } +@ID @OneRow @Tbl + mv { 0.5v } + aformat { @Cell ml { 0i } A | @Cell @Code B | @Cell mr { 0i } @I lines @Break C } +{ +@Rowa + mb { 0i } + A { +@Box margin { 0i } +string @Texture hshift { 4p } vshift { 4p } +@Box margin { 2.0f } paint { black } {} +} + B { +"string @Texture" +" hshift { 4p }" +" vshift { 4p }" +} +} +You have to find the right amount of shift by experiment, especially +when combined with rotation and scaling. We recommend sticking to the +{@Code p} (points), {@Code m} (ems), {@Code c} (centimetres), and +{@Code i} (inches) units of measurement when giving length options +to {@Code "@Texture"} symbols. +@PP +Care is needed when using the @Code font and @Code value options +of {@Code "string @Texture"}, since these options are passed straight +through to the PostScript output without checking. The @Code "font" +option takes a PostScript name for a font, not a Lout name. Typical +PostScript font names, virtually certain to work, are {@Code Times-Roman} +and {@Code Helvetica}. Since Lout takes no special steps to make sure +that the font you ask for is available, you should restrict your font +choices to fonts known to be in use elsewhere on the same page, or +known to be always loaded in your viewing device. The @Code "value" +option must be a sequence of characters from the nominated font. +Although the value does not have to be quoted as shown, we recommend +it as a reminder of how limited the choices are here. Also, spaces in +your value will work better between quotes, and to make parentheses -- +@Code "(" and @Code ")" -- come out correctly they must be enclosed in +quotes and preceded by a backslash character, which you get as usual by +writing @I two backslash characters. For example, {@Code "\"\\\\(\""} +will produce one left parenthesis. +@PP +Notice that {@Code "solid @Texture"} produces solid colour, +or in other words no texture: +@ID @Code @Verbatim { +striped @Texture angle { 45d } +@Box linewidth { 2p } solid @Texture 50p @Font WARNING! +} +produces +@CD { +striped @Texture angle { 45d } +@Box linewidth { 2p } solid @Texture 50p @Font WARNING! +} +As shown, {@Code "solid @Texture"} is useful for switching back to +normal printing within a textured region. In this example, without +it the letters would have been striped as well. +@PP +Expert users can also make the object to the left of @Code "@Texture" +be anything that is acceptable to the left of the expert's symbol +{@Code "@SetTexture"}, allowing people who want to do some serious +work in PostScript to get arbitrary textures. Consult the Expert's +Guide for more about this. +@End @Section diff --git a/doc/user/dia b/doc/user/dia index 9b0f8f9..5e7e966 100644 --- a/doc/user/dia +++ b/doc/user/dia @@ -4,7 +4,8 @@ @Begin @LP This chapter describes how to use the @@Diag symbol -diag. @Index { @@Diag } +diagrams. @RawIndex { diagrams } +diag.diagrams @Index { @Code "@Diag" (diagrams) } @FootNote { Starting with Version 3.18 of Lout, the @@Diag symbol was enhanced with the {@Code "@ANode"}, {@Code "@BNode"}, and {@Code "@CNode"} symbols diff --git a/doc/user/dia_defi b/doc/user/dia_defi index ed27887..200ce8e 100644 --- a/doc/user/dia_defi +++ b/doc/user/dia_defi @@ -4,6 +4,10 @@ @Begin @PP @@Diag permits you to create your own node outlines and link paths, by +diagrams. @RawIndex { diagrams } +diagrams.definitions @SubIndex { definitions } +definitions. @RawIndex { definitions } +definitions.use.with.diagrams @SubIndex { use with diagrams } giving non-standard values to the @Code outline and @Code path options. This section shows how to do this for very simple shapes only; the following section introduces the large repertoire of geometrical @@ -34,14 +38,14 @@ corner, and @Eq { (xsize, ysize) } at the top right: The value of the @Code outline option is a sequence of points defined in this coordinate system: @ID { -@Code { -"@Node" -" outline {" -" 0 0" -" xsize 0" -" 0 ysize" -" 0 0" -" }" +@Code @Verbatim { +@Node + outline { + 0 0 + xsize 0 + 0 ysize + 0 0 + } } ||7ct @Diag { @@ -64,20 +68,21 @@ As shown, the resulting outline is created by joining each point to the next with a straight line. It is conventional to proceed anticlockwise around the outline, but you may start anywhere. @PP -The {@Code paint}, {@Code outlinestyle}, {@Code outlinedashlength}, -and {@Code outlinewidth} options of @Code "@Node" work for user-defined -outlines exactly as they do for the standard ones: +The {@Code paint}, {@Code texture}, {@Code outlinestyle}, +{@Code outlinedashlength}, and {@Code outlinewidth} options of +@Code "@Node" work for user-defined outlines exactly as they do +for the standard ones: @ID { -@Code { -"@Node" -" outline {" -" 0 0" -" xsize 0" -" 0 ysize" -" 0 0" -" }" -" paint { lightgrey }" -" outlinestyle { solid dashed }" +@Code @Verbatim { +@Node + outline { + 0 0 + xsize 0 + 0 ysize + 0 0 + } + paint { lightgrey } + outlinestyle { solid dashed } } ||7ct @Diag { @@ -104,15 +109,15 @@ Two points may also be separated by {@Code "["}{@I point}{@Code "]"}, where @I point stands for any point. This causes the two points to be joined by an arc whose centre is at the given point: @ID { -@Code { -"@Node" -" outline {" -" 0 0" -" ysize 0" -" [ 0 0 ]" -" 0 ysize" -" 0 0" -" }" +@Code @Verbatim { +@Node + outline { + 0 0 + ysize 0 + [ 0 0 ] + 0 ysize + 0 0 + } } ||7ct @Diag { @@ -181,13 +186,13 @@ neatly onto Bezier curves as they do onto lines and arcs. Tags (Section {@NumberOf dia_tags}) may be assigned to points within the outline option, like this: @ID { -@Code { -"@Node" -" outline {" -" LR:: { xsize 0 }" -" UL:: { 0 ysize }" -" 0 0 LR UL 0 0" -" }" +@Code @Verbatim { +@Node + outline { + LR:: { xsize 0 } + UL:: { 0 ysize } + 0 0 LR UL 0 0 + } } ||7ct @Diag { @@ -226,15 +231,15 @@ example) and in the angle step if the label is aligned, perpendicular, parallel, or antiparallel. A direction is given using the @Code ":<" symbol within an outline: @ID { -@Code { -"@Node" -" outline {" -" LR:: { xsize 0 }" -" LR:< 0d" -" UL:: { 0 ysize }" -" UL:< 270d" -" 0 0 LR UL 0 0" -" }" +@Code @Verbatim { +@Node + outline { + LR:: { xsize 0 } + LR:< 0d + UL:: { 0 ysize } + UL:< 270d + 0 0 LR UL 0 0 + } } ||7ct @Diag { @@ -271,13 +276,13 @@ Within a link path, the symbols @Code from and @Code to denote the values of the link's @Code from and @Code to options, and these form the basis of constructing the link path: @ID { -@Code { -"@Link" -" path {" -" FROM:: from" -" TO:: to" -" FROM TO" -" }" +@Code @Verbatim { +@Link + path { + FROM:: from + TO:: to + FROM TO + } } ||7ct { @@ -309,33 +314,33 @@ Once the outline or path is complete, unless it is really a one-off production the best thing to do with it is to add it to your extend. @Index { @Code extend keyword } @Code "mydefs" file in the following form: -@ID @OneRow @Code { -"extend @DiagSetup @Diag" -"macro @MyNode {" -" @Node" -" outline {" -" LR:: { xsize 0 }" -" LR:< 0d" -" UL:: { 0 ysize }" -" UL:< 270d" -" 0 0 LR UL 0 0" -" }" -"}" +@ID @OneRow @Code @Verbatim { +extend @DiagSetup @Diag +macro @MyNode { + @Node + outline { + LR:: { xsize 0 } + LR:< 0d + UL:: { 0 ysize } + UL:< 270d + 0 0 LR UL 0 0 + } +} } This says that we are `extending' the @@Diag symbol by adding a new symbol, {@Code "@MyNode"}, which stands for what follows it between braces. @Code "@MyNode" will then behave exactly like @Code "@Circle" and the other standard node symbols. The same pattern works for links: -@ID @OneRow @Code { -"extend @DiagSetup @Diag" -"macro @MyLink {" -" @Link" -" path {" -" FROM:: from" -" TO:: to" -" FROM TO" -" }" -"}" +@ID @OneRow @Code @Verbatim { +extend @DiagSetup @Diag +macro @MyLink { + @Link + path { + FROM:: from + TO:: to + FROM TO + } +} } If it is worth the effort to construct a new outline or link path, it is worth packaging it like this and thinking up a good name for it, @@ -343,15 +348,15 @@ for then it will be available, easily, forever. @PP This same approach is also useful to define common combinations of options, even when there is no new outline or path: -@ID @OneRow @Code { -"extend @DiagSetup @Diag" -"macro @BigOctagon {" -" @Polygon" -" sides { 8 }" -" hsize { 5c }" -" vsize { 5c }" -" font { Bold }" -"}" +@ID @OneRow @Code @Verbatim { +extend @DiagSetup @Diag +macro @BigOctagon { + @Polygon + sides { 8 } + hsize { 5c } + vsize { 5c } + font { Bold } +} } Such definitions are very useful if the combinations occur frequently. Any options not mentioned have their usual default values, diff --git a/doc/user/dia_erro b/doc/user/dia_erro index a04aae0..95b1d4d 100644 --- a/doc/user/dia_erro +++ b/doc/user/dia_erro @@ -8,6 +8,8 @@ any PostScript device. However, some of the options of {@Code "@Diag"}'s symbols are passed through Lout to the output file without checking, including anything containing @Code "@Diag" lengths, angles, points, and tags. Any errors in these options will not be detected until the file +errors. @RawIndex { errors } +errors.in.diagrams @SubIndex { in diagrams } is printed. @PP The most likely errors are {@I syntax @I errors}, as in @@ -27,6 +29,10 @@ have been printed next. If you see {@Code VMerror} in an error message, it means that the printer vmerror. @Index { @Code VMerror PostScript error } is running out of memory. In that case, one thing you can try is +diagrams. @RawIndex { diagrams } +diagrams.save @SubIndex { @Code "save" option } +save. @RawIndex { @Code "save" option } +save.in.diagrams @SubIndex { in diagrams } @ID @Code { "@Diag" " save { yes }" diff --git a/doc/user/dia_geom b/doc/user/dia_geom index bfc9c02..a3c4e86 100644 --- a/doc/user/dia_geom +++ b/doc/user/dia_geom @@ -4,6 +4,9 @@ @Begin @PP @@Diag has many options whose values contain lengths, angles, and +diagrams. @RawIndex { diagrams } +diagrams.geometry @SubIndex { geometry } +geometry.diagrams @Index { geometry in diagrams } points. Options such as @Code margin and {@Code vsize}, which affect the size or appearance of the base of a node, may contain only the kinds of lengths described in Section {@NumberOf objects}; but in all other cases @@ -46,23 +49,23 @@ These remarks on safety do not apply within the @Code outline option of specified. Vector operations, with the aid of a few well-chosen tags, can greatly simplify the production of outlines: @ID { -@Code { -"@Node" -" outline {" -" SB:: {0 ysize} ** 0.4" -" ST:: {0 ysize} ** 0.6" -" HB:: {xsize 0} ** 0.7" -" SB" -" SB ++ HB" -" HB" -" xsize ysize * 0.5" -" HB ++ {0 ysize}" -" HB ++ ST" -" ST" -" SB" -" }" -" paint { grey }" -"{ 6c @Wide 2c @High }" +@Code @Verbatim { +@Node + outline { + SB:: {0 ysize} ** 0.4 + ST:: {0 ysize} ** 0.6 + HB:: {xsize 0} ** 0.7 + SB + SB ++ HB + HB + xsize ysize * 0.5 + HB ++ {0 ysize} + HB ++ ST + ST + SB + } + paint { grey } +{ 6c @Wide 2c @High } } ||7ct @Diag { @@ -96,8 +99,6 @@ can be a length or angle, or even a sequence of values. It is permissible to change the value assigned to a tag by reassigning. @PP Two very useful symbols, {@Code angleto} and {@Code atangle}, bring -angleto. @Index { @Code angleto symbol in @Code "@Diag" } -atangle. @Index { @Code atangle symbol in @Code "@Diag" } angles into the algebra. The {@Code angleto} symbol finds the angle from one point to another. For example, @ID @Code "SB angleto ST" @@ -109,21 +110,20 @@ is the point {@Code "1f 1f"}, and is the point @Code 2f from {@Code "B@NE"} to its northwest. @PP There is a @Code prev symbol, used only within {@Code outline} and -prev. @Index { @Code prev symbol in @Code "@Diag" } {@Code path}, which returns the previous point on the outline or path, ignoring points within {@Code "[]"}. It makes relative movements very easy: @ID { -@Code { -" outline {" -" 0 0" -" { 2c atangle 30d }" -" prev ++ { 2c atangle 90d }" -" prev ++ { 2c atangle 150d }" -" prev ++ { 2c atangle 210d }" -" prev ++ { 2c atangle 270d }" -" 0 0" -" }" +@Code @Verbatim { + outline { + 0 0 + { 2c atangle 30d } + prev ++ { 2c atangle 90d } + prev ++ { 2c atangle 150d } + prev ++ { 2c atangle 210d } + prev ++ { 2c atangle 270d } + 0 0 + } } ||7ct @Diag { ||2.5c @@ -145,8 +145,6 @@ shrink with the base as it should. Such outlines, while tempting, are always regretted later. @PP There are {@Code xcoord} and {@Code ycoord} symbols for finding the -xcoord. @Index { @Code xcoord symbol in @Code "@Diag" } -ycoord. @Index { @Code ycoord symbol in @Code "@Diag" } @I x and @I y coordinates of a point: @ID @Code { "{xcoord P1} min {xcoord P2}" "{ycoord P1} max {ycoord P2}" @@ -168,9 +166,9 @@ The solution is based on a symbol called {@Code boundaryatangle}, whose preceding object should be either a point or else the tag of a node with one of the standard shapes, and whose following object is an angle: -@ID @Code { -"{ xsize ysize*0.5 } boundaryatangle 45d" -"A boundaryatangle 45d" +@ID @Code @Verbatim { +{ xsize ysize*0.5 } boundaryatangle 45d +A boundaryatangle 45d } In the first case the result is the point, regardless of the angle. In the second case, the result is the point on the boundary of @@ -191,13 +189,13 @@ either node tags or points. In either case a suitable direction for the line to take is @ID @Code "from??CTR angleto to??CTR" and so the desired path is -@ID @Code { -"path {" -" FROM:: from boundaryatangle { from??CTR angleto to??CTR }" -" TO:: to boundaryatangle { to??CTR angleto from??CTR }" -" FROM" -" TO" -"}" +@ID @Code @Verbatim { +path { + FROM:: from boundaryatangle { from??CTR angleto to??CTR } + TO:: to boundaryatangle { to??CTR angleto from??CTR } + FROM + TO +} } The first line defines point @Code FROM to be on the boundary of @Code from at the appropriate angle, if @Code "from" is a node tag; diff --git a/doc/user/dia_intr b/doc/user/dia_intr index 4f1ee40..02ab5b2 100644 --- a/doc/user/dia_intr +++ b/doc/user/dia_intr @@ -48,6 +48,12 @@ Most uses of @@Diag contain a @I { nodes part } and a @I { links part }: @Code "}" } This reflects @@Diag's view of the world as consisting of {@I nodes} +diagrams. @RawIndex { diagrams } +diagrams.nodespart @SubIndex { nodes part } +nodespart.diagrams @Index { nodes part in diagrams } +diagrams. @RawIndex { diagrams } +diagrams.linkspart @SubIndex { links part } +linkspart.diagrams @Index { links part in diagrams } (circles, squares, and so on), which have to be put in their right places and then joined with @I links (lines, arrows). The technical meaning of the {@Code "//"} symbol does not concern us here; it @@ -75,6 +81,9 @@ Node symbols like @Code "@Ellipse" and @Code "@Square" follow a familiar pattern: they consume the following object, which may be arbitrary, draw a shape around it, and give back the resulting object. To insert links, the nodes must first be given names, called {@I tags}, using the @Code "::" symbol: +diagrams. @RawIndex { diagrams } +diagrams.tags @SubIndex { tags ({@Code "::"}) } +tags.diagrams @Index { tags ({@Code "::"}) in diagrams } @ID @OneRow @Code { "A:: @Ellipse { Hello, world }" "@DP" @@ -85,14 +94,14 @@ Then a link from @Code A to @Code B may be added to the links part: @Fmta { @Col 7c @Wide A ! @Col B } { @Rowa - A { @Code { -"@Diag {" -" A:: @Ellipse { Hello, world }" -" @DP" -" B:: @Square @I x" -" //" -" @Link from { A } to { B }" -"}" + A { @Code @Verbatim { +@Diag { + A:: @Ellipse { Hello, world } + @DP + B:: @Square @I x + // + @Link from { A } to { B } +} } } B { @Diag { A:: @Ellipse { Hello, world } diff --git a/doc/user/dia_labe b/doc/user/dia_labe index c449367..80b5615 100644 --- a/doc/user/dia_labe +++ b/doc/user/dia_labe @@ -4,6 +4,10 @@ @Begin @PP Diagrams often contain small @I labels adjacent to their nodes and links: +diagrams. @RawIndex { diagrams } +diagrams.labels @SubIndex { labels } +labels. @RawIndex { labels } +labels.in.diagrams @SubIndex { in diagrams } @CD @Diag nodelabelformat { @I @Body } { @@ -23,20 +27,27 @@ Diagrams often contain small @I labels adjacent to their nodes and links: @Arrow from { B } to { C } ylabel { 20 } } Each node may have up to four labels, called {@Code alabel}, {@Code blabel}, -label. @Index { label options in @Code "@Diag" } -alabel. @Index { @Code alabel option in @Code "@Diag" } -blabel. @Index { @Code blabel option in @Code "@Diag" } -clabel. @Index { @Code clabel option in @Code "@Diag" } -dlabel. @Index { @Code dlabel option in @Code "@Diag" } +diagrams. @RawIndex { diagrams } +diagrams.alabel @SubIndex { @Code "alabel" option } +alabel.diagrams @Index { @Code "alabel" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.blabel @SubIndex { @Code "blabel" option } +blabel.diagrams @Index { @Code "blabel" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.clabel @SubIndex { @Code "clabel" option } +clabel.diagrams @Index { @Code "clabel" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.dlabel @SubIndex { @Code "dlabel" option } +dlabel.diagrams @Index { @Code "dlabel" option (diagrams) } {@Code clabel}, and {@Code dlabel}: @ID { -@Code { -"@Ellipse" -" alabel { a }" -" blabel { b }" -" clabel { c }" -" dlabel { d }" -"{ Hello, world }" +@Code @Verbatim { +@Ellipse + alabel { a } + blabel { b } + clabel { c } + dlabel { d } +{ Hello, world } } ||7ct @VContract @Diag { @@ -49,14 +60,29 @@ dlabel. @Index { @Code dlabel option in @Code "@Diag" } } } Links also have labels, five in fact: +diagrams. @RawIndex { diagrams } +diagrams.fromlabel @SubIndex { @Code "fromlabel" option } +fromlabel.diagrams @Index { @Code "fromlabel" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.xlabel @SubIndex { @Code "xlabel" option } +xlabel.diagrams @Index { @Code "xlabel" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.ylabel @SubIndex { @Code "ylabel" option } +ylabel.diagrams @Index { @Code "ylabel" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.zlabel @SubIndex { @Code "zlabel" option } +zlabel.diagrams @Index { @Code "zlabel" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.tolabel @SubIndex { @Code "tolabel" option } +tolabel.diagrams @Index { @Code "tolabel" option (diagrams) } @ID { -@Code { -"@Link" -" fromlabel { f }" -" xlabel { x }" -" ylabel { y }" -" zlabel { z }" -" tolabel { t }" +@Code @Verbatim { +@Link + fromlabel { f } + xlabel { x } + ylabel { y } + zlabel { z } + tolabel { t } } ||7ct @VContract @Diag { @@ -77,9 +103,9 @@ over the endpoints of the link, and {@Code fromlabel} is by default printed at a funny angle, because these labels are the means of attaching arrowheads to links: @ID { -@Code { -"@Link" -" tolabel { @SolidArrowHead }" +@Code @Verbatim { +@Link + tolabel { @SolidArrowHead } } ||7ct @VContract @Diag { @@ -109,14 +135,22 @@ labels. These are described below mainly for {@Code alabel}, but there are corresponding options for all nine labels. @PP The {@Code alabelfont} and {@Code alabelbreak} options determine the +diagrams. @RawIndex { diagrams } +diagrams.labelfont @SubIndex { @Code "labelfont" options } +labelfont. @RawIndex { @Code "labelfont" options } +labelfont.in.diagrams @SubIndex { in diagrams } +diagrams. @RawIndex { diagrams } +diagrams.labelbreak @SubIndex { @Code "labelbreak" options } +labelbreak. @RawIndex { @Code "labelbreak" options } +labelbreak.in.diagrams @SubIndex { in diagrams } font and paragraph breaking style of the label: @ID { -@Code { -"@Ellipse" -" alabel { a }" -" alabelfont { -2p }" -" alabelbreak { ragged nohyphen }" -"{ Hello, world }" +@Code @Verbatim { +@Ellipse + alabel { a } + alabelfont { -2p } + alabelbreak { ragged nohyphen } +{ Hello, world } } ||7ct @VContract @Diag { @@ -130,13 +164,17 @@ font and paragraph breaking style of the label: This example shows the default values of these two options; @Code "-2p" explains why the labels in earlier examples were printed in a smaller font size. There is also an {@Code alabelformat} option which allows +diagrams. @RawIndex { diagrams } +diagrams.labelformat @SubIndex { @Code "labelformat" options } +labelformat. @RawIndex { @Code "labelformat" options } +labelformat.in.diagrams @SubIndex { in diagrams } for more radical changes in appearance: @ID { -@Code { -"@Ellipse" -" alabel { a }" -" alabelformat { @Box @I @Body }" -"{ Hello, world }" +@Code @Verbatim { +@Ellipse + alabel { a } + alabelformat { @Box @I @Body } +{ Hello, world } } ||7ct @Diag { @@ -155,13 +193,13 @@ Nodes also have {@Code nodelabelfont}, {@Code nodelabelbreak}, and {@Code nodelabelformat} options which work in the same way but affect all of the node labels, not just one: @ID { -@Code { -"@Ellipse" -" nodelabelformat" -" { @Box @I @Body }" -" alabel { a }" -" blabel { b }" -"{ Hello, world }" +@Code @Verbatim { +@Ellipse + nodelabelformat + { @Box @I @Body } + alabel { a } + blabel { b } +{ Hello, world } } ||7ct @Diag { @@ -179,19 +217,19 @@ Links similarly have {@Code linklabelfont}, {@Code linklabelbreak}, and results that people do not expect.) The @Code "@Diag" symbol also has these options, in the usual way, and they are extremely useful there: @ID { -@Code { -"@Diag" -" nodelabelfont { Slope -2p }" -" linklabelformat { \"/\"@Body\"/\" }" -" hsize { 1.8c }" -"{" -" A:: @Ellipse alabel { a } { OK }" -" @DP" -" @DP" -" B:: @Ellipse alabel { b } { FAULT }" -" //" -" @Arrow from { A } to { B } ylabel { sig }" -"}" +@Code @Verbatim { +@Diag + nodelabelfont { Slope -2p } + linklabelformat { \/\@Body\/\ } + hsize { 1.8c } +{ + A:: @Ellipse alabel { a } { OK } + @DP + @DP + B:: @Ellipse alabel { b } { FAULT } + // + @Arrow from { A } to { B } ylabel { sig } +} } ||7ct @VContract @Diag @@ -225,15 +263,18 @@ Each label inhabits its own characteristic region of the node or link: {@Code alabel} in the north-east corner of the node, {@Code ylabel} halfway along the link, and so on. This general location of the label is defined by the {@Code alabelpos} option. Here +diagrams. @RawIndex { diagrams } +diagrams.labelpos @SubIndex { @Code "labelpos" options } +labelpos.diagrams @Index { @Code "labelpos" options (diagrams) } are the default values for all nine labels: @IL @LI { -@Code { -"@Node" -" alabelpos { NE }" -" blabelpos { NW }" -" clabelpos { SW }" -" dlabelpos { SE }" +@Code @Verbatim { +@Node + alabelpos { NE } + blabelpos { NW } + clabelpos { SW } + dlabelpos { SE } } ||7ct @VContract @Diag { @@ -242,13 +283,13 @@ are the default values for all nine labels: } } @LI { -@Code { -"@Link" -" fromlabelpos { FROM }" -" xlabelpos { LFROM }" -" ylabelpos { LMID }" -" zlabelpos { LTO }" -" tolabelpos { TO }" +@Code @Verbatim { +@Link + fromlabelpos { FROM } + xlabelpos { LFROM } + ylabelpos { LMID } + zlabelpos { LTO } + tolabelpos { TO } } ||7ct @VContract @Diag { @@ -268,15 +309,21 @@ node by setting this option in the @Code "@Diag" symbol, as was done for the formatting options above. @PP In a similar vein, there is an @Code { xindent } option which controls how +diagrams. @RawIndex { diagrams } +diagrams.xindent @SubIndex { @Code "xindent" option } +xindent.diagrams @Index { @Code "xindent" option (diagrams) } far from the start of the link the @Code "LFROM" tag, and hence the {@Code xlabel}, will appear. A similar option, @Code { zindent }, determines +diagrams. @RawIndex { diagrams } +diagrams.zindent @SubIndex { @Code "zindent" option } +zindent.diagrams @Index { @Code "zindent" option (diagrams) } how far from the end of the link the @Code "LTO" tag and hence the {@Code zlabel} will appear: @ID { -@Code { -"@Link" -" xindent { 1f }" -" zindent { 2f }" +@Code @Verbatim { +@Link + xindent { 1f } + zindent { 2f } } ||7ct @VContract @Diag { @@ -293,6 +340,9 @@ how far from the end of the link the @Code "LTO" tag and hence the Both options have default value {@Code 0.8f}. @PP The @Code alabelangle option determines the angle at which the label is +diagrams. @RawIndex { diagrams } +diagrams.labelangle @SubIndex { @Code "labelangle" options } +labelangle.diagrams @Index { @Code "labelangle" options (diagrams) } printed: @ID @Tab @Fmta { @Col @Code A ! @Col B } @@ -308,6 +358,9 @@ printed: B { Perpendicular to the outline or link path } } The @Code "alabelprox" option determines where in the proximity of +diagrams. @RawIndex { diagrams } +diagrams.labelprox @SubIndex { @Code "labelprox" options } +labelprox.diagrams @Index { @Code "labelprox" options (diagrams) } @Code alabelpos the label is printed: @ID @Tab @Fmta { @Col @Code A ! @Col B } @@ -334,14 +387,18 @@ going from @Code from to @Code to } going from @Code from to @Code to (the default for node labels) } } The {@Code alabelmargin} option adds a margin around all four sides of +diagrams. @RawIndex { diagrams } +diagrams.labelmargin @SubIndex { @Code "labelmargin" options } +labelmargin. @RawIndex { @Code "labelmargin" options } +labelmargin.in.diagrams @SubIndex { in diagrams } the label, thereby moving it away from {@Code alabelpos} irrespective of which direction it happens to lie in: @ID { -@Code { -"@Ellipse" -" alabel { a }" -" alabelmargin { 0f }" -"{ Hello, world }" +@Code @Verbatim { +@Ellipse + alabel { a } + alabelmargin { 0f } +{ Hello, world } } ||7ct @VContract @Diag { @@ -371,7 +428,7 @@ the one closest to {@Code 0d}. @PP The @Code alabelprox option may be {@Code N}, {@Code S}, {@Code E}, {@Code W}, {@Code NE}, {@Code SE}, {@Code NW}, -{@Code SW}, or {@Code CTR}: +{@Code SW}, {@Code NNW}, {@Code NNE}, {@Code SSW}, {@Code SSE}, or {@Code CTR}: @CD @Diag { //1f @ShowTags @Box margin { 0.5c } { 24p @Font grey @Colour @I label } @@ -400,6 +457,9 @@ through {@Code alabelpos} at the angle of {@Code alabelpos}. The corner or side midpoint slides up or down this line to the point which minimises the distance from {@Code alabelpos} to the centre of the label. Only @Code ylabelctr has @Code "yes" for its default value; the +diagrams. @RawIndex { diagrams } +diagrams.labelctr @SubIndex { @Code "labelctr" options } +labelctr.diagrams @Index { @Code "labelctr" options (diagrams) } @Code y label often looks better centred when this adjustment is made, particularly on lines with shallow but non-zero slope: @CD @Tab @@ -426,6 +486,10 @@ since it is then the centre of the label which is centred on the link, rather than one of its corners. @PP Finally, when all else fails there is an {@Code alabeladjust} option +diagrams. @RawIndex { diagrams } +diagrams.labeladjust @SubIndex { @Code "labeladjust" options } +labeladjust. @RawIndex { @Code "labeladjust" options } +labeladjust.in.diagrams @SubIndex { in diagrams } which translates the label by an arbitrary amount: @ID @Code "alabeladjust { -0.5c 1.5c }" causes the label to appear 0.5 centimetres to the left of and 1.5 centimetres diff --git a/doc/user/dia_link b/doc/user/dia_link index b71f9d5..f3a80fb 100644 --- a/doc/user/dia_link +++ b/doc/user/dia_link @@ -4,15 +4,26 @@ @Begin @PP @Code "@Diag" has one basic symbol for creating links, called -link. @Index { @Code "@Link" symbol from @Code "@Diag" } +diagrams. @RawIndex { diagrams } +diagrams.link @SubIndex { @Code "@Link" symbol } +link.diagrams @Index { @Code "@Link" symbol (diagrams) } {@Code "@Link"}. It draws a link between two points or nodes given by {@Code from} and {@Code to} options, along a path +diagrams. @RawIndex { diagrams } +diagrams.from @SubIndex { @Code "from" option } +from.diagrams @Index { @Code "from" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.to @SubIndex { @Code "to" option } +to.diagrams @Index { @Code "to" option (diagrams) } given by a {@Code path} option: -@ID @Code { -"@Link" -" path { ... }" -" from { ... }" -" to { ... }" +diagrams. @RawIndex { diagrams } +diagrams.path @SubIndex { @Code "path" option } +path.diagrams @Index { @Code "path" option (diagrams) } +@ID @Code @Verbatim { +@Link + path { ... } + from { ... } + to { ... } } Unlike {@Code "@Node"}, {@Code "@Link"} has no following object. @PP @@ -72,6 +83,13 @@ relative to each other, except that no promise of a sensible result is made for two nodes very close together. @PP @Code "@Link" has two options, @Code bias and {@Code radius}, that may be +diagrams. @RawIndex { diagrams } +diagrams.bias @SubIndex { @Code "bias" option } +bias.diagrams @Index { @Code "bias" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.radius @SubIndex { @Code "radius" option } +radius. @RawIndex { @Code "radius" option } +radius.in.diagrams @SubIndex { in diagrams } used to fine-tune the path. The @Code "bias" option determines the maximum distance that a curve is permitted to stray: @CD @Tab @@ -108,10 +126,10 @@ a semicircle at the right in an {@Code rvlcurve}. Lout has no idea where the path is wandering, and cannot take it into account when placing a diagram on the page: @ID { -@Code { -"@Link" -" path { ccurve }" -" bias { 2c }" +@Code @Verbatim { +@Link + path { ccurve } + bias { 2c } } ||7ct @Diag vstrut { no } { @@ -130,6 +148,15 @@ in the setup file, where they apply to every link in every diagram of the document, unless overridden. @PP There are {@Code pathstyle}, {@Code pathdashlength} and {@Code pathwidth} +diagrams. @RawIndex { diagrams } +diagrams.pathstyle @SubIndex { @Code "pathstyle" option } +pathstyle.diagrams @Index { @Code "pathstyle" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.pathdashlength @SubIndex { @Code "pathdashlength" option } +pathdashlength.diagrams @Index { @Code "pathdashlength" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.pathwidth @SubIndex { @Code "pathwidth" option } +pathwidth.diagrams @Index { @Code "pathwidth" option (diagrams) } options which affect the appearance of the path in the same way as the {@Code outlinestyle}, {@Code outlinedashlength} and {@Code outlinewidth} options of {@Code "@Node"} affect the outline. When {@Code pathstyle} @@ -137,15 +164,20 @@ contains just one value (as opposed to a sequence of values) @Code "@Diag" tries to divide the path into fewer segments than it would otherwise, to make dashed and dotted paths look as good as possible. There is also a {@Code pathgap} option which affects only @Code doubleline paths; it +diagrams. @RawIndex { diagrams } +diagrams.pathgap @SubIndex { @Code "pathgap" option } +pathgap.diagrams @Index { @Code "pathgap" option (diagrams) } determines the gap between the centres of the two lines. @PP The @Code "@Link" symbol has an @Code arrow option, which adds an -arrow. @Index { arrows } +diagrams. @RawIndex { diagrams } +diagrams.arrow.opt @SubIndex { @Code "arrow" option } +arrow.opt.diagrams @Index { @Code "arrow" option (diagrams) } arrowhead to the end of the link: @ID { -@Code { -"@Link" -" arrow { yes }" +@Code @Verbatim { +@Link + arrow { yes } } ||7ct @Diag { @@ -160,9 +192,9 @@ arrowhead to the end of the link: Its value may be {@Code no} (the default), {@Code yes}, {@Code forward} (which is the same as {@Code yes}), {@Code back}, or {@Code both}: @ID { -@Code { -"@Link" -" arrow { both }" +@Code @Verbatim { +@Link + arrow { both } } ||7ct @Diag { @@ -177,17 +209,26 @@ Its value may be {@Code no} (the default), {@Code yes}, {@Code forward} @Code "@Link" has three options for controlling the appearance of arrowheads: {@Code arrowstyle}, {@Code arrowwidth}, and {@Code arrowlength}. Although every link symbol has these options, for +diagrams. @RawIndex { diagrams } +diagrams.arrowstyle @SubIndex { @Code "arrowstyle" option } +arrowstyle.diagrams @Index { @Code "arrowstyle" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.arrowwidth @SubIndex { @Code "arrowwidth" option } +arrowwidth.diagrams @Index { @Code "arrowwidth" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.arrowlength @SubIndex { @Code "arrowlength" option } +arrowlength.diagrams @Index { @Code "arrowlength" option (diagrams) } consistency it is almost always better to set the corresponding options to the @Code "@Diag" symbol, which applies them to every arrow in the diagram: -@ID @Code { -"@Diag" -" arrowstyle { solid }" -" arrowwidth { 0.3f }" -" arrowlength { 0.5f }" -"{" -" ..." -"}" +@ID @Code @Verbatim { +@Diag + arrowstyle { solid } + arrowwidth { 0.3f } + arrowlength { 0.5f } +{ + ... +} } This shows the default values: a solid arrowhead like the ones above, @Code "0.3f" wide (across) and @Code "0.5f" long. The @Code "arrowwidth" @@ -245,15 +286,55 @@ base to its point, and hence can and does ensure that the link path does not overstrike and thicken the point of the arrow. } @PP -It is possible to place an arbitrary object at the beginning or +Corresponding with {@Code arrowstyle}, {@Code arrowwidth}, and +{@Code arrowlength}, there are {@Code backarrowstyle}, +{@Code backarrowwidth}, and {@Code backarrowlength} options which +diagrams. @RawIndex { diagrams } +diagrams.backarrowstyle @SubIndex { @Code "backarrowstyle" option } +backarrowstyle.diagrams @Index { @Code "backarrowstyle" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.backarrowwidth @SubIndex { @Code "backarrowwidth" option } +backarrowwidth.diagrams @Index { @Code "backarrowwidth" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.backarrowlength @SubIndex { @Code "backarrowlength" option } +backarrowlength.diagrams @Index { @Code "backarrowlength" option (diagrams) } +determine the style and size of the back arrow; it doesn't have +to be the same style or size as the forward arrow: +@ID { +@Code @Verbatim { +@Link + arrow { both } + backarrowstyle { circle } +} +||7ct +@Diag { +1c @High 3c @Wide +// +@Link + from { 0,0 } + to { 1,1 } + arrow { both } + backarrowstyle { circle } +} +} +It is also possible to place an arbitrary object at the beginning or end of a link, using the @Code "fromlabel" and @Code "tolabel" options of Section {@NumberOf dia_labe}. @PP To save time in common cases, @Code "@Diag" provides link symbols, each of which is just @Code "@Link" with one of the standard paths already set: {@Code "@Line"}, {@Code "@Curve"}, {@Code "@CCurve"}, +diagrams. @RawIndex { diagrams } +diagrams.line @SubIndex { @Code "@Line" symbol } +line.diagrams @Index { @Code "@Line" symbol (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.curve @SubIndex { @Code "@Curve" symbol } +curve.diagrams @Index { @Code "@Curve" symbol (diagrams) } {@Code "@RVLCurve"}, and so on. There are also symbols in which the @Code "arrow" option is set to @Code yes in addition: {@Code "@Arrow"}, +diagrams. @RawIndex { diagrams } +diagrams.arrow.sym @SubIndex { @Code "@Arrow" symbol } +arrow.sym.diagrams @Index { @Code "@Arrow" symbol (diagrams) } {@Code "@CurveArrow"}, {@Code "@CCurveArrow"}, {@Code "@RVLCurveArrow"}, and so on. See the summary (Section {@NumberOf dia_summ}) for the full list of these symbols. You will still need the @Code "arrow" option diff --git a/doc/user/dia_node b/doc/user/dia_node index 4fd6159..fddf3e0 100644 --- a/doc/user/dia_node +++ b/doc/user/dia_node @@ -4,14 +4,19 @@ @Begin @PP @Code "@Diag" has one basic symbol for creating nodes. It is called -node. @Index { @Code "@Node" } +diagrams. @RawIndex { diagrams } +diagrams.node @SubIndex { @Code "@Node" symbol } +node.diagrams @Index { @Code "@Node" symbol (diagrams) } {@Code "@Node"}, and it takes the following object and encloses it in an outline whose shape is determined by the {@Code "outline"} option: +diagrams. @RawIndex { diagrams } +diagrams.outline @SubIndex { @Code "outline" option } +outline.diagrams @Index { @Code "outline" option (diagrams) } @ID { -@Code { -"@Node" -" outline { curvebox }" -"{ Hello, world }" +@Code @Verbatim { +@Node + outline { curvebox } +{ Hello, world } } ||7ct @Diag { @@ -29,13 +34,16 @@ produce standard shapes: {@Code box}, {@Code curvebox}, {@Code shadowbox}, The shape of the outline is determined by the @Code outline option, but its size and position depend on the size and position of its {@I base}: the following object with a small margin around it. For +diagrams. @RawIndex { diagrams } +diagrams.base @SubIndex { base of a node } +base.diagrams @Index { base of a node in diagrams } example, this is how a circle is positioned over its base (shown in grey): @ID @OneRow { -@Code { -"@Node" -" outline { circle }" -"{ Hello, world }" +@Code @Verbatim { +@Node + outline { circle } +{ Hello, world } } ||7ct @Diag { @@ -55,14 +63,14 @@ exception share the following very useful property: they may be given to the @Code "@Diag" symbol as well, where they apply to every node in the diagram: @ID @OneRow { -@Code { -"@Diag" -" outline { circle }" -"{" -" @Node @I a" -" @DP" -" @Node @I b" -"}" +@Code @Verbatim { +@Diag + outline { circle } +{ + @Node @I a + @DP + @Node @I b +} } ||7ct @Diag @@ -88,9 +96,15 @@ 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 -anode.fig @Index { @Code "@ANode" in @Code "@Diag" } -bnode.fig @Index { @Code "@BNode" in @Code "@Diag" } -cnode.fig @Index { @Code "@CNode" in @Code "@Diag" } +diagrams. @RawIndex { diagrams } +diagrams.anode @SubIndex { @Code "@ANode" symbol } +anode.diagrams @Index { @Code "@ANode" symbol (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.bnode @SubIndex { @Code "@BNode" symbol } +bnode.diagrams @Index { @Code "@BNode" symbol (diagrams) } +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 "@Node"}, but the @I default values of these options are different, in that they come from @Code "@Diag" options, @@ -130,33 +144,55 @@ setup file is omitted. To save time in simple cases, @Code "@Diag" provides nine other node symbols called {@Code "@Box"}, -box.fig @Index { @Code "@Box" in @Code "@Diag" } +diagrams. @RawIndex { diagrams } +diagrams.box @SubIndex { @Code "@Box" symbol } +boxzzz.diagrams @Index { @Code "@Box" symbol (diagrams) } {@Code "@CurveBox"}, -curvebox.fig @Index { @Code "@CurveBox" in @Code "@Diag" } +diagrams. @RawIndex { diagrams } +diagrams.curvebox @SubIndex { @Code "@CurveBox" symbol } +curvebox.diagrams @Index { @Code "@CurveBox" symbol (diagrams) } {@Code "@ShadowBox"}, -shadowbox.fig @Index { @Code "@ShadowBox" in @Code "@Diag" } +diagrams. @RawIndex { diagrams } +diagrams.shadowbox @SubIndex { @Code "@ShadowBox" symbol } +shadowbox.diagrams @Index { @Code "@ShadowBox" symbol (diagrams) } {@Code "@Square"}, -square. @Index @Code "@Square" +diagrams. @RawIndex { diagrams } +diagrams.square @SubIndex { @Code "@Square" symbol } +square.diagrams @Index { @Code "@Square" symbol (diagrams) } {@Code "@Diamond"}, -diamond. @Index @Code "@Diamond" +diagrams. @RawIndex { diagrams } +diagrams.diamond @SubIndex { @Code "@Diamond" symbol } +diamond.diagrams @Index { @Code "@Diamond" symbol (diagrams) } {@Code "@Polygon"}, +diagrams. @RawIndex { diagrams } +diagrams.polygon @SubIndex { @Code "@Polygon" symbol } {@Code "@Isosceles"}, -isosceles. @Index @Code "@Isosceles" +diagrams. @RawIndex { diagrams } +diagrams.isosceles @SubIndex { @Code "@Isosceles" symbol } +isosceles.diagrams @Index { @Code "@Isosceles" symbol (diagrams) } {@Code "@Ellipse"}, -ellipse. @Index @Code "@Ellipse" +diagrams. @RawIndex { diagrams } +diagrams.ellipse @SubIndex { @Code "@Ellipse" symbol } +ellipse.diagrams @Index { @Code "@Ellipse" symbol (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.circle @SubIndex { @Code "@Circle" symbol } +circle.diagrams @Index { @Code "@Circle" symbol (diagrams) } and {@Code "@Circle"}. These are just abbreviations for @Code "@Node" with the appropriate value of {@Code outline}, nothing more. They take the same options as {@Code "@Node"} (except that @Code outline is already fixed), and everything works in the same way. @PP There is a @Code shadow option which determines the depth of the shadow +diagrams. @RawIndex { diagrams } +diagrams.shadow @SubIndex { @Code "shadow" option } +shadow.diagrams @Index { @Code "shadow" option (diagrams) } in shadow boxes: @ID { -@Code { -"@Node" -" outline { shadowbox }" -" shadow { 0.4f }" -"{ WARNING }" +@Code @Verbatim { +@Node + outline { shadowbox } + shadow { 0.4f } +{ WARNING } } ||7ct @Diag { @@ -168,13 +204,19 @@ in shadow boxes: } This example shows the default value, 0.4 times the current font size. For polygons there is a @Code sides option for specifying the number -polygon. @Index @Code "@Polygon" +diagrams. @RawIndex { diagrams } +diagrams.sides @SubIndex { @Code "sides" option } +sides.diagrams @Index { @Code "sides" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.angle @SubIndex { @Code "angle" option } +angle.diagrams @Index { @Code "angle" option (diagrams) } +polygon.diagrams @Index { @Code "@Polygon" (diagrams) } of sides, and an @Code angle option for rotating the outline: @IL @LI { -@Code { -"@Polygon" -" sides { 5 }" +@Code @Verbatim { +@Polygon + sides { 5 } } ||7ct @Diag { @@ -185,10 +227,10 @@ of sides, and an @Code angle option for rotating the outline: } @LI { -@Code { -"@Polygon" -" sides { 5 }" -" angle { 0d }" +@Code @Verbatim { +@Polygon + sides { 5 } + angle { 0d } } ||7ct @Diag { @@ -212,14 +254,26 @@ where they apply to every node as usual. However, they only affect the appearance of shadow boxes and polygons, respectively. @PP The {@Code outlinestyle}, {@Code outlinedashlength}, and {@Code outlinewidth} +diagrams. @RawIndex { diagrams } +diagrams.outlinestyle @SubIndex { @Code "outlinestyle" option } +outlinestyle. @RawIndex { @Code "outlinestyle" option } +outlinestyle.in.diagrams @SubIndex { in diagrams } +diagrams. @RawIndex { diagrams } +diagrams.outlinedashlength @SubIndex { @Code "outlinedashlength" option } +outlinedashlength. @RawIndex { @Code "outlinedashlength" option } +outlinedashlength.in.diagrams @SubIndex { in diagrams } +diagrams. @RawIndex { diagrams } +diagrams.outlinewidth @SubIndex { @Code "outlinewidth" option } +outlinewidth. @RawIndex { @Code "outlinewidth" option } +outlinewidth.in.diagrams @SubIndex { in diagrams } options apply to any node and affect the appearance of the outline: @ID @OneRow { -@Code { -"@CurveBox" -" outlinestyle { solid }" -" outlinedashlength { 0.2f }" -" outlinewidth { thin }" -"{ Hello, world }" +@Code @Verbatim { +@CurveBox + outlinestyle { solid } + outlinedashlength { 0.2f } + outlinewidth { thin } +{ Hello, world } } ||7ct @Diag { @@ -232,14 +286,27 @@ options apply to any node and affect the appearance of the outline: } This example shows the default values of these options. The {@Code outlinestyle} option may be {@Code solid}, {@Code dashed}, -dashed. @Index { dashed lines } -dotted. @Index { dotted lines } +diagrams. @RawIndex { diagrams } +diagrams.solid @SubIndex { @Code "solid" outlines } +solid.diagrams @Index { @Code "solid" outlines (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.dashed @SubIndex { @Code "dashed" outlines } +dashed.diagrams @Index { dashed outlines (diagrams) } {@Code cdashed}, {@Code dotted}, or {@Code noline}: +diagrams. @RawIndex { diagrams } +diagrams.cdashed @SubIndex { @Code "cdashed" outlines } +cdashed.diagrams @Index { cdashed outlines (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.dotted @SubIndex { @Code "dotted" outlines } +dotted.diagrams @Index { dotted outlines (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.noline @SubIndex { @Code "noline" outlines } +noline.diagrams @Index { noline outlines (diagrams) } @ID @OneRow { -@Code { -"@CurveBox" -" outlinestyle { cdashed }" -"{ Hello, world }" +@Code @Verbatim { +@CurveBox + outlinestyle { cdashed } +{ Hello, world } } ||7ct @Diag { @@ -262,10 +329,10 @@ The {@Code outlinestyle} option may contain a sequence of the values mentioned above, meaning that they are to be applied in turn to each segment of the outline: @ID @OneRow { -@Code { -"@CurveBox" -" outlinestyle { solid cdashed }" -"{ Hello, world }" +@Code @Verbatim { +@CurveBox + outlinestyle { solid cdashed } +{ Hello, world } } ||7ct @Diag { @@ -289,14 +356,18 @@ options have been kept simple to reflect that. @PP Nodes may be painted any of the colours listed in Section {@NumberOf colour}, using the @Code "paint" option: +diagrams. @RawIndex { diagrams } +diagrams.paint @SubIndex { @Code "paint" option } +paint. @RawIndex { @Code "paint" option } +paint.in.diagrams @SubIndex { in diagrams } @ID @OneRow { -@Code { -"@Box" -" paint { grey }" -"@Diamond" -" outlinestyle { noline }" -" paint { white }" -"{ Hello, world }" +@Code @Verbatim { +@Box + paint { grey } +@Diamond + outlinestyle { noline } + paint { white } +{ Hello, world } } ||7ct @Diag { @@ -309,27 +380,42 @@ Nodes may be painted any of the colours listed in Section } } In this example the object following @Code "@Box" is a diamond containing -{@Code "Hello, world"}. The default value of @Code "paint" is -{@Code nopaint}, a special value (not a colour) meaning don't use any paint. +{@Code "Hello, world"}. The default value of @Code "paint" is {@Code none}, +a special value (not a colour) meaning don't use any paint. There is +also a @Code "texture" option which causes this paint to be applied with a +diagrams. @RawIndex { diagrams } +diagrams.texture @SubIndex { @Code "texture" option } +texture.option. @RawIndex { @Code "texture" option } +texture.option.in.diagrams @SubIndex { in diagrams } +given texture. This works exacly like the @Code texture option described +in Section {@NumberOf boxes}, so we'll say no more about it here. @PP When painting it is important to know what order things are done in, because anything put down earlier will disappear under the paint. This is why -@Code nopaint and @Code white are different. Painting is done first, then +@Code none and @Code white are different. Painting is done first, then boundaries, and finally the following object. @PP Each node symbol has @Code "font" and @Code "break" options which may be used to +diagrams. @RawIndex { diagrams } +diagrams.font @SubIndex { @Code "font" option } +font.option. @RawIndex { @Code "font" option } +font.option.in.diagrams @SubIndex { in diagrams } +diagrams. @RawIndex { diagrams } +diagrams.break @SubIndex { @Code "break" option } +break. @RawIndex { @Code "break" option } +break.diagrams @SubIndex { in diagrams } set the font and paragraph breaking style of the following object: @ID @OneRow { -@Code { -"@Box" -" font { Helvetica Base }" -" break { clines }" -"{" -"WARNING" -"DANGEROUS" -"PENGUINS" -"}" +@Code @Verbatim { +@Box + font { Helvetica Base } + break { clines } +{ +WARNING +DANGEROUS +PENGUINS +} } ||7ct @Diag { @@ -345,16 +431,19 @@ PENGUINS } Both options have empty default values, which leave the font and break style unchanged. There is also a @Code "format" option for making more +diagrams. @RawIndex { diagrams } +diagrams.format @SubIndex { @Code "format" option } +format.diagrams @Index { @Code "format" option (diagrams) } radical changes to the appearance of the following object: @ID @OneRow { -@Code { -"@Box" -" format {" -" {0.8 1.5} @Scale @S @Body" -" }" -"{" -"Dangerous Penguins" -"}" +@Code @Verbatim { +@Box + format { + {0.8 1.5} @Scale @S @Body + } +{ +Dangerous Penguins +} } ||7ct @Diag { @@ -368,26 +457,30 @@ Dangerous Penguins The result is the @Code "format" option with any @Code "@Body" symbol within it replaced by the following object. These are very useful when attached to the @Code "@Diag" symbol: -@ID @OneRow @Code { -"@Diag" -" font { Helvetica Base }" -" break { clines }" -" format { { 0.8 1.5 } @Scale @S @Body }" -"{" -" ..." -"}" +@ID @OneRow @Code @Verbatim { +@Diag + font { Helvetica Base } + break { clines } + format { { 0.8 1.5 } @Scale @S @Body } +{ + ... +} } since then they apply to every node, as usual, thereby eliminating a lot of tedious, error-prone duplication of formatting information at each node. @PP The @Code margin option determines the size of the margin added to +diagrams. @RawIndex { diagrams } +diagrams.margin @SubIndex { @Code "margin" option } +margin.options @RawIndex { margin options } +margin.options.in.diagrams @SubIndex { in diagrams } the following object: @ID @OneRow { -@Code { -"@Box" -" margin { 0c }" -"{ Hello, world }" +@Code @Verbatim { +@Box + margin { 0c } +{ Hello, world } } ||7ct @Diag { @@ -411,16 +504,19 @@ are also {@Code leftmargin}, {@Code rightmargin}, {@Code margin}, {@Code hmargin}, and {@Code vmargin}. @PP When nodes appear side by side, the {@Code valign} option is +diagrams. @RawIndex { diagrams } +diagrams.valign @SubIndex { @Code "valign" option } +valign.diagrams @Index { @Code "valign" option (diagrams) } useful for controlling their vertical position with respect to each other. For example, @ID @OneRow { -@Code { -"@Diag" -" valign { foot }" -"{" -"@Box font { 24p } Big" -"@Box font { 8p } Small" -"}" +@Code @Verbatim { +@Diag + valign { foot } +{ +@Box font { 24p } Big +@Box font { 8p } Small +} } ||7ct @Diag @@ -439,15 +535,18 @@ it may be {@Code top}, {@Code ctr}, or {@Code foot}, meaning alignment through the top, centre (the default value), or foot. @PP The {@Code vsize} option specifies a particular +diagrams. @RawIndex { diagrams } +diagrams.vsize @SubIndex { @Code "vsize" option } +vsize.diagrams @Index { @Code "vsize" option (diagrams) } height for a node (not including margins): @ID @OneRow { -@Code { -"@Diag" -" vsize { 2f }" -"{" -"@Box font { 24p } Big" -"@Box font { 8p } Small" -"}" +@Code @Verbatim { +@Diag + vsize { 2f } +{ +@Box font { 24p } Big +@Box font { 8p } Small +} } ||7ct @Diag @@ -463,17 +562,20 @@ tall for the chosen height, Lout will print a warning message (`forced to enlarge {@Code "@High"}', probably) and enlarge the base. @PP There is a @Code vindent option which is effective only when @Code vsize +diagrams. @RawIndex { diagrams } +diagrams.vindent @SubIndex { @Code "vindent" option } +vindent.diagrams @Index { @Code "vindent" option (diagrams) } is used. It controls where in the vertical space the following object is to appear: @ID @OneRow { -@Code { -"@Diag" -" vsize { 3f }" -"{" -"@Box vindent { top } Top" -"@Box Centre" -"@Box vindent { foot } Foot" -"}" +@Code @Verbatim { +@Diag + vsize { 3f } +{ +@Box vindent { top } Top +@Box Centre +@Box vindent { foot } Foot +} } ||7ct @Diag @@ -493,12 +595,12 @@ for the @Code valign option. Small discrepancies in the size of nodes can be very annoying, particularly when the nodes appear side by side: @ID @OneRow { -@Code { -"@Diag" -"{" -"@Box Hole @Box in" -"@Box my @Box pocket" -"}" +@Code @Verbatim { +@Diag +{ +@Box Hole @Box in +@Box my @Box pocket +} } ||7ct @Diag @@ -511,13 +613,13 @@ These are caused by the slightly different heights of the objects within the nodes. Selecting a fixed vertical size for all nodes goes some way towards solving this problem: @ID @OneRow { -@Code { -"@Diag" -" vsize { 1f }" -"{" -"@Box Hole @Box in" -"@Box my @Box pocket" -"}" +@Code @Verbatim { +@Diag + vsize { 1f } +{ +@Box Hole @Box in +@Box my @Box pocket +} } ||7ct @Diag @@ -533,14 +635,17 @@ deepest. However, there is still a problem with the baselines of the words being misaligned. A better solution is to insert a @I { vertical strut } into each node: an invisible object with zero width and height equal to {@Code 1f}. This is done using the @Code vstrut option: +diagrams. @RawIndex { diagrams } +diagrams.vstrut @SubIndex { @Code "vstrut" option } +vstrut.diagrams @Index { @Code "vstrut" option (diagrams) } @ID @OneRow { -@Code { -"@Diag" -" vstrut { yes }" -"{" -"@Box Hole @Box in" -"@Box my @Box pocket" -"}" +@Code @Verbatim { +@Diag + vstrut { yes } +{ +@Box Hole @Box in +@Box my @Box pocket +} } ||7ct @Diag @@ -555,6 +660,18 @@ a length, meaning to insert a strut of this height. So @Code "vstrut { yes }" is equivalent to {@Code "vstrut { 1.0f }"}. @PP There are {@Code halign}, {@Code hsize}, {@Code hindent}, and {@Code hstrut} +diagrams. @RawIndex { diagrams } +diagrams.halign @SubIndex { @Code "halign" option } +halign.diagrams @Index { @Code "halign" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.hsize @SubIndex { @Code "hsize" option } +hsize.diagrams @Index { @Code "hsize" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.hindent @SubIndex { @Code "hindent" option } +hindent.diagrams @Index { @Code "hindent" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.hstrut @SubIndex { @Code "hstrut" option } +hstrut.diagrams @Index { @Code "hstrut" option (diagrams) } options which work horizontally exactly as {@Code valign}, {@Code vsize}, {@Code vindent}, and {@Code vstrut} work vertically, except that they use {@Code left} and {@Code right} where the vertical ones use diff --git a/doc/user/dia_posi b/doc/user/dia_posi index 727d3be..5cf8d82 100644 --- a/doc/user/dia_posi +++ b/doc/user/dia_posi @@ -4,6 +4,9 @@ @Begin @PP Once the nodes of the diagram are in place, @@Diag can be trusted to look +diagrams. @RawIndex { diagrams } +diagrams.positioning @SubIndex { positioning nodes } +positioning.diagrams @Index { positioning nodes in diagrams } after the rest: links to standard outlines will terminate neatly on their boundaries, labels will not overstrike links no matter what direction they are heading, and so on. The great weakness of @@Diag is in positioning @@ -23,28 +26,28 @@ a bit of a jumble. The {@Code "@Tbl"} symbol (Chapter {@NumberOf tables}) is a good choice when the nodes have any kind of grid-like arrangement: @ID @OneRow { -@Code { -"@Diag {" -"@Tbl" -" aformat { @Cell A | @Cell B | @Cell C }" -" marginhorizontal { 0.5c }" -" marginvertical { 0.25c }" -"{" -"@Rowa" -" B { A:: @Square }" -"@Rowa" -" A { B:: @Square }" -" C { C:: @Square }" -"@Rowa" -" B { D:: @Square }" -"}" -"//" -"@Arrow from { A } to { B }" -"@Arrow from { A } to { C }" -"@Arrow from { B } to { D }" -"@Arrow from { C } to { D }" -"@Arrow from { A } to { D }" -"}" +@Code @Verbatim { +@Diag { +@Tbl + aformat { @Cell A | @Cell B | @Cell C } + marginhorizontal { 0.5c } + marginvertical { 0.25c } +{ +@Rowa + B { A:: @Square } +@Rowa + A { B:: @Square } + C { C:: @Square } +@Rowa + B { D:: @Square } +} +// +@Arrow from { A } to { B } +@Arrow from { A } to { C } +@Arrow from { B } to { D } +@Arrow from { C } to { D } +@Arrow from { A } to { D } +} } ||9ct @Diag { @@ -76,21 +79,21 @@ Similarly, the @Code "@Graph" symbol from Chapter {@NumberOf graphs} has an @Code "objects" option which can place arbitrary objects, including labelled nodes, anywhere on a graph: @ID @OneRow { -@Code { -"@Diag {" -"@Graph" -" xmin { 0 }" -" xmax { 100 }" -" ymin { 0 }" -" ymax { 100 }" -" objects {" -" @CTR at { 20 30 } { A:: @Square }" -" @CTR at { 60 70 } { B:: @Square }" -" }" -"{}" -"//" -"@Link from { A } to { B }" -"}" +@Code @Verbatim { +@Diag { +@Graph + xmin { 0 } + xmax { 100 } + ymin { 0 } + ymax { 100 } + objects { + @CTR at { 20 30 } { A:: @Square } + @CTR at { 60 70 } { B:: @Square } + } +{} +// +@Link from { A } to { B } +} } ||8.5ct @Diag { @@ -117,18 +120,21 @@ somewhat similar to the @Code "@Graph" one. It is often the easiest way to scatter nodes about a diagram at random. The first step is to create a nodes part that is just an empty space of whatever size you want the final diagram to be: -@ID @OneRow @Code { -"@Diag {" -" 4c @High 6c @Wide" -" //" -" ..." -"}" +@ID @OneRow @Code @Verbatim { +@Diag { + 4c @High 6c @Wide + // + ... +} } As shown, this is done with the @Code "@Wide" and @Code "@High" symbols from basic Lout; the above diagram will be four centimetres high by six centimetres wide. @PP @@Diag has a @Code "," symbol that allows you to specify a point by +diagrams. @RawIndex { diagrams } +diagrams.coordinates @SubIndex { coordinates } +coordinates.diagrams @Index { coordinates in diagrams } its coordinates in the diagram's base. For example, @Code "0,0" denotes the bottom left-hand corner of the base, @Code "1,0" denotes the bottom right-hand corner, and @@ -137,23 +143,26 @@ usually be between 0 and 1, since otherwise they denote points outside the base (which is allowed but seldom useful). @PP Every node symbol has a @Code "translate" option which allows you +diagrams. @RawIndex { diagrams } +diagrams.translate @SubIndex { @Code "translate" option } +translate.diagrams @Index { @Code "translate" option (diagrams) } to move the node about on the diagram's base (or off it if you use coordinates less than 0 or greater than 1). If you use this option, the node effectively has zero size and overstrikes anything else in the area you put it (like labels do). It is best to put these nodes in the links part: @ID @OneRow { -@Code { -"@Diag {" -"@Box margin { 0c } 4c @Wide 5c @High" -"//" -"A:: @Square" -" translate { CTR to 0.5, 0.67 }" -" { @I A }" -"B:: @Circle" -" translate { CTR to 0.8, 0.25 }" -" { @I B }" -"}" +@Code @Verbatim { +@Diag { +@Box margin { 0c } 4c @Wide 5c @High +// +A:: @Square + translate { CTR to 0.5, 0.67 } + { @I A } +B:: @Circle + translate { CTR to 0.8, 0.25 } + { @I B } +} } ||9ct @Diag { @@ -177,25 +186,25 @@ You are free to have nodes in the nodes part as well, or any object at all. Here is an example which shows what a little ingenuity can accomplish: @ID @OneRow { -@Code { -"@Diag {" -"@Polygon" -" sides { 5 }" -" outlinestyle { noline }" -" hsize { 4c }" -" vsize { 4c }" -"//" -"A:: @Circle translate { N to P1 } {}" -"B:: @Circle translate { N to P2 } {}" -"C:: @Circle translate { N to P3 } {}" -"D:: @Circle translate { N to P4 } {}" -"E:: @Circle translate { N to P5 } {}" -"@Link arrow { both } from { A } to { B }" -"@Link arrow { both } from { B } to { C }" -"@Link arrow { both } from { C } to { D }" -"@Link arrow { both } from { D } to { E }" -"@Link arrow { both } from { E } to { A }" -"}" +@Code @Verbatim { +@Diag { +@Polygon + sides { 5 } + outlinestyle { noline } + hsize { 4c } + vsize { 4c } +// +A:: @Circle translate { N to P1 } {} +B:: @Circle translate { N to P2 } {} +C:: @Circle translate { N to P3 } {} +D:: @Circle translate { N to P4 } {} +E:: @Circle translate { N to P5 } {} +@Link arrow { both } from { A } to { B } +@Link arrow { both } from { B } to { C } +@Link arrow { both } from { C } to { D } +@Link arrow { both } from { D } to { E } +@Link arrow { both } from { E } to { A } +} } ||9ct @Diag { diff --git a/doc/user/dia_summ b/doc/user/dia_summ index 230b745..193417e 100644 --- a/doc/user/dia_summ +++ b/doc/user/dia_summ @@ -4,6 +4,9 @@ @Begin @PP Here is the complete list of standard node outlines that may be given +diagrams. @RawIndex { diagrams } +diagrams.summary @SubIndex { summary of all options } +summary.diagrams @Index { summary of all options for diagrams } to the @Code "@Node" symbol. Each shows the outline name, any extra options relevant to this outline, base (shown as a grey box), segments (shown using {@Code "outlinestyle { solid dashed }"}), @@ -262,8 +265,12 @@ any outline } C { {@Code thin}, {@Code medium}, {@Code thick}, or any @I length } @Rowa A { " paint" } - B { nopaint } - C { @Code nopaint or any colour from Section {@NumberOf colour} } + B { none } + C { @Code none or any colour from Section {@NumberOf colour} } +@Rowa + A { " texture" } + B { solid } + C { Any texture from Section {@NumberOf textures} } @Rowa A { " font" } B { } @@ -320,6 +327,10 @@ length from Section {@NumberOf objects} } C { {@Code "left"}, {@Code "ctr"}, {@Code "mctr"}, {@Code "right"}, or any length from Section {@NumberOf objects} } @Rowa + A { " hstrut"} + B { no } + C { {@Code no}, {@Code yes}, or any length from Section {@NumberOf objects} } +@Rowa A { " hmargin" } B { margin } C { any length from Section {@NumberOf objects} } @@ -332,10 +343,6 @@ length from Section {@NumberOf objects} } B { hmargin } C { any length from Section {@NumberOf objects} } @Rowa - A { " hstrut"} - B { no } - C { {@Code no}, {@Code yes}, or any length from Section {@NumberOf objects} } -@Rowa A { " nodelabel"} B { } C { any object } @@ -369,7 +376,8 @@ length from Section {@NumberOf objects} } B { outside } C { {@Code above}, {@Code below}, {@Code left}, {@Code right}, {@Code inside}, or {@Code outside}; {@Code CTR}, {@Code N}, {@Code S}, -{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, or {@Code SE} +{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, {@Code SE}, +{@Code NNW}, {@Code NNE}, {@Code SSW}, or {@Code SSE} } @Rowa A { " nodelabelctr"} @@ -1210,6 +1218,19 @@ or {@Code both} } B { 0.5f } C { any @I length } @Rowa + A { " backarrowstyle"} + B { solid } + C { {@Code solid}, {@Code halfopen}, {@Code open}, {@Code curvedsolid}, +{@Code curvedhalfopen}, or {@Code curvedopen} } +@Rowa + A { " backarrowwidth"} + B { 0.3f } + C { any @I length } +@Rowa + A { " backarrowlength"} + B { 0.5f } + C { any @I length } +@Rowa A { " linklabel"} B { } C { any object } @@ -1243,7 +1264,8 @@ or {@Code both} } B { above } C { {@Code above}, {@Code below}, {@Code left}, {@Code right}, {@Code inside}, or {@Code outside}; {@Code CTR}, {@Code N}, {@Code S}, -{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, or {@Code SE} +{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, {@Code SE}, +{@Code NNW}, {@Code NNE}, {@Code SSW}, or {@Code SSE} } @Rowa A { " linklabelctr"} @@ -1279,7 +1301,7 @@ or {@Code both} } C { any length from Section {@NumberOf objects} } @Rowa A { " fromlabelfont"} - B { } + B { "-2p" } C { Any value suitable for the @Code "@Font" symbol } @Rowa A { " fromlabelbreak"} @@ -1303,7 +1325,8 @@ or {@Code both} } B { W } C { {@Code above}, {@Code below}, {@Code left}, {@Code right}, {@Code inside}, or {@Code outside}; {@Code CTR}, {@Code N}, {@Code S}, -{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, or {@Code SE} +{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, {@Code SE}, +{@Code NNW}, {@Code NNE}, {@Code SSW}, or {@Code SSE} } @Rowa A { " fromlabelctr"} @@ -1323,7 +1346,7 @@ or {@Code both} } C { any length from Section {@NumberOf objects} } @Rowa A { " tolabelfont"} - B { } + B { "-2p" } C { Any value suitable for the @Code "@Font" symbol } @Rowa A { " tolabelbreak"} @@ -1347,7 +1370,8 @@ or {@Code both} } B { W } C { {@Code above}, {@Code below}, {@Code left}, {@Code right}, {@Code inside}, or {@Code outside}; {@Code CTR}, {@Code N}, {@Code S}, -{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, or {@Code SE} +{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, {@Code SE}, +{@Code NNW}, {@Code NNE}, {@Code SSW}, or {@Code SSE} } @Rowa A { " tolabelctr"} diff --git a/doc/user/dia_synt b/doc/user/dia_synt index 6cef550..260197e 100644 --- a/doc/user/dia_synt +++ b/doc/user/dia_synt @@ -4,7 +4,8 @@ @Begin @PP A variant of the @@Diag symbol, called {@Code "@SyntaxDiag"}, -syntax.diag @Index { @Code "@SyntaxDiag" symbol } +diagrams. @RawIndex { diagrams } +diagrams.syntax @SubIndex { syntax diagrams } syntax.diagrams @Index { syntax diagrams } railroad.diagrams @Index { railroad diagrams } produces syntax diagrams (sometimes called railroad diagrams): diff --git a/doc/user/dia_tags b/doc/user/dia_tags index 86f22e3..ce2e2d7 100644 --- a/doc/user/dia_tags +++ b/doc/user/dia_tags @@ -5,6 +5,9 @@ @PP In addition to drawing the outline, each of the standard node types also attaches names, called {@I tags}, to certain points. For +diagrams. @RawIndex { diagrams } +diagrams.tags @SubIndex { tags ({@Code "::"}) } +tags.diagrams @Index { tags ({@Code "::"}) in diagrams } example, the @Code "@Ellipse" symbol creates nine tags: @ID { @Code { @@ -36,10 +39,10 @@ The names and positions of all standard tags may be found in the summary (Section {@NumberOf dia_summ}) at the end of this chapter. Each tag stands for a point, and may be used wherever a point is required: @ID { -@Code { -"@Ellipse { Hello, world }" -"//" -"@Link from { SW } to { SE }" +@Code @Verbatim { +@Ellipse { Hello, world } +// +@Link from { SW } to { SE } } ||7ct @Diag { @@ -73,10 +76,10 @@ afterwards the names are changed by prefixing the word preceding {@Code "::"}, plus a @Code "@" character, to each one. These longer tags may be used exactly like the others: @ID { -@Code { -"A:: @Ellipse { Hello, world }" -"//" -"@Link from { A@SW } to { A@SE }" +@Code @Verbatim { +A:: @Ellipse { Hello, world } +// +@Link from { A@SW } to { A@SE } } ||7ct @Diag { @@ -89,17 +92,17 @@ The retagging symbol may be applied to links, and indeed to arbitrary objects; it will retag every tag within the following object, even tags that have already been retagged: @ID { -@Code { -"A:: {" -" 1:: @Ellipse" -" vsize { 1.0c }" -" hsize { 2.5c }" -" @DP" -" @DP" -" 2:: @Ellipse" -" vsize { 1.0c }" -" hsize { 2.5c }" -"}" +@Code @Verbatim { +A:: { + 1:: @Ellipse + vsize { 1.0c } + hsize { 2.5c } + @DP + @DP + 2:: @Ellipse + vsize { 1.0c } + hsize { 2.5c } +} } ||7ct @Diag { @@ -125,14 +128,14 @@ any mixup causes total disaster. @PP When a tag lies within the object following some node, it is automatically retagged in this way with tag {@Code IN}. For example, in -@ID @Code { -"@Square" -"@Circle Hello" +@ID @Code @Verbatim { +@Square +@Circle Hello } the circle lies within the square, and what you get in effect is -@ID @Code { -"@Square" -"IN:: @Circle Hello" +@ID @Code @Verbatim { +@Square +IN:: @Circle Hello } This prevents confusion between the tags of the inner and outer nodes. This retagging cannot be left to the user's discretion, owing to unexpected @@ -144,13 +147,13 @@ Although @Code from and @Code to are just two of several options within given, they have a special virtue not shared by any other options. It is possible to give the name of an entire node, not just a tag denoting one point, to them: -@ID { +@ID @Verbatim { @Code { -"A:: @Circle" -"@DP" -"B:: @Ellipse { Hello, world }" -"//" -"@Link from { A } to { B }" +A:: @Circle +@DP +B:: @Ellipse { Hello, world } +// +@Link from { A } to { B } } ||7ct @Diag { @@ -167,6 +170,9 @@ potentially confusing: @Code A and @Code B do not denote points and are not tags, strictly speaking, at all. @PP The @Code "::" symbol has a @Code restrict option which can be +diagrams. @RawIndex { diagrams } +diagrams.restrict @SubIndex { @Code "restrict" option } +restrict.diagrams @Index { @Code "restrict" option (diagrams) } used to save printer memory in deeply nested structures (such as the syntax diagrams of Section {@NumberOf dia_synt}) by restricting the tags promoted by @Code "::" to a limited set: diff --git a/doc/user/dia_tree b/doc/user/dia_tree index d16f2bc..3b1b6d1 100644 --- a/doc/user/dia_tree +++ b/doc/user/dia_tree @@ -4,29 +4,37 @@ @Begin @PP @@Diag offers some symbols for producing tree diagrams, using the -tree. @Index { @Code "@Tree" symbol in @@Diag } +diagrams. @RawIndex { diagrams } +diagrams.tree @SubIndex { @Code "@Tree" symbol } +tree.diagrams @Index { @Code "@Tree" symbol (diagrams) } @Code "@Tree" symbol, which may appear anywhere within the nodes part: -@ID @OneRow @Code { -"@Diag {" -" ..." -" @Tree { ... }" -" ..." -"}" +@ID @OneRow @Code @Verbatim { +@Diag { + ... + @Tree { ... } + ... +} } Within this symbol, new symbols {@Code "@LeftSub"}, {@Code "@RightSub"}, +diagrams. @RawIndex { diagrams } +diagrams.leftsub @SubIndex { @Code "@LeftSub" symbol } +leftsub.diagrams @Index { @Code "@LeftSub" symbol (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.rightsub @SubIndex { @Code "@RightSub" symbol } +rightsub.diagrams @Index { @Code "@RightSub" symbol (diagrams) } {@Code "@FirstSub"}, {@Code "@NextSub"}, and {@Code "@StubSub"} become available. The first two are used to get a (non-empty) binary tree: @ID @OneRow { -@Code { -"@Tree {" -" @Circle A" -" @LeftSub {" -" @Circle B" -" @LeftSub @Square C" -" @RightSub @Square D" -" }" -" @RightSub @Circle E" -"}" +@Code @Verbatim { +@Tree { + @Circle A + @LeftSub { + @Circle B + @LeftSub @Square C + @RightSub @Square D + } + @RightSub @Circle E +} } ||7ct @Diag { @@ -52,19 +60,25 @@ left or right subtree, leave out the corresponding @Code "@LeftSub" or @Code "@RightSub" symbol. @PP A similar system using @Code "@FirstSub" and @Code "@NextSub" produces +diagrams. @RawIndex { diagrams } +diagrams.firstsub @SubIndex { @Code "@FirstSub" symbol } +firstsub.diagrams @Index { @Code "@FirstSub" symbol (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.nextsub @SubIndex { @Code "@NextSub" symbol } +nextsub.diagrams @Index { @Code "@NextSub" symbol (diagrams) } trees in which each node may have arbitrarily many children: @ID @OneRow { -@Code { -"@Tree {" -" @Circle A" -" @FirstSub {" -" @Circle B" -" @FirstSub @Square C" -" @NextSub @Square D" -" }" -" @NextSub @Circle E" -" @NextSub @Circle F" -"}" +@Code @Verbatim { +@Tree { + @Circle A + @FirstSub { + @Circle B + @FirstSub @Square C + @NextSub @Square D + } + @NextSub @Circle E + @NextSub @Circle F +} } ||7ct @Diag { @@ -90,16 +104,16 @@ intruding into the space beneath it. Although each subtree must contain a node for its root, it is not hard to get around this: @ID @OneRow { -@Code { -"@Tree" -"{" -"@Circle" -"@FirstSub @Circle" -"@NextSub pathstyle { noline }" -" @Circle outlinestyle { noline }" -" ..." -"@NextSub @Circle" -"}" +@Code @Verbatim { +@Tree +{ +@Circle +@FirstSub @Circle +@NextSub pathstyle { noline } + @Circle outlinestyle { noline } + ... +@NextSub @Circle +} } ||7ct @Diag { @@ -119,12 +133,15 @@ in a way consistent with the surrounding nodes, and offers margins and so forth which help with fine-tuning its position. @PP The fifth subtree symbol, {@Code "@StubSub"}, produces a stub subtree: +diagrams. @RawIndex { diagrams } +diagrams.stubsub @SubIndex { @Code "@StubSub" symbol } +stubsub.diagrams @Index { @Code "@StubSub" symbol (diagrams) } @ID @OneRow { -@Code { -"@Tree {" -"@Circle @Eq { a }" -"@StubSub @Eq { T tsub a }" -"}" +@Code @Verbatim { +@Tree { +@Circle @Eq { a } +@StubSub @Eq { T tsub a } +} } ||7ct @Diag { @@ -152,18 +169,18 @@ The subtree symbols have all of the options of {@Code "@Link"}, and these apply to the link drawn from the parent of the root of the subtree to the root of the subtree (or anticlockwise around the stub object): @ID @OneRow { -@Code { -"@Tree {" -" @Circle A" -" @LeftSub" -" arrow { yes }" -" xlabel { 1 }" -" @Circle B" -" @RightSub" -" arrow { yes }" -" xlabel { 2 }" -" @Circle C" -"}" +@Code @Verbatim { +@Tree { + @Circle A + @LeftSub + arrow { yes } + xlabel { 1 } + @Circle B + @RightSub + arrow { yes } + xlabel { 2 } + @Circle C +} } ||7ct @Diag { @@ -185,16 +202,22 @@ To get reverse arrows use @Code "arrow { back }" as usual. The subtree symbols do not need @Code from and @Code to options, because they already know which nodes they are linking together. However, you may use @Code from or @Code to to give a tag specifying a particular +diagrams. @RawIndex { diagrams } +diagrams.from @SubIndex { @Code "from" option } +from.diagrams @Index { @Code "from" option (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.to @SubIndex { @Code "to" option } +to.diagrams @Index { @Code "to" option (diagrams) } point within the node: @ID @OneRow { -@Code { -"@Tree {" -"@Circle" -"@LeftSub from { S } to { N }" -" @Isosceles vsize { 2f }" -"@RightSub from { S } to { N }" -" @Isosceles vsize { 2f }" -"}" +@Code @Verbatim { +@Tree { +@Circle +@LeftSub from { S } to { N } + @Isosceles vsize { 2f } +@RightSub from { S } to { N } + @Isosceles vsize { 2f } +} } ||7ct @Diag @@ -213,15 +236,15 @@ In this example both links go from the @Code S tag of the parent node to the options also work for {@Code "@StubSub"}, where they refer to the start and end of the stub path: @ID @OneRow { -@Code { -"@Tree {" -"@Circle @Eq { a }" -"@StubSub" -" from { SW }" -" to { SE }" -"@Box outlinestyle { noline }" -" @Eq { T tsub a }" -"}" +@Code @Verbatim { +@Tree { +@Circle @Eq { a } +@StubSub + from { SW } + to { SE } +@Box outlinestyle { noline } + @Eq { T tsub a } +} } ||7ct @Diag { @@ -239,25 +262,31 @@ and so the tags both refer to points in the parent node in this case. @PP The @Code "@LeftSub" and @Code "@RightSub" symbols have variants called @Code "@ZeroWidthLeftSub" and @Code "@ZeroWidthRightSub" which are the +diagrams. @RawIndex { diagrams } +diagrams.zerowidthleftsub @SubIndex { @Code "@ZeroWidthLeftSub" symbol } +zerowidthleftsub.diagrams @Index { @Code "@ZeroWidthLeftSub" (diagrams) } +diagrams. @RawIndex { diagrams } +diagrams.zerowidthrightsub @SubIndex { @Code "@ZeroWidthRightSub" symbol } +zerowidthrightsub.diagrams @Index { @Code "@ZeroWidthRightSub" (diagrams) } same except that the resulting subtrees consume no width: @ID @OneRow { -@Code { -"@Tree {" -"@Circle" -"@LeftSub {" -" @Circle" -" @LeftSub @Square" -" @RightSub @Square" -"}" -"@RightSub {" -" @Circle" -" @LeftSub {" -" @Circle" -" @ZeroWidthLeftSub @Square" -" @ZeroWidthRightSub @Square" -" }" -" @RightSub @Square" -"} }" +@Code @Verbatim { +@Tree { +@Circle +@LeftSub { + @Circle + @LeftSub @Square + @RightSub @Square +} +@RightSub { + @Circle + @LeftSub { + @Circle + @ZeroWidthLeftSub @Square + @ZeroWidthRightSub @Square + } + @RightSub @Square +} } } ||7ct @Diag { @@ -285,23 +314,29 @@ There is nothing analogous for the other subtree symbols. @PP The @Code "@Diag" symbol has a few options for adjusting the appearance of the tree. The @Code "treehsep" option determines the horizontal space left +diagrams. @RawIndex { diagrams } +diagrams.treehsep @SubIndex { @Code "treehsep" option } +treehsep.diagrams @Index { @Code "treehsep" option (diagrams) } between a root and its left subtree, between a root and its right subtree, and between one subtree and the next when @Code "@NextSub" is used. The @Code "treevsep" option determines the vertical space left between a root +diagrams. @RawIndex { diagrams } +diagrams.treevsep @SubIndex { @Code "treevsep" option } +treevsep.diagrams @Index { @Code "treevsep" option (diagrams) } and its subtrees: @ID @OneRow { -@Code { -"@Diag" -" treehsep { 0c }" -" treevsep { 0c }" -"{" -"@Tree" -"{" -" @Circle A" -" @LeftSub @Square B" -" @RightSub @Square C" -"}" -"}" +@Code @Verbatim { +@Diag + treehsep { 0c } + treevsep { 0c } +{ +@Tree +{ + @Circle A + @LeftSub @Square B + @RightSub @Square C +} +} } ||7ct @Diag @@ -322,6 +357,9 @@ These options may also be given to individual subtree symbols, although all children of their parent. @PP The @Code "treehindent" option determines where the root of a non-binary +diagrams. @RawIndex { diagrams } +diagrams.treehindent @SubIndex { @Code "treehindent" option } +treehindent.diagrams @Index { @Code "treehindent" option (diagrams) } tree is positioned over its subtrees; the value may be @Code "left" for at left, @Code "ctr" for centred over them (the default), @Code "right" for at the right, or any length, meaning that far from @@ -340,7 +378,9 @@ the end. The root always has tag {@Code "T"}. The tree as a whole may be retagged in the usual way. @PP There is an @Code "@HTree" symbol which is the same as -htree. @Index { @Code "@HTree" symbol in @@Diag } +diagrams. @RawIndex { diagrams } +diagrams.htree @SubIndex { @Code "@HTree" symbol } +htree.diagrams @Index { @Code "@HTree" symbol (diagrams) } @Code "@Tree" except that the tree grows horizontally (from left to right) instead of vertically. The same symbols are available within @Code "@HTree" as within {@Code "@Tree"}; @Code "@LeftSub" and @@ -348,20 +388,23 @@ right) instead of vertically. The same symbols are available within @Code "@RightSub" and @Code "@NextSub" produce lower trees. @Code "@HTree" has no @Code "treehindent" option; instead, it has an exactly analogous @Code "treevindent" option. +diagrams. @RawIndex { diagrams } +diagrams.treevindent @SubIndex { @Code "treevindent" option } +treevindent.diagrams @Index { @Code "treevindent" option (diagrams) } @PP @Code "@HTree" may be used to get horizontal lists: @ID @OneRow { -@Code { -"@I @Diag" -" arrow { yes } treehsep { 1c } {" -"@HTree {" -" @Node A" -" @FirstSub {" -" @Node B" -" @FirstSub @Node C" -" }" -"}" -"}" +@Code @Verbatim { +@I @Diag + arrow { yes } treehsep { 1c } { +@HTree { + @Node A + @FirstSub { + @Node B + @FirstSub @Node C + } +} +} } ||7ct @I @Diag arrow { yes } treehsep { 1c } { diff --git a/doc/user/equ b/doc/user/equ index 7a87fdb..6e3525d 100644 --- a/doc/user/equ +++ b/doc/user/equ @@ -6,7 +6,9 @@ This chapter explains how to produce mathematical formulas in Lout, equations. @Index { equations } mathematics. @Index mathematics -eq. @Index @Code "@Eq" +equations. @RawIndex { equations } +equations.eq @SubIndex { @Code "@Eq" } +eq.equations @Index { @Code "@Eq" (equations) } using the @Code "@Eq" symbol like this: @ID @Code { "@Eq { big int supp 1 on 0 ` dx over sqrt {1 - x sup 2} = pi over 2 }" diff --git a/doc/user/equ_defs b/doc/user/equ_defs index 0e38da7..e05deac 100644 --- a/doc/user/equ_defs +++ b/doc/user/equ_defs @@ -5,6 +5,10 @@ Whenever you type particular equations or parts of equations repeatedly, you can save time by using definitions. Definitions are the subject of Section {@NumberOf definitions}, so here we will just give a few examples +equations. @RawIndex { equations } +equations.definitions @SubIndex { definitions, use with } +definitions. @RawIndex { definitions } +definitions.use.with.equations @SubIndex { use with equations } of their use in equation formatting. @PP Suppose for example that @OneCol @Eq { p sub i ` log sub 2 ` p sub i } diff --git a/doc/user/equ_disp b/doc/user/equ_disp index ea4af47..43ce4b8 100644 --- a/doc/user/equ_disp +++ b/doc/user/equ_disp @@ -93,14 +93,14 @@ Fortunately, each display symbol has a `raw' version, which means that no space is inserted above or below the display. Instead, raw.displays @Index { raw displays } you must insert it yourself using paragraph symbols: -@ID @OneRow @Code { -"preceding text" -"@DP" -"@RawAlignedDisplay @Eq { ... }" -"@DP" -"@RawAlignedNumberedDisplay @Eq { ... }" -"@DP" -"following text" +@ID @OneRow @Code @Verbatim { +preceding text +@DP +@RawAlignedDisplay @Eq { ... } +@DP +@RawAlignedNumberedDisplay @Eq { ... } +@DP +following text } You get the right spacing by placing {@Code "@DP"} symbols before, between, and after each display; and you get to use the specialized diff --git a/doc/user/equ_intr b/doc/user/equ_intr index 882aaff..e6f742f 100644 --- a/doc/user/equ_intr +++ b/doc/user/equ_intr @@ -17,12 +17,11 @@ you want equations, like this: } This shows what to do if you want both tables and equations, but you may leave out the line for tables if you don't want them. Setup files -for specialized packages, such as like {@Code "tab"} and {@Code "eq"}, +for specialized packages, such as {@Code "tab"} and {@Code "eq"}, are best included before the main setup file, but may be included in any order. @PP With the @Code "eq" file included, you may write -eq. @Index { @Code "@Eq" } @ID @Code "@Eq { ... }" at any point in your document, and the symbols of @Code "@Eq" will be available between the braces. Any symbols available outside continue @@ -38,7 +37,9 @@ at the desired point. To make the optimal paragraph breaker work hard to arrange the paragraph so that the equation does not spread over two lines, use {@Code "@OneCol @Eq { ... }"}. This is needed so frequently that a symbol @Code "@E" is defined in @Code "eq" along with @Code "@Eq" -e. @Index { @Code "@E" } +equations. @RawIndex { equations } +equations.e @SubIndex { @Code "@E" } +eaaa.equations @Index { @Code "@E" (equations) } which is an abbreviation for {@Code "@OneCol @Eq"}. @PP To display an equation, use a display symbol like @Code "@IndentedDisplay" diff --git a/doc/user/equ_spac b/doc/user/equ_spac index 2a79fb1..47aff3b 100644 --- a/doc/user/equ_spac +++ b/doc/user/equ_spac @@ -19,9 +19,13 @@ simplest way to restore the effect of white space to part of an equation is to enclose that part in a @Code "@Font" symbol.) @PP Every symbol provided by {@Code "@Eq"} has a @I {full name}, which +equations. @RawIndex { equations } +equations.fullname @SubIndex { full name of symbol } full.name @Index { full name of equation symbol } denotes the symbol without any space attached. Many symbols also have a @I {short name}, which denotes the same symbol with what +equations. @RawIndex { equations } +equations.shortname @SubIndex { short name of symbol } short.name @Index { short name of equation symbol } {@Code "@Eq"} considers to be an appropriate amount of space for that symbol attached to it. For example, @Eq { lessequal } has full name @@ -39,11 +43,17 @@ symbol attached to it. For example, @Eq { lessequal } has full name } @EL {@Code "@Eq"} puts a thick space around relation symbols like {@Code "<="}, -relations @Index { relation symbols in equations } +equations. @RawIndex { equations } +equations.relation.symbols @SubIndex { relation symbols } +relation.symbols @Index { relation symbols in equations } a medium space around binary operator symbols like {@Code "+"}, and a thin -binary.op @Index { binary operators in equations } +equations. @RawIndex { equations } +equations.binaryoperators @SubIndex { binary operator symbols } +binaryoperators @Index { binary operator symbols in equations } space after punctuation symbols (@Code ";" and {@Code ","}); except that -punctuation @Index { punctuation in equations } +equations. @RawIndex { equations } +equations.punctuation @SubIndex { punctuation symbols } +punctuation @Index { punctuation symbols in equations } in places where the symbols appear in a smaller size (superscripts, subscripts, etc.), these spaces are omitted. No other horizontal space is ever inserted. @@ -52,6 +62,9 @@ The short names have been carefully designed to produce good-looking mathematics most of the time. It is best to rely on them in the first instance and only think about spacing when the result is not pleasing. In that case, {@Code "@Eq"}'s space can be removed by using the full names, +equations. @RawIndex { equations } +equations.spacing @SubIndex { spacing symbols } +spacing.equations @Index { spacing symbols in equations } and thin, medium and thick space can be added using the following symbols: @ID @Tab vmargin { 0.5vx } @@ -72,10 +85,21 @@ precedence. The @Code "&" symbol from raw Lout is also available; the @Code "s" unit has value 0 and so is not very useful, but one can write @Code "&2m" for example for a two em space. The full names are tedious to remember, so {@Code "@Eq"} provides a @Code "non" symbol -non. @Index { @Code "non" in equations } +equations. @RawIndex { equations } +equations.non @SubIndex { @Code "non" symbol } +non.equations @Index { @Code "non" symbol (equations) } which removes spaces from its right parameter; thus @Code "non <=" is equivalent to {@Code "lessequal"}. There are also {@Code "rel"}, +equations. @RawIndex { equations } +equations.rel @SubIndex { @Code "rel" symbol } +rel.equations @Index { @Code "rel" symbol (equations) } {@Code "bin"}, and {@Code "punct"} symbols for telling {@Code "@Eq"} +equations. @RawIndex { equations } +equations.bin @SubIndex { @Code "bin" symbol } +bin.equations @Index { @Code "bin" symbol (equations) } +equations. @RawIndex { equations } +equations.punct @SubIndex { @Code "punct" symbol } +punct.equations @Index { @Code "punct" symbol (equations) } to add space to the following symbol as though it was a relation symbol, binary operator, or punctuation symbol. @End @Section diff --git a/doc/user/equ_summ b/doc/user/equ_summ index 9f9bf66..8f5b738 100644 --- a/doc/user/equ_summ +++ b/doc/user/equ_summ @@ -33,7 +33,11 @@ and full names. The auxiliary symbols are: B { Remove spaces normally put into @Code x } @Rowa A { @Code "vctr x" } - B { Centre @Code x vertically } + B { Centre @Code x vertically +equations. @RawIndex { equations } +equations.vctr @SubIndex { @Code "vctr" symbol } +vctr.equations @Index { @Code "vctr" symbol (equations) } +} @Rowa A { @Code "big x" } B { Make @Code x larger } @@ -63,48 +67,72 @@ examples of the other symbols: @Code "x dot" |7ct @Eq { x dot } +equations. @RawIndex { equations } +equations.dot @SubIndex { @Code "dot" symbol } +dot.equations @Index { @Code "dot" symbol (equations) } } @LI { @Code "x dotdot" |7ct @Eq { x dotdot } +equations. @RawIndex { equations } +equations.dotdot @SubIndex { @Code "dotdot" symbol } +dotdot.equations @Index { @Code "dotdot" symbol (equations) } } @LI { @Code "x hat" |7ct @Eq { x hat } +equations. @RawIndex { equations } +equations.hat @SubIndex { @Code "hat" symbol } +hat.equations @Index { @Code "hat" symbol (equations) } } @LI { @Code "x tilde" |7ct @Eq { x tilde } +equations. @RawIndex { equations } +equations.tilde @SubIndex { @Code "tilde" symbol } +tilde.equations @Index { @Code "tilde" symbol (equations) } } @LI { @Code "x vec" |7ct @Eq { x vec } +equations. @RawIndex { equations } +equations.vec @SubIndex { @Code "vec" symbol } +vec.equations @Index { @Code "vec" symbol (equations) } } @LI { @Code "x dyad" |7ct @Eq { x dyad } +equations. @RawIndex { equations } +equations.dyad @SubIndex { @Code "dyad" symbol } +dyad.equations @Index { @Code "dyad" symbol (equations) } } @LI { @Code "x+y overbar" |7ct @Eq { x+y overbar } +equations. @RawIndex { equations } +equations.overbar @SubIndex { @Code "overbar" symbol } +overbar.equations @Index { @Code "overbar" symbol (equations) } } @LI { @Code "x+y underbar" |7ct @Eq { x+y underbar } +equations. @RawIndex { equations } +equations.underbar @SubIndex { @Code "underbar" symbol } +underbar.equations @Index { @Code "underbar" symbol (equations) } } @EL @@ -165,12 +193,18 @@ together as shown; @Code "tsub" and @Code "ton" are exactly like "{90d @Rotate blbrace}" } |7ct @Eq { {a, ... , z} widefrom {90d @Rotate blbrace} } +equations. @RawIndex { equations } +equations.widefrom @SubIndex { @Code "widefrom" symbol } +widezzzfrom.equations @Index { @Code "widefrom" symbol (equations) } } @LI { @Code "{a, ... , z} wideto minus" |7ct @Eq { {a, ... , z} wideto minus } +equations. @RawIndex { equations } +equations.wideto @SubIndex { @Code "wideto" symbol } +widezzzto.equations @Index { @Code "wideto" symbol (equations) } } @EL @@ -183,12 +217,18 @@ to the width of the left. @Code "sqrt {x over y}" |7ct @Eq { sqrt {x over y} } +equations. @RawIndex { equations } +equations.sqrt @SubIndex { @Code "sqrt" symbol } +sqrt.equations @Index { @Code "sqrt" symbol (equations) } } @LI { @Code "3 root {x over y}" |7ct @Eq { 3 root {x over y} } +equations. @RawIndex { equations } +equations.root @SubIndex { @Code "root" symbol } +root.equations @Index { @Code "root" symbol (equations) } } @EL @@ -200,24 +240,36 @@ four ways to denote division: @Code "2 over 3" |7ct @Eq { 2 over 3 } +equations. @RawIndex { equations } +equations.over @SubIndex { @Code "over" symbol } +over.equations @Index { @Code "over" symbol (equations) } } @LI { @Code "2 frac 3" |7ct @Eq { 2 frac 3 } +equations. @RawIndex { equations } +equations.frac @SubIndex { @Code "frac" symbol } +frac.equations @Index { @Code "frac" symbol (equations) } } @LI { @Code "2 div 3" |7ct @Eq { 2 div 3 } +equations. @RawIndex { equations } +equations.div @SubIndex { @Code "div" symbol } +div.equations @Index { @Code "div" symbol (equations) } } @LI { @Code "2 slash 3" |7ct @Eq { 2 slash 3 } +equations. @RawIndex { equations } +equations.slash @SubIndex { @Code "slash" symbol } +slash.equations @Index { @Code "slash" symbol (equations) } } @EL @@ -286,6 +338,9 @@ ragged @Break { } @DP These can be negated by preceding them with {@Code "not"}, as in +equations. @RawIndex { equations } +equations.not @SubIndex { @Code "not" symbol } +not.equations @Index { @Code "not" symbol (equations) } negation. @Index { negation of equation symbols } {@Code "not =="}, for example, which yields {@Eq { not == }}. The following short names define binary operators (medium space on each side): diff --git a/doc/user/equ_symb b/doc/user/equ_symb index f56eca2..20f407b 100644 --- a/doc/user/equ_symb +++ b/doc/user/equ_symb @@ -45,17 +45,27 @@ Some symbols join objects together in mathematical ways: @Eq { x sub 2 } } Here the @Code "sub" symbol has taken the object just to its left, and -sub. @Index { @Code "sub" in equations } +equations. @RawIndex { equations } +equations.sub @SubIndex { @Code "sub" symbol } +sub.sym.equations @Index { @Code "sub" symbol (equations) } the object just to its right, and joined them into one object in the form of a subscript. The two objects are called the left and right parameters of {@Code "sub"}, and they may be arbitrary Lout objects. @PP Other symbols of a similar kind include {@Code "sup"} for -sup. @Index { @Code "sup" in equations } +equations. @RawIndex { equations } +equations.sup @SubIndex { @Code "sup" symbol } +sup.equations @Index { @Code "sup" symbol (equations) } superscripting, @Code "over" for built-up fractions, and @Code "from" -over.eq. @Index { @Code "over" in equations } -from. @Index { @Code "from" in equations } -to. @Index { @Code "to" in equations } +equations. @RawIndex { equations } +equations.over @SubIndex { @Code "over" symbol } +over.equations @Index { @Code "over" symbol (equations) } +equations. @RawIndex { equations } +equations.from @SubIndex { @Code "from" symbol } +from.equations @Index { @Code "from" symbol (equations) } +equations. @RawIndex { equations } +equations.to @SubIndex { @Code "to" symbol } +to.equations @Index { @Code "to" symbol (equations) } and @Code "to" for the lower and upper limits of sums, products, etc. These symbols may be used together to produce complicated equations very easily: @@ -73,8 +83,12 @@ Here @Code "sum" is just the @Eq { summation } symbol; @Code "from" and @Code "to" do all the work of placing the limits. They are quite independent, so either or both may be omitted. To get a superscript directly over a subscript, use the @Code "supp" and @Code "on" symbols: -supp. @Index { @Code "supp" in equations } -on. @Index { @Code "on" in equations } +equations. @RawIndex { equations } +equations.supp @SubIndex { @Code "supp" symbol } +supp.equations @Index { @Code "supp" symbol (equations) } +equations. @RawIndex { equations } +equations.on @SubIndex { @Code "on" symbol } +on.equations @Index { @Code "on" symbol (equations) } @ID { @Code "A supp b on a" |7ct @@ -98,6 +112,12 @@ can fix this by using `tucked' subscripts, like this: } @EndList The @Code "tsub" and @Code "ton" symbols are exactly like @Code "sub" +equations. @RawIndex { equations } +equations.tsub @SubIndex { @Code "tsub" symbol } +tsub.equations @Index { @Code "tsub" symbol (equations) } +equations. @RawIndex { equations } +equations.ton @SubIndex { @Code "ton" symbol } +ton.equations @Index { @Code "ton" symbol (equations) } and @Code "on" except for this tucking-in effect. However, the @Code "sub" symbol itself does a certain amount of tucking in; the amount is determined by kerning information in the font files and @@ -121,6 +141,9 @@ There are two possible interpretations for this: @EndList @Code "@Eq" chooses between them in the following way. Every symbol that takes a parameter also has a {@I precedence}, which is a number. For +equations. @RawIndex { equations } +equations.precedence @SubIndex { precedence of symbols } +precedence.equations @Index { precedence of symbols in equations } example, @Code "sup" has precedence 60 and @Code "over" has precedence 54. The symbol with the highest precedence wins the object lying between them, so in the above case the first interpretation is chosen. If two @@ -170,17 +193,19 @@ to have only left associative symbols. The summary at the end of this chapter gives the precedence of every symbol. @PP The @Code matrix symbol {@PageMark matrix} builds an array of objects: -matrix. @Index { @Code "matrix" in equations } +equations. @RawIndex { equations } +equations.matrix @SubIndex { @Code "matrix" symbol } +matrix.equations @Index { @Code "matrix" symbol (equations) } @ID { -@Code { -"matrix" -" atleft { blpar }" -" atright { brpar }" -"{" -" row col x sup 2 col y sup 2 col z sup 2" -" row col x col y col z" -" row col 1 col 1 col 1" -"}" +@Code @Verbatim { +matrix + atleft { blpar } + atright { brpar } +{ + row col x sup 2 col y sup 2 col z sup 2 + row col x col y col z + row col 1 col 1 col 1 +} } ||9ct @Eq { @@ -195,17 +220,29 @@ matrix } } The @Code atleft and @Code atright options place vertically scaled +equations. @RawIndex { equations } +equations.atleft @SubIndex { @Code "atleft" option } +atleft.equations @Index { @Code "atleft" option (equations) } +equations. @RawIndex { equations } +equations.atright @SubIndex { @Code "atright" option } +atright.equations @Index { @Code "atright" option (equations) } versions of their values at each side; if either is omitted the value is taken to be an empty object of zero width by default. Although we have used @Code blpar and @Code brpar here, since the options are vertically scaled to the correct size some people prefer simply -@ID @OneRow @Code { -"matrix" -" atleft { ( }" -" atright { ) }" +@ID @OneRow @Code @Verbatim { +matrix + atleft { ( } + atright { ) } } The right parameter of @Code matrix is the array itself. It must be enclosed in braces, and it is a sequence of rows introduced by +equations. @RawIndex { equations } +equations.row @SubIndex { @Code "row" symbol } +row.equations @Index { @Code "row" symbol (equations) } +equations. @RawIndex { equations } +equations.col @SubIndex { @Code "col" symbol } +col.equations @Index { @Code "col" symbol (equations) } @Code row symbols; each row is a sequence of objects introduced by @Code col symbols. @FootNote { @@ -220,8 +257,20 @@ them in braces. @PP Entries built with the @Code col symbol have their objects centred in the column. Also available are @Code lcol for left-justified entries, +equations. @RawIndex { equations } +equations.lcol @SubIndex { @Code "lcol" symbol } +lcol.equations @Index { @Code "lcol" symbol (equations) } @Code ccol meaning the same as {@Code col}, @Code rcol for +equations. @RawIndex { equations } +equations.ccol @SubIndex { @Code "ccol" symbol } +ccol.equations @Index { @Code "ccol" symbol (equations) } +equations. @RawIndex { equations } +equations.rcol @SubIndex { @Code "rcol" symbol } +rcol.equations @Index { @Code "rcol" symbol (equations) } right-justified entries, and @Code mcol for alignment along column +equations. @RawIndex { equations } +equations.mcol @SubIndex { @Code "mcol" symbol } +mcol.equations @Index { @Code "mcol" symbol (equations) } marks. Each column may contain entries of different kinds, except that @Code mcol does not work well with any other sort. @PP @@ -253,6 +302,10 @@ matrix } To assist in resolving this problem, the @Code "matrix" symbol has a @Code "strut" option, which causes a strut to be inserted into +equations. @RawIndex { equations } +equations.strut @SubIndex { @Code "strut" option } +strut.option. @RawIndex { @Code "strut" option } +strut.option.in.equations @SubIndex { in equations } every row, guaranteeing that every row has height at least equal to the height of the strut. By using @ID @Code { @@ -304,27 +357,51 @@ and, on the right, the result produced: @Rowa A { "pmatrix" } B { "matrix atleft { ( } atright { ) } { M }" } - C { @Eq { pmatrix { M } } } + C { @Eq { pmatrix { M } } +equations. @RawIndex { equations } +equations.pmatrix @SubIndex { @Code "pmatrix" symbol } +pmatrix.equations @Index { @Code "pmatrix" symbol (equations) } +} @Rowa A { "bmatrix" } B { "matrix atleft { blbrack } atright { brbrack } { M }" } - C { @Eq { bmatrix { M } } } + C { @Eq { bmatrix { M } } +equations. @RawIndex { equations } +equations.bmatrix @SubIndex { @Code "bmatrix" symbol } +bmatrix.equations @Index { @Code "bmatrix" symbol (equations) } +} @Rowa A { "brmatrix" } B { "matrix atleft { blbrace } atright { brbrace } { M }" } - C { @Eq { brmatrix { M } } } + C { @Eq { brmatrix { M } } +equations. @RawIndex { equations } +equations.brmatrix @SubIndex { @Code "brmatrix" symbol } +brmatrix.equations @Index { @Code "brmatrix" symbol (equations) } +} @Rowa A { "fmatrix" } B { "matrix atleft { blfloor } atright { brfloor } { M }" } - C { @Eq { fmatrix { M } } } + C { @Eq { fmatrix { M } } +equations. @RawIndex { equations } +equations.fmatrix @SubIndex { @Code "fmatrix" symbol } +fmatrix.equations @Index { @Code "fmatrix" symbol (equations) } +} @Rowa A { "cmatrix" } B { "matrix atleft { blceil } atright { brceil } { M }" } - C { @Eq { cmatrix { M } } } + C { @Eq { cmatrix { M } } +equations. @RawIndex { equations } +equations.cmatrix @SubIndex { @Code "cmatrix" symbol } +cmatrix.equations @Index { @Code "cmatrix" symbol (equations) } +} @Rowa A { "amatrix" } B { "matrix atleft { blangle } atright { brangle } { M }" } - C { @Eq { amatrix { M } } } + C { @Eq { amatrix { M } } +equations. @RawIndex { equations } +equations.amatrix @SubIndex { @Code "amatrix" symbol } +amatrix.equations @Index { @Code "amatrix" symbol (equations) } +} } For example: @ID { @@ -340,6 +417,9 @@ As this example shows, these symbols are very useful for getting large scaled delimiters around things that aren't necessarily matrices at all. @PP Each of the @Code "@Eq" symbols that takes parameters also has a @Code gap +equations. @RawIndex { equations } +equations.gap @SubIndex { @Code "gap" option } +gap.equations @Index { @Code "gap" option (equations) } option, which controls the amount of space inserted by the symbol: @IL @LI { diff --git a/doc/user/equ_tequ b/doc/user/equ_tequ index bbb1d20..c02782a 100644 --- a/doc/user/equ_tequ +++ b/doc/user/equ_tequ @@ -4,6 +4,7 @@ @Begin @PP There is an alternative version of the @Code "@Eq" symbol that +tex. @RawIndex { @TeX } tex.mathfonts @SubIndex { mathematical fonts } uses fonts taken from the @TeX document formatting system. These fonts are said to produce better-looking @@ -12,6 +13,7 @@ standard @Code "@Eq" symbol. @PP The fonts were converted from @TeX form to PostScript form by Basil K. Malyshev, who has attached a license to them permitting +malyshev @Index { Malyshev, Basil K. } non-commercial use only. This is a much more stringent license than the one attached to Lout itself. For this reason, the files needed to use these @TeX fonts are distributed separately from the @@ -24,10 +26,11 @@ Once these files are installed, you change from the standard absolutely nothing else. @PP Unfortunately, the @TeX fonts are not usually resident on PostScript -printing devices, which means that Lout is obliged to include them in its -PostScript output file. You don't have to do anything to make this -happen, but the cost is fairly large: changing to @Code "@SysInclude { teq }" -increases the size of the PostScript output file by 252 kilobytes. +printing devices, which means that Lout is obliged to include them in +its PostScript output file. You don't have to do anything to make this +happen, but the cost is fairly large: changing to +@Code "@SysInclude { teq }" increases the size of the PostScript +output file by 252 kilobytes. @PP It is possible to gain access to characters in the @TeX fonts that are not accessible directly from {@Code "@Eq"}, mainly diff --git a/doc/user/equ_vert b/doc/user/equ_vert index 1595ed8..95d46a8 100644 --- a/doc/user/equ_vert +++ b/doc/user/equ_vert @@ -5,6 +5,8 @@ @PP Every equation and every object within every equation has an @I axis running through it which is used to position it vertically +equations. @RawIndex { equations } +equations.axis @SubIndex { axis of } axis @Index { axis of equation } with respect to nearby objects. In the Expert's Guide to Lout @Cite { $kingston1995lout.expert } this is called a @I { row mark }, @@ -105,14 +107,20 @@ axis shifted } } To supply these possibilities, the @Code "matrix" symbol and all its variants (@Code "pmatrix" etc.) have two options whose +equations. @RawIndex { equations } +equations.userow @SubIndex { @Code "userow" option } +userow.equations @Index { @Code "userow" option (equations) } +equations. @RawIndex { equations } +equations.shiftdelim @SubIndex { @Code "shiftdelim" option } +shiftdelim.equations @Index { @Code "shiftdelim" option (equations) } values may be {@Code "yes"} or {@Code "no"}: -@ID @Code { -"matrix" -" userow { no }" -" shiftdelim { yes }" -"{" -" ..." -"}" +@ID @Code @Verbatim { +matrix + userow { no } + shiftdelim { yes } +{ + ... +} } The @Code "userow" option determines whether the axis of the matrix will use a row axis; the default is not to, i.e. to @@ -126,6 +134,9 @@ which row's axis to use to make the overall axis. If you do nothing, the first (or only) row's axis becomes the overall axis. To select some other row instead, replace the @Code "row" symbol that precedes the row by {@Code "axisrow"}: +equations. @RawIndex { equations } +equations.axisrow @SubIndex { @Code "axisrow" symbol } +axisrow.equations @Index { @Code "axisrow" symbol (equations) } @ID @Code @Tab vmargin { 0.5vx } hmargin { 1s } diff --git a/doc/user/fmt_head b/doc/user/fmt_head index 31f6d89..3c902a5 100644 --- a/doc/user/fmt_head +++ b/doc/user/fmt_head @@ -74,12 +74,12 @@ the default value of {@Code "@IntroPageNumbers"}. @PP Let's summarize the five options so far by looking at their values in the @Code book setup file, which was used to produce the present document: -@ID @OneRow @Code { -"@PageHeaders { Titles }" -"@PageNumbers { Arabic }" -"@FirstPageNumber { 1 }" -"@IntroPageNumbers { Roman }" -"@IntroFirstPageNumber { 1 }" +@ID @OneRow @Code @Verbatim { +@PageHeaders { Titles } +@PageNumbers { Arabic } +@FirstPageNumber { 1 } +@IntroPageNumbers { Roman } +@IntroFirstPageNumber { 1 } } The remainder of this section goes beyond these basic choices to explain how to change the detailed appearance of page headers @@ -109,36 +109,36 @@ These classifications are quite independent of each other: a page could be a non-intro start odd page, or an intro non-start even page, and so on. This makes eight (@Eq { 2 times 2 times 2 }) possibilities altogether. Depending on the type of document there may also be pages -that Lout will never place a page header or footer on. For example, no page -headers or footers will appear on pages containing part titles in books. +that Lout will never place a page header or footer on (e.g. pages +containing part titles in books). @PP If you choose {@Code "@PageHeaders { None }"}, there are no page headers or footers, so there is nothing more to say. If you choose {@Code "@PageHeaders { Simple }"}, then eight options become relevant for controlling the page headers on each of the eight kinds of pages. Here they are with their default values: -@ID @OneRow @Code { -"@OddTop { @Centre { - @PageNum - } }" -"@EvenTop { @Centre { - @PageNum - } }" -"@StartOddTop { @Null }" -"@StartEvenTop { @Null }" -"@IntroOddTop { @Null }" -"@IntroEvenTop { @Null }" -"@IntroStartOddTop { @Null }" -"@IntroStartEvenTop { @Null }" +@ID @OneRow @Code @Verbatim { +@OddTop { @Centre { - @PageNum - } } +@EvenTop { @Centre { - @PageNum - } } +@StartOddTop { @Null } +@StartEvenTop { @Null } +@IntroOddTop { @Null } +@IntroEvenTop { @Null } +@IntroStartOddTop { @Null } +@IntroStartEvenTop { @Null } } If the word @Code Start is missing from an option name, the option applies to non-start pages; if @Code Intro is missing, it applies to non-intro pages. Another eight options control footers in the same way: -@ID @OneRow @Code { -"@OddFoot { @Null }" -"@EvenFoot { @Null }" -"@StartOddFoot { @Null }" -"@StartEvenFoot { @Null }" -"@IntroOddFoot { @Centre @PageNum }" -"@IntroEvenFoot { @Null }" -"@IntroStartOddFoot { @Centre @PageNum }" -"@IntroStartEvenFoot { @Null }" +@ID @OneRow @Code @Verbatim { +@OddFoot { @Null } +@EvenFoot { @Null } +@StartOddFoot { @Null } +@StartEvenFoot { @Null } +@IntroOddFoot { @Centre @PageNum } +@IntroEvenFoot { @Null } +@IntroStartOddFoot { @Centre @PageNum } +@IntroStartEvenFoot { @Null } } The value of the option is an object which becomes the header or footer. It may be any object, but there are some peculiarities that @@ -197,30 +197,30 @@ odd pages, and so on. A different set of sixteen options applies when @Code "@PageHeaders" is set to @Code Titles or {@Code "NoTitles"}. Here are the eight options for headers, with their default values: -@ID @OneRow @Code { -"@RunningOddTop { @I { @MinorNum @DotSep @MinorTitle }" -" @Right @B @PageNum }" -"@RunningEvenTop { @B @PageNum" -" @Right @I { @MajorNum @DotSep @MajorTitle } }" -"@RunningStartOddTop { @Null }" -"@RunningStartEvenTop { @Null }" -"@RunningIntroOddTop { @Null }" -"@RunningIntroEvenTop { @Null }" -"@RunningIntroStartOddTop { @Null }" -"@RunningIntroStartEvenTop { @Null }" +@ID @OneRow @Code @Verbatim { +@RunningOddTop { @I { @MinorNum @DotSep @MinorTitle } + @Right @B @PageNum } +@RunningEvenTop { @B @PageNum + @Right @I { @MajorNum @DotSep @MajorTitle } } +@RunningStartOddTop { @Null } +@RunningStartEvenTop { @Null } +@RunningIntroOddTop { @Null } +@RunningIntroEvenTop { @Null } +@RunningIntroStartOddTop { @Null } +@RunningIntroStartEvenTop { @Null } } Some options occupy two lines, but only because they are long: as usual, the end of a line is the same as one space. Here are the options for footers: -@ID @OneRow @Code { -"@RunningOddFoot { @Null }" -"@RunningEvenFoot { @Null }" -"@RunningStartOddFoot { @Centre { Bold 0.8f } @Font @PageNum }" -"@RunningStartEvenFoot { @Centre { Bold 0.8f } @Font @PageNum }" -"@RunningIntroOddFoot { @Right @PageNum }" -"@RunningIntroEvenFoot { @PageNum }" -"@RunningIntroStartOddFoot { @Null }" -"@RunningIntroStartEvenFoot { @Null }" +@ID @OneRow @Code @Verbatim { +@RunningOddFoot { @Null } +@RunningEvenFoot { @Null } +@RunningStartOddFoot { @Centre { Bold 0.8f } @Font @PageNum } +@RunningStartEvenFoot { @Centre { Bold 0.8f } @Font @PageNum } +@RunningIntroOddFoot { @Right @PageNum } +@RunningIntroEvenFoot { @PageNum } +@RunningIntroStartOddFoot { @Null } +@RunningIntroStartEvenFoot { @Null } } All these options are similar to the earlier ones, in providing one option for each of the eight kinds of pages. The names are the same diff --git a/doc/user/fmt_marg b/doc/user/fmt_marg index c1fdcef..a938670 100644 --- a/doc/user/fmt_marg +++ b/doc/user/fmt_marg @@ -4,8 +4,8 @@ @Begin @PP There are six options for setting the top and bottom margins on each -margins. @RawIndex { margins } -margins.in.pages @SubIndex { in pages } +margin.options @RawIndex { margin options } +margin.options.in.pages @SubIndex { in pages } top.margin @Index @Code "@TopMargin" foot.margin @Index @Code "@FootMargin" odd.left.margin @Index @Code "@OddLeftMargin" @@ -14,13 +14,13 @@ even.left.margin @Index @Code "@EvenLeftMargin" even.right.margin @Index @Code "@EvenRightMargin" page, and the left and right margins on odd and even pages. Here they are with their default values: -@ID @OneRow @Code { -"@TopMargin { 2.50c }" -"@FootMargin { 2.50c }" -"@OddLeftMargin { 2.50c }" -"@OddRightMargin { 2.50c }" -"@EvenLeftMargin { 2.50c }" -"@EvenRightMargin { 2.50c }" +@ID @OneRow @Code @Verbatim { +@TopMargin { 2.50c } +@FootMargin { 2.50c } +@OddLeftMargin { 2.50c } +@OddRightMargin { 2.50c } +@EvenLeftMargin { 2.50c } +@EvenRightMargin { 2.50c } } When setting these options you must ensure that @ID @Eq { @Code "@OddLeftMargin" + @Code "@OddRightMargin" = @@ -31,11 +31,11 @@ even pages. In addition, four options are provided which add extra left and right margins to the page @I body (that is, everything but the running headers and footers): -@ID @OneRow @Code { -"@OddLeftBodyMargin { 0c }" -"@OddRightBodyMargin { 0c }" -"@EvenLeftBodyMargin { 0c }" -"@EvenRightBodyMargin { 0c }" +@ID @OneRow @Code @Verbatim { +@OddLeftBodyMargin { 0c } +@OddRightBodyMargin { 0c } +@EvenLeftBodyMargin { 0c } +@EvenRightBodyMargin { 0c } } The default is to add no page body margins, as shown. Most people who use page body margins would change only @Code "@OddRightBodyMargin" and @@ -46,12 +46,12 @@ be the same on odd and even pages. Margin notes @PP You can have a box drawn around each page if you wish. Here are the relevant options and their default values: -@ID @OneRow @Code { -"@PageBoxType { None }" -"@PageBoxMargin { 1.00c }" -"@PageBoxLineWidth {}" -"@PageBoxPaint { None }" -"@PageBoxShadow { 0.06c }" +@ID @OneRow @Code @Verbatim { +@PageBoxType { None } +@PageBoxMargin { 1.00c } +@PageBoxLineWidth {} +@PageBoxPaint { None } +@PageBoxShadow { 0.06c } } You get boxes by changing the @Code "@PageBoxType" option: page.box.type @Index @Code "@PageBoxType" @@ -83,10 +83,10 @@ The {@Code "@PageBoxMargin"}, {@Code "@PageBoxLineWidth"}, the page box exactly as the {@Code margin}, {@Code linewidth}, {@Code paint}, and {@Code shadow} options described for other boxes in Section {@NumberOf boxes} do. For example, -@ID @OneRow @Code { -"@PageBoxType { CurveBox }" -"@PageBoxMargin { 1.0c }" -"@PageBoxPaint { grey }" +@ID @OneRow @Code @Verbatim { +@PageBoxType { CurveBox } +@PageBoxMargin { 1.0c } +@PageBoxPaint { grey } } draws a curved box, painted grey, around each page, with a one centimetre margin between its boundary and the page contents. If the @@ -138,13 +138,13 @@ produces something like this around each page: The @Code "@BoundaryMarks" symbol has options for controlling the line width (thickness), the line length, and the gap between the ends of the lines and the corner of the text area: -@ID @OneRow @Code { -"@PageBackground {" -" @BoundaryMarks" -" linewidth { 0.2p }" -" length { 0.5c }" -" gap { 0.5c }" -"}" +@ID @OneRow @Code @Verbatim { +@PageBackground { + @BoundaryMarks + linewidth { 0.2p } + length { 0.5c } + gap { 0.5c } +} } This shows the default values: 0.2 points for line width, 0.5 centimetres for the others. diff --git a/doc/user/fmt_setu b/doc/user/fmt_setu index 0f59b56..991e1f4 100644 --- a/doc/user/fmt_setu +++ b/doc/user/fmt_setu @@ -5,7 +5,7 @@ @PP As mentioned briefly in Section {@NumberOf start}, each Lout document begins with an instruction to include (i.e. to read) a @I { setup file }: -setup.file @Index { setup file } +setup.files. @Index { setup files } sysinclude. @Index @Code "@SysInclude" system.include @Index { system include directory } doc.file @Index { @Code "doc" file } @@ -105,11 +105,13 @@ than we've shown; the display above just shows the first few. You change the overall format of your document by changing these options. @PP -As it stands, the options are all hidden within comments, so the -default values (shown within braces) are in force. To change an -option, delete the @Code "#" and change the value between -braces. For example, to set the document in Helvetica 10 point -font, change the @Code { "@InitialFont" } line to +A @Code "#" causes Lout to ignore that character and the rest of the +line (such ignored parts are called {@I comments} and @Code "#" is +the @I { comment character }). As it stands, then, the options are +all hidden within comments, so their default values (shown within braces +in the comments) are in force. To change an option, delete the @Code "#" +and change the value between braces. For example, to set the document +in Helvetica 10 point font, change the @Code { "@InitialFont" } line to @ID @Code "@InitialFont { Helvetica Base 10p }" We won't go through all the options now, since they are the subject of following sections. @@ -124,15 +126,15 @@ options you can leave the @Code "@OrIfPlain" symbol there and change one or both of the alternative values as you wish. @PP Next comes a similar @Code "@Use" clause, for the DocumentSetup package: -@ID @OneRow @Code { -"@Use { @DocumentSetup" -" # @PageType { A4 @OrIfPlain Other }" -" # @PageWidth { 80s }" -" # @PageHeight { 66f }" -" # @PageOrientation { Portrait }" -" # @PageBackground {}" -" # @TopMargin { 2.5c @OrIfPlain 6f }" -"}" +@ID @OneRow @Code @Verbatim { +@Use { @DocumentSetup + # @PageType { A4 @OrIfPlain Other } + # @PageWidth { 80s } + # @PageHeight { 66f } + # @PageOrientation { Portrait } + # @PageBackground {} + # @TopMargin { 2.5c @OrIfPlain 6f } +} } This one has many options, starting with options for page layout as shown, then going on to figures and tables, tables of @@ -145,28 +147,27 @@ main variation is that in some files, some options are already set. The so that overhead transparencies will have a large font size. However, now comes a third @Code "@Use" clause whose symbol and options depend on the document type. For ordinary documents (i.e. in the @Code "doc" -setup file) this clause is -@ID @OneRow @Code { -"@Use { @OrdinarySetup" -" # @IndexWord { index }" -" # @AppendixWord { appendix }" -" # @SectionNumbers { Arabic }" -" # @AppendixNumbers { UCAlpha }" -" # @SectionHeadingFont { Bold }" -"}" +setup file) this clause is (once again we show just some of the options): +@ID @OneRow @Code @Verbatim { +@Use { @OrdinarySetup + # @IndexWord { index } + # @AppendixWord { appendix } + # @SectionNumbers { Arabic } + # @AppendixNumbers { UCAlpha } + # @SectionHeadingFont { Bold } +} +} +In the @Code slides setup file for overhead transparencies, we find this: +@ID @OneRow @Code @Verbatim { +@Use { @OverheadSetup + # @DateLine { No } + # @ContentsWord { contents } + # @FirstOverheadNumber { 1 } + # @OverheadNumbers { Arabic } + # @TitlePageFont { Helvetica Base 1.5f } + # @OverheadHeadingFont { Bold } + # @OverheadInContents { No } } -Once again this is just some of the options. In the @Code slides -setup file for overhead transparencies, we find this: -@ID @OneRow @Code { -"@Use { @OverheadSetup" -" # @DateLine { No }" -" # @ContentsWord { contents }" -" # @FirstOverheadNumber { 1 }" -" # @OverheadNumbers { Arabic }" -" # @TitlePageFont { Helvetica Base 1.5f }" -" # @OverheadHeadingFont { Bold }" -" # @OverheadInContents { No }" -"}" } In general this third @Code "@Use" clause assigns values to options specific to the document type we are using, whereas the first and diff --git a/doc/user/fmt_size b/doc/user/fmt_size index 8e4a258..04ebb5e 100644 --- a/doc/user/fmt_size +++ b/doc/user/fmt_size @@ -6,11 +6,11 @@ This section explains how to use the setup file options that determine page size and page orientation. Here they are with their default values: page.type @Index @Code "@PageType" -@ID @OneRow @Code { -"@PageType { A4 }" -"@PageWidth {}" -"@PageHeight {}" -"@PageOrientation { Portrait }" +@ID @OneRow @Code @Verbatim { +@PageType { A4 } +@PageWidth {} +@PageHeight {} +@PageOrientation { Portrait } } The usual way to determine the page size is to set the @Code "@PageType" option to the name of the paper you use: diff --git a/doc/user/gra_capt b/doc/user/gra_capt index 089e6e5..6c7e77c 100644 --- a/doc/user/gra_capt +++ b/doc/user/gra_capt @@ -4,7 +4,25 @@ @Begin @PP There are options for placing captions above, below, left, and right of +captions. @RawIndex { captions } captions.graphs @SubIndex { in graphs } +graphs. @RawIndex { graphs (statistical) } +graphs.captions @SubIndex { captions } +graphs.abovecaption @SubIndex { @Code abovecaption option } +abovecaption. @RawIndex { @Code "abovecaption" option } +abovecaption.graph @SubIndex { in graphs } +graphs. @RawIndex { graphs (statistical) } +graphs.belowcaption @SubIndex { @Code belowcaption option } +belowcaption. @RawIndex { @Code "belowcaption" option } +belowcaption.graph @SubIndex { in graphs } +graphs. @RawIndex { graphs (statistical) } +graphs.leftcaption @SubIndex { @Code leftcaption option } +leftcaption. @RawIndex { @Code "leftcaption" option } +leftcaption.graph @SubIndex { in graphs } +graphs. @RawIndex { graphs (statistical) } +graphs.rightcaption @SubIndex { @Code rightcaption option } +rightcaption. @RawIndex { @Code "rightcaption" option } +rightcaption.graph @SubIndex { in graphs } the frame: @ID @OneRow @Code { "@Graph" @@ -34,21 +52,37 @@ what happens if there is no data. @PP There are options for controlling the amount of space between each caption (when non-empty) and the frame. Here they are with their +graphs. @RawIndex { graphs (statistical) } +graphs.abovegap @SubIndex { @Code abovegap option } +abovegap. @RawIndex { @Code "abovegap" option } +abovegap.graphs @SubIndex { in graphs } +graphs. @RawIndex { graphs (statistical) } +graphs.belowgap @SubIndex { @Code belowgap option } +belowgap. @RawIndex { @Code "belowgap" option } +belowgap.graphs @SubIndex { in graphs } +graphs. @RawIndex { graphs (statistical) } +graphs.leftgap @SubIndex { @Code leftgap option } +leftgap. @RawIndex { @Code "leftgap" option } +leftgap.graphs @SubIndex { in graphs } +graphs. @RawIndex { graphs (statistical) } +graphs.rightgap @SubIndex { @Code rightgap option } +rightgap. @RawIndex { @Code "rightgap" option } +rightgap.graphs @SubIndex { in graphs } default values: -@ID @OneRow @Code { -"@Graph" -" abovegap { 0.5 cm }" -" belowgap { 0.5 cm }" -" leftgap { 1.5 cm }" -" rightgap { 0.5 cm }" -"{" -" ..." -"}" +@ID @OneRow @Code @Verbatim { +@Graph + abovegap { 0.5c } + belowgap { 0.5c } + leftgap { 1.5c } + rightgap { 0.5c } +{ + ... +} } This is particularly important in the case of {@Code "leftgap"} (and @Code "rightgap" if @Code rticks is used), because Lout has no idea how wide the ticks and labels attached to the y axis -are; 1.5 cm is just a wild guess and often needs adjustment. On the +are; 1.5c is just a wild guess and often needs adjustment. On the other hand, Lout does know how high the ticks and labels on the x axis are; it allows 1.7 times the current font size for them, and @Code "belowgap" is additional to this. @@ -56,13 +90,17 @@ are; it allows 1.7 times the current font size for them, and When a graph is to be presented as a centred display, it is generally best if the centring is done with respect to the frame alone, not the captions, ticks, and labels. The @Code "hidecaptions" option does this by +graphs. @RawIndex { graphs (statistical) } +graphs.hidecaptions @SubIndex { @Code hidecaptions option } +hidecaptions. @RawIndex { @Code "hidecaptions" option } +hidecaptions.in.graphs @SubIndex { in graphs } making the left and right captions and gaps seem to Lout to have zero width: -@ID @OneRow @Code { -"@Graph" -" hidecaptions { yes }" -"{" -" ..." -"}" +@ID @OneRow @Code @Verbatim { +@Graph + hidecaptions { yes } +{ + ... +} } Actually @Code "yes" has been made the default value, since the vast majority of graphs are centred displays. In the rare cases where diff --git a/doc/user/gra_data b/doc/user/gra_data index 049a644..91f87ad 100644 --- a/doc/user/gra_data +++ b/doc/user/gra_data @@ -4,11 +4,15 @@ @Begin @PP The @Code "@Data" symbol has options for controlling the -data. @Index @Code "@Data" +graphs. @RawIndex { graphs (statistical) } +graphs.data @SubIndex { @Code "@Data" symbol } +data.graph @Index { @Code "@Data" symbol (graphs) } appearance of its data. We have already seen the @Code "points" option, which controls what is printed at each data +graphs. @RawIndex { graphs (statistical) } +graphs.points @SubIndex { @Code points option } +points.graph @Index { @Code "points" option (graphs) } point: -points.graphs @Index { @Code "points" option in graphs } @CD @Tab vmargin { 0.5vx } @Fmta { @Col @Code A ! @Col B ! @Col ! @Col @Code C ! @Col D } @@ -41,20 +45,24 @@ points.graphs @Index { @Code "points" option in graphs } } If the @Code "points" option is omitted or empty, nothing is printed. The symbols are centred over the data point. There is a @Code "symbolsize" +graphs. @RawIndex { graphs (statistical) } +graphs.symbolsize @SubIndex { @Code symbolsize option } +symbolsize.graph @Index { @Code "symbolsize" option (graphs) } option which controls the size (radius) of all these symbols: -symbolsize. @Index { @Code "symbolsize" option in graphs } @ID @OneRow @Code { "@Data" -" symbolsize { 0.15 ft }" +" symbolsize { 0.15f }" } shows the default, 0.15 times the current font size. More precisely, the default value is taken from an option to the @Code "@Graph" symbol, also called {@Code "symbolsize"}. By setting that option you can therefore set the symbol size of all data -points in the graph at once; its default value is {@Code "0.15 ft"}. +points in the graph at once; its default value is {@Code "0.15f"}. @PP The @Code "@Data" symbol also has a @Code "pairs" option which -pairs. @Index { @Code "pairs" option in graphs } +graphs. @RawIndex { graphs (statistical) } +graphs.pairs @SubIndex { @Code pairs option } +pairs.graph @Index { @Code "pairs" option (graphs) } determines how each pair of points is connected. The choices are @Code none (not connected, the default), @Code solid (a solid line), @Code dashed (a dashed line), or @Code dotted (a dotted line). For @@ -97,38 +105,49 @@ first and last dash in each segment will have half the length of the others. @PP A @Code "dashlength" option controls the length of dashes and also the +graphs. @RawIndex { graphs (statistical) } +graphs.dashlength @SubIndex { @Code dashlength option } +dashlength.graph @Index { @Code "dashlength" option (graphs) } separation between dots, and a @Code "linewidth" option controls the +graphs. @RawIndex { graphs (statistical) } +graphs.linewidth @SubIndex { @Code linewidth option } +linewidth.graph @Index { @Code "linewidth" option (graphs) } width (thickness) of the lines and dots: @ID @OneRow @Code { "@Data" -" dashlength { 0.2 ft }" -" linewidth { 0.5 pt }" +" dashlength { 0.2f }" +" linewidth { 0.5p }" "{" " ..." "}" } -This shows the default values, {@Code "0.2 ft"} for @Code "dashlength" -and {@Code "0.5 pt"} (half a point) for {@Code "linewidth"}. Actually +This shows the default values, {@Code "0.2f"} for @Code "dashlength" +and {@Code "0.5p"} (half a point) for {@Code "linewidth"}. Actually the default value for @Code "linewidth" is whatever happens to be already in use, but Lout sets line widths to half a point initially. This option also controls the separation between bars in histograms. @PP The @Code "pairs" option is also used for producing histograms, like +graphs. @RawIndex { graphs (statistical) } +graphs.histograms @SubIndex { histograms } histograms. @Index { histograms } +graphs. @RawIndex { graphs (statistical) } +graphs.yhisto @SubIndex { @Code yhisto option } +yhisto.graph @Index { @Code "yhisto" option (graphs) } this: -@ID @OneRow @Code { -"@Graph" -" hidecaptions { yes }" -" abovecaption { Computer Science 3 Results (1993) }" -" leftcaption { Number of" -"students }" -" belowcaption { Final mark (%) }" -" yextra { 0 cm }" -" ymax { 80 }" -"{" -" @Data pairs { yhisto }" -" { 0 1 10 3 20 2 30 4 40 15 50 60 60 58 70 28 80 15 90 7 100 0 }" -"}" +@ID @OneRow @Code @Verbatim { +@Graph + hidecaptions { yes } + abovecaption { Computer Science 3 Results (1993) } + leftcaption { Number of +students } + belowcaption { Final mark (%) } + yextra { 0c } + ymax { 80 } +{ + @Data pairs { yhisto } + { 0 1 10 3 20 2 30 4 40 15 50 60 60 58 70 28 80 15 90 7 100 0 } +} } which has result @CD @Graph @@ -137,7 +156,7 @@ which has result leftcaption { Number of students } belowcaption { Final mark (%) } - yextra { 0 cm } + yextra { 0c } ymax { 80 } { @Data @@ -150,13 +169,16 @@ these two x values. This means that the very last y value has no effect on the result (however, there must be a last y value anyway). @PP There is an alternative to @Code "yhisto" called {@Code "surfaceyhisto"}: +graphs. @RawIndex { graphs (statistical) } +graphs.surfaceyhisto @SubIndex { @Code surfaceyhisto option } +surfaceyhisto.graph @Index { @Code "surfaceyhisto" option (graphs) } @CD @Graph hidecaptions { yes } abovecaption { Computer Science 3 Results (1993) } leftcaption { Number of students } belowcaption { Final mark (%) } - yextra { 0 cm } + yextra { 0c } ymax { 80 } { @Data @@ -167,39 +189,50 @@ As you can see, @Code "surfaceyhisto" draws just the surface of the histogram, not the descending lines. @PP There are @Code "xhisto" and @Code "surfacexhisto" values of +graphs. @RawIndex { graphs (statistical) } +graphs.xhisto @SubIndex { @Code xhisto option } +xhisto.graph @Index { @Code "xhisto" option (graphs) } +graphs. @RawIndex { graphs (statistical) } +graphs.surfacexhisto @SubIndex { @Code surfacexhisto option } +surfacexhisto.graph @Index { @Code "surfacexhisto" option (graphs) } @Code "pairs" which produce a histogram whose bars are parallel to the x axis. There are also {@Code "filledyhisto" } and {@Code "filledxhisto" } values which produce filled rectangles rather +graphs. @RawIndex { graphs (statistical) } +graphs.filledxhisto @SubIndex { @Code filledxhisto option } +filledxhisto.graph @Index { @Code "filledxhisto" option (graphs) } +graphs. @RawIndex { graphs (statistical) } +graphs.filledyhisto @SubIndex { @Code filledyhisto option } +filledyhisto.graph @Index { @Code "filledyhisto" option (graphs) } than outlined ones: -@ID @OneRow @Code { -"@Graph" -" abovecaption { Fertility rates in some developing countries }" -" xextra { 0 cm }" -" yextra { 0 cm }" -" xmax { 8 }" -" yticks {" -" 1.5 (Turkey) 2.5 (Thailand)" -" 3.5 (Indonesia) 4.5 (Costa Rica)" -" 5.5 (Colombia) 6.5 (Cameroon)" -" 7.5 (Botswana) 8.5 (Bangladesh)" -" }" -" yticklength { 0 cm }" -"{" -" @Data" -" pairs { filledxhisto }" -" { 0 1 3.2 2 2.2 3 3.0 4 3.5 5 2.8 6 5.9 7 4.8 8 5.3 9 }" -"}" +@ID @OneRow @Code @Verbatim { +@Graph + abovecaption { Fertility rates in some developing countries } + xextra { 0c } + yextra { 0c } + xmax { 8 } + yticks { + 1.5 (Turkey) 2.5 (Thailand) + 3.5 (Indonesia) 4.5 (Costa Rica) + 5.5 (Colombia) 6.5 (Cameroon) + 7.5 (Botswana) 8.5 (Bangladesh) + } + yticklength { 0c } +{ + @Data + pairs { filledxhisto } + { 0 1 3.2 2 2.2 3 3.0 4 3.5 5 2.8 6 5.9 7 4.8 8 5.3 9 } +} } produces @CD @Graph - abovecaption { Fertility rates in some developing countries - } - xextra { 0 cm } - yextra { 0 cm } + abovecaption { Fertility rates in some developing countries } + xextra { 0c } + yextra { 0c } xmax { 8 } yticks { 1.5 (Turkey) 2.5 (Thailand) 3.5 (Indonesia) 4.5 (Costa Rica) 5.5 (Colombia) 6.5 (Cameroon) 7.5 (Botswana) 8.5 (Bangladesh) } - yticklength { 0 cm } + yticklength { 0c } { @Data pairs { filledxhisto } @@ -212,10 +245,13 @@ equal to the x value lying between the two y values; this time the very first x value has no effect on the result. @PP The colour of one set of data can be changed with a @Code "colour" +graphs. @RawIndex { graphs (statistical) } +graphs.colour @SubIndex { @Code colour option } +colour.graph @Index { @Code "colour" option (graphs) } option: -@ID @OneRow @Code { -"@Data" -" colour { blue }" +@ID @OneRow @Code @Verbatim { +@Data + colour { blue } } For the complete list of acceptable colours, see Section {@NumberOf colour}. The @Code "colour" option's name may also be @@ -223,6 +259,10 @@ spelt @Code {"color"}. @PP It is also possible to paint the area between the data points and the x axis (or frame if @Code "style" is not {@Code "axes"}), using +graphs. @RawIndex { graphs (statistical) } +graphs.paint @SubIndex { @Code paint option } +paint. @RawIndex { @Code "paint" option } +paint.in.graphs @SubIndex { in graphs } @ID @OneRow @Code { "@Data" " paint { yes }" @@ -234,8 +274,69 @@ data sets. However the points and lines of each data set are drawn after painting that set, so they cannot be hidden under their own paint; and axes and frames are drawn last so that they too are never hidden. @PP +Wherever there is a @Code paint option in Lout's standard packages, +there is a neighbouring @Code texture option. For historical reasons +the @Code paint option of @Code "@Graph" is not quite the same as other +@Code "paint" options, but the @Code "texture" option is available +graphs. @RawIndex { graphs (statistical) } +graphs.texture @SubIndex { @Code texture option } +texture.option. @RawIndex { @Code "texture" option } +texture.option.in.graph @SubIndex { in graphs } +as usual: +@ID @OneRow @Code @Verbatim { +@Graph + yextra { 0c } +{ + @Data + paint { yes } + texture { chessboard angle { 45d } } + { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 } +} +} +produces +@FootNote { +If you can't see any textures here, the fault is probably with your +PostScript viewer. See Section {@NumberOf textures}. +} +@CD @Graph + yextra { 0c } +{ + @Data + paint { yes } + texture { striped angle { 90d } } + { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 } +} +Any value acceptable to the @Code "texture" option of @Code "@Box" +(Section {@NumberOf boxes}) is acceptable here. The @Code "texture" +option will also give a texture to the filled areas of a +{@Code filledxhisto} or {@Code filledyhisto}: +@ID @OneRow @Code @Verbatim { +@Graph + yextra { 0c } +{ + @Data + pairs { filledyhisto } + texture { striped angle { 45d } } + { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 7 0 } +} +} +produces +@CD @Graph + yextra { 0c } +{ + @Data + pairs { filledyhisto } + texture { striped angle { 45d } } + { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 7 0 } +} +If you want the bars to vary in colour or texture, you have to give +multiple @Code "@Data" sets, one for each combination of colour and +texture. +@PP A @Code "dataformat" option is provided for changing the interpretation -dataformat. @Index { @Code "dataformat" option in graphs } +graphs. @RawIndex { graphs (statistical) } +graphs.dataformat @SubIndex { @Code dataformat option } +dataformat.graph @Index { @Code "dataformat" option (graphs) } of the data. Ordinarily, as we know, the numbers are taken to be pairs of x and y coordinates, like this: @ID @OneRow @Code { @@ -253,17 +354,17 @@ interpretation is changed to a sequence of y coordinates only: " y y ... y" "}" } -and x values 1, 2, and so on are inserted automatically, just as though -the original input had been +and x values 1, 2, and so on are inserted automatically, as though +the original input was @ID @OneRow @Code { "@Data" "{" " 1 y 2 y ..." "}" } -There is also {@Code "xonly"}, which inserts y values 1, 2, and so on. The +Similarly, {@Code "xonly"} inserts y values 1, 2, and so on. The default value, {@Code "xandy"}, gives the usual interpretation, and -{@Code "swapxandy"} exchanges adjacent pairs of numbers in the data, so -that the data is interpreted as @E { (y, x) } pairs rather than @E { (x, y) } +{@Code "swapxandy"} exchanges adjacent pairs of numbers: the data +is interpreted as @E { (y, x) } pairs rather than @E { (x, y) } pairs. The layout of data on lines has no effect on the interpretation. @End @Section diff --git a/doc/user/gra_erro b/doc/user/gra_erro index 3c123a3..80a30ba 100644 --- a/doc/user/gra_erro +++ b/doc/user/gra_erro @@ -4,6 +4,10 @@ @Begin @PP Lout normally produces output that will print without mishap on +graphs. @RawIndex { graphs (statistical) } +graphs.errors @SubIndex { errors } +errors. @RawIndex { errors } +errors.in.graphs @SubIndex { in graphs } any PostScript device. However, some of the options of @Code "@Graph" and all of the data and labels are passed through Lout without checking. Any errors in this material will not be detected @@ -27,10 +31,14 @@ has run out of memory. All the data is stored in the printer while the graph is being printed, and it remains there until the end of the current page, when it is discarded and all memory consumed by the graph is reclaimed. If you do run out of memory, one option is to try -@ID @Code { -"@Graph" -" save { yes }" -"..." +graphs. @RawIndex { graphs (statistical) } +graphs.save @SubIndex { @Code save option } +save. @RawIndex { @Code "save" option } +save.in.graphs @SubIndex { in graphs } +@ID @Code @Verbatim { +@Graph + save { yes } +... } This causes the memory used by the graph to be reclaimed as soon as the graph is printed, which might well solve your problem if you have diff --git a/doc/user/gra_func b/doc/user/gra_func index d30e82c..a2471bd 100644 --- a/doc/user/gra_func +++ b/doc/user/gra_func @@ -4,6 +4,8 @@ @Begin @PP @Code "@Graph" offers quite a large selection of mathematical functions, +graphs. @RawIndex { graphs (statistical) } +graphs.mathematical @SubIndex { mathematical functions } mathematical.functions @Index { mathematical functions in graphs } available everywhere that x and y coordinates are required: within the @Code xticks and @Code yticks options, within the points within @@ -26,36 +28,36 @@ For plotting functions there are three looping symbols, {@Code "xloop"}, {@Code "yloop"}, and {@Code "zloop"}. For example, the following plots the two functions @Eq { y = 2 } and @Eq { y = sqrt { pi x "/" 4 } + 1 } for @Eq { x } from 10 to 500: -@ID @OneRow @Code { -"-2p @Font @Graph" -" style { axes }" -" xorigin { 0 }" -" yorigin { 0 }" -" width { 8 cm }" -" xticks { 10@ 50@ 100@ 200@ 500@ }" -" objects { @NE at { 300 2 } @I { Exponential }" -" @SE at { 300 sqrt { pi*300/4 } + 1 } @I { Uniform } }" -" belowcaption { @I n }" -" belowgap { 0 cm }" -" leftcaption { Right shell nodes }" -"{" -" @Data points { filledcircle }" -" { 10 1.97 50 2.01 100 2.00 200 2.0 500 2.00 }" -"" -" @Data points { filledcircle }" -" { 10 3.53 50 7.45 100 9.32 200 13.41 500 21.63 }" -"" -" @Data pairs { dashed }" -" { 10 2 500 2 }" -"" -" @Data pairs { dashed }" -" {" -" xloop from { 10 } to { 500 } by { 20 } do" -" {" -" x sqrt { pi*x / 4 } + 1" -" }" -" }" -"}" +@ID -1px @Break @OneRow @Code @Verbatim { +-2p @Font @Graph + style { axes } + xorigin { 0 } + yorigin { 0 } + width { 8c } + xticks { 10@ 50@ 100@ 200@ 500@ } + objects { @NE at { 300 2 } @I { Exponential } + @SE at { 300 sqrt { pi*300/4 } + 1 } @I { Uniform } } + belowcaption { @I n } + belowgap { 0c } + leftcaption { Right shell nodes } +{ + @Data points { filledcircle } + { 10 1.97 50 2.01 100 2.00 200 2.0 500 2.00 } + + @Data points { filledcircle } + { 10 3.53 50 7.45 100 9.32 200 13.41 500 21.63 } + + @Data pairs { dashed } + { 10 2 500 2 } + + @Data pairs { dashed } + { + xloop from { 10 } to { 500 } by { 20 } do + { + x sqrt { pi*x / 4 } + 1 + } + } +} } The @Code "do" option of @Code xloop is replicated repeatedly with each occurrence of @Code x replaced by 10, 30, 50, ... up to 490. The @@ -67,14 +69,14 @@ pp. 15--33 (1985). } style { axes } xorigin { 0 } yorigin { 0 } - width { 8 cm } + width { 8c } xticks { 10@ 50@ 100@ 200@ 500@ } objects { @NE at { 300 2 } @I { Exponential } @SE at { 300 sqrt { pi*300/4 } + 1 } @I { Uniform } } belowcaption { @I n } - belowgap { 0 cm } + belowgap { 0c } leftcaption { Right shell nodes } { @Data points { filledcircle } @@ -101,11 +103,11 @@ the illusion of a smooth curve quite well. There is also an @Code "if" symbol which produces alternative results, depending on whether a condition evaluates to @Code "true" or {@Code"false"}: -@ID @OneRow @Code { -"xloop from { -5 } to { +5 } by { 0.2 } do" -"{" -" if cond { abs { x } > 0.1 } then { x 1/x } else {}" -"}" +@ID @OneRow @Code @Verbatim { +xloop from { -5 } to { +5 } by { 0.2 } do +{ + if cond { abs { x } > 0.1 } then { x 1/x } else {} +} } This plots the function @Eq { y = 1 "/" x }, skipping points near zero. Actually the @Code "else" part could be omitted since its default @@ -113,13 +115,13 @@ value is empty. @PP Adventurous users might enjoy nesting a @Code "yloop" or @Code "zloop" within an {@Code "xloop"}, or using loops to generate ticks, like this: -@ID @OneRow @Code { -"xticks {" -" xloop from { 0 } to { 20 } do" -" {" -" x if cond { x mod 5 = 0 } then { @ }" -" }" -"}" +@ID @OneRow @Code @Verbatim { +xticks { + xloop from { 0 } to { 20 } do + { + x if cond { x mod 5 = 0 } then { @ } + } +} } The missing @Code "by" option defaults to 1, so this produces x ticks at 0, 1, 2, ..., 20, with labels at 0, 5, 10, 15, and 20. It is quite all @@ -129,25 +131,25 @@ final result obeys the rules of Section {@NumberOf ticks}. You can define your own functions using Lout definitions, placed in your @Code "mydefs" file as explained in Section {@NumberOf definitions}. Here is an example of a function definition: -@ID @OneRow @Code { -"import @Graph @Data" -"def @Tan" -" precedence 40" -" right x" -"{" -" sin x / cos x" -"}" +@ID @OneRow @Code @Verbatim { +import @Graph @Data +def @Tan + precedence 40 + right x +{ + sin x / cos x +} } This defines a function called @Code "@Tan" which implements the trigonometric tangent function. It may then be used in expressions just like any other function: -@ID @OneRow @Code { -"@Data {" -" yloop from { 0 } to { 0.95 } by { 0.05 } do" -" {" -" y @Tan { y / pi }" -" }" -"}" +@ID @OneRow @Code @Verbatim { +@Data { + yloop from { 0 } to { 0.95 } by { 0.05 } do + { + y @Tan { y / pi } + } +} } Following is a detailed explanation. @PP diff --git a/doc/user/gra_keys b/doc/user/gra_keys index 089139a..616626b 100644 --- a/doc/user/gra_keys +++ b/doc/user/gra_keys @@ -4,23 +4,66 @@ @Begin @PP A @I key to a graph is an explanation of what each data set -key. @Index { key in graph } +graphs. @RawIndex { graphs (statistical) } +graphs.keys @SubIndex { keys } +keys.graph @Index { keys in graphs } represents. To assist you in constructing a key, some extra symbols are provided in addition to {@Code "@Graph"}: -graph.cross @Index @Code "@GraphCross" -graph.plus @Index @Code "@GraphPlus" -graph.square @Index @Code "@GraphSquare" -graph.filled.square @Index @Code "@GraphFilledSquare" -graph.diamond @Index @Code "@GraphDiamond" -graph.filled.diamond @Index @Code "@GraphFilledDiamond" -graph.circle @Index @Code "@GraphCircle" -graph.filled.circle @Index @Code "@GraphFilledCircle" -graph.triangle @Index @Code "@GraphTriangle" -graph.filled.triangle @Index @Code "@GraphFilledTriangle" -graph.noline @Index @Code "@GraphNoLine" -graph.solid @Index @Code "@GraphSolid" -graph.dashed @Index @Code "@GraphDashed" -graph.dotted @Index @Code "@GraphDotted" +graphs. @RawIndex { graphs (statistical) } +graphs.graphcross @SubIndex { @Code "@GraphCross" symbol } +{ graphacross } @Index { @Code "@GraphCross" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphplus @SubIndex { @Code "@GraphPlus" symbol } +{ graphaplus } @Index { @Code "@GraphPlus" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphsquare @SubIndex { @Code "@GraphSquare" symbol } +{ graphasquare } @Index { @Code "@GraphSquare" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphfilled.square @SubIndex { @Code "@GraphFilledSquare" symbol } +{ graphafilled.square } @Index { @Code "@GraphFilledSquare" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphdiamond @SubIndex { @Code "@GraphDiamond" symbol } +{ graphadiamond } @Index { @Code "@GraphDiamond" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphfilled.diamond @SubIndex { @Code "@GraphFilledDiamond" symbol } +{ graphafilled.diamond } @Index { @Code "@GraphFilledDiamond" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphcircle @SubIndex { @Code "@GraphCircle" symbol } +{ graphacircle } @Index { @Code "@GraphCircle" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphfilled.circle @SubIndex { @Code "@GraphFilledCircle" symbol } +{ graphafilled.circle } @Index { @Code "@GraphFilledCircle" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphtriangle @SubIndex { @Code "@GraphTriangle" symbol } +{ graphatriangle } @Index { @Code "@GraphTriangle" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphfilled.triangle @SubIndex { @Code "@GraphFilledTriangle" symbol } +{ graphafilled.triangle } @Index { @Code "@GraphFilledTriangle" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphnoline @SubIndex { @Code "@GraphNoLine" symbol } +{ graphanoline } @Index { @Code "@GraphNoLine" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphsolid @SubIndex { @Code "@GraphSolid" symbol } +{ graphasolid } @Index { @Code "@GraphSolid" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphdashed @SubIndex { @Code "@GraphDashed" symbol } +{ graphadashed } @Index { @Code "@GraphDashed" symbol (graphs) } + +graphs. @RawIndex { graphs (statistical) } +graphs.graphdotted @SubIndex { @Code "@GraphDotted" symbol } +{ graphadotted } @Index { @Code "@GraphDotted" symbol (graphs) } @ID @Tab @Fmta { @Col @Code A ! @Col B ! @Col @Code C ! @Col D } { @@ -66,14 +109,16 @@ graph.dotted @Index @Code "@GraphDotted" These extra symbols may be used anywhere in your document except within the right parameter of {@Code "@Graph"}; they are commonly used within the caption options of {@Code "@Graph"}: -@ID @OneRow @Code { -"@Graph" -" rightcaption {" -"@GraphPlus @GraphSolid @GraphPlus Boston" -"@GraphPlus @GraphDashed @GraphPlus New York" -"@GraphPlus @GraphDotted @GraphPlus Philadelphia" -"}" +@ID @OneRow @Code @Verbatim { +@Graph + rightcaption { +@GraphPlus @GraphSolid @GraphPlus Boston +@GraphPlus @GraphDashed @GraphPlus New York +@GraphPlus @GraphDotted @GraphPlus Philadelphia +} } +(You can also use them within the @Code objects option, which +is the way to place your key within the graph itself.) Recall that unlike the other captions, @Code rightcaption is set using the @Code "lines @Break" style rather than {@Code "clines @Break"} (Section {@NumberOf captions}). Adding this caption to the graph @@ -96,9 +141,9 @@ from Section {@NumberOf data}, the complete result is } The first eight symbols have a @Code "symbolsize" option with the -usual meaning and the usual default value ({@Code "0.15 ft"}). The +usual meaning and the usual default value ({@Code "0.15f"}). The last four symbols have @Code "dashlength" and @Code "linewidth" options -with the usual default values, {@Code "0.2 ft"} and {@Code "0.5 pt"} +with the usual default values, {@Code "0.2f"} and {@Code "0.5p"} respectively, and a @Code "length" option, which determines the length -of the line drawn by each symbol; its default value is {@Code "1.0 ft"}. +of the line drawn by each symbol; its default value is {@Code "1.0f"}. @End @Section diff --git a/doc/user/gra_over b/doc/user/gra_over index 1b9653a..5bffe08 100644 --- a/doc/user/gra_over +++ b/doc/user/gra_over @@ -9,7 +9,10 @@ symbol, with their values enclosed in braces; they may appear in any order, and if omitted are assigned some sensible default value. @PP There is a @Code "style" option for controlling the overall style of the -style.graph @Index { @Code "style" option of @Code "@Graph" } +graphs. @RawIndex { graphs (statistical) } +graphs.style @SubIndex { @Code style option } +style. @RawIndex { @Code "style" option } +style.in.graphs @SubIndex { in graphs } 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 @@ -20,33 +23,39 @@ 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: -@ID @OneRow @Code { -"-2p @Font @Graph" -" style { axes }" -" xorigin { 0 }" -" yorigin { 0 }" -" width { 12 cm }" -" height { 7 cm }" -" leftcaption { 90d @Rotate { counts (%) } }" -" leftgap { 1.0 cm }" -" belowcaption { time (min) }" -" belowgap { 0 cm }" -"{" -" @Data" -" points { filledsquare }" -" pairs { solid }" -" { 0 0.0 1 4.8 2 7.0 3 15.2 4 19.8 5 20.0 6 21.0 7 25.0" -" 10 29.5 15 31.2 20 35.0 30 40.0 60 50.8" -" }" -"" -" @Data" -" points { square }" -" pairs { solid }" -" {" -" 0 0.0 1 3.7 1.5 43.1 2 99.1 3 85.6 4 69.1 5 47.0 6 44.1 7 40.8" -" 10 35.0 15 29.4 20 25.0 30 21.1 60 15.5" -" }" -"}" +graphs. @RawIndex { graphs (statistical) } +graphs.xorigin @SubIndex { @Code xorigin option } +xorigin.graph @Index { @Code "xorigin" option (graphs) } +graphs. @RawIndex { graphs (statistical) } +graphs.yorigin @SubIndex { @Code yorigin option } +yorigin.graph @Index { @Code "yorigin" option (graphs) } +@ID @OneRow @Code @Verbatim { +-2p @Font @Graph + style { axes } + xorigin { 0 } + yorigin { 0 } + width { 12c } + height { 7c } + leftcaption { 90d @Rotate { counts (%) } } + leftgap { 1.0c } + belowcaption { time (min) } + belowgap { 0c } +{ + @Data + points { filledsquare } + pairs { solid } + { 0 0.0 1 4.8 2 7.0 3 15.2 4 19.8 5 20.0 6 21.0 7 25.0 + 10 29.5 15 31.2 20 35.0 30 40.0 60 50.8 + } + + @Data + points { square } + pairs { solid } + { + 0 0.0 1 3.7 1.5 43.1 2 99.1 3 85.6 4 69.1 5 47.0 6 44.1 7 40.8 + 10 35.0 15 29.4 20 25.0 30 21.1 60 15.5 + } +} } We have requested a smaller font size for this graph as a whole by preceding it with {@Code "-2p @Font"}, meaning two points smaller, and @@ -56,12 +65,12 @@ resulting graph has an x axis and a y axis instead of a frame, like this: style { axes } xorigin { 0 } yorigin { 0 } - width { 12 cm } - height { 7 cm } + width { 12c } + height { 7c } leftcaption { 90d @Rotate { counts (%) } } - leftgap { 1.0 cm } + leftgap { 1.0c } belowcaption { time (min) } - belowgap { 0 cm } + belowgap { 0c } { @Data points { filledsquare } @@ -91,15 +100,21 @@ and the other would have r ticks (adjacent to the right-hand side of the frame). @PP There are @Code "xlog" and @Code "ylog" options which produce +graphs. @RawIndex { graphs (statistical) } +graphs.xlog @SubIndex { @Code xlog option } +xlog.graph @Index { @Code "xlog" option (graphs) } +graphs. @RawIndex { graphs (statistical) } +graphs.ylog @SubIndex { @Code ylog option } +ylog.graph @Index { @Code "ylog" option (graphs) } logarithmic.axes @Index { logarithmic axes in graphs } logarithmic x and y axes: -@ID @OneRow @Code { -"@Graph" -" xlog { 10 }" -" ylog { 10 }" -"{" -" ..." -"}" +@ID @OneRow @Code @Verbatim { +@Graph + xlog { 10 } + ylog { 10 } +{ + ... +} } The value is the base of the logarithm, usually 10 or 2, or {@Code none} (the default) meaning not logarithmic. Logarithms @@ -110,14 +125,22 @@ x ticks, or {@Code "xorigin"} or {@Code "xmin"} options; and similarly for {@Code "ylog"}. @PP There are @Code "width" and @Code "height" options for setting the size +graphs. @RawIndex { graphs (statistical) } +graphs.width @SubIndex { @Code width option } +width. @RawIndex { @Code "width" option } +width.in.graphs @SubIndex { in graphs } +graphs. @RawIndex { graphs (statistical) } +graphs.height @SubIndex { @Code height option } +height. @RawIndex { @Code "height" option } +height.in.graphs @SubIndex { in graphs } of the total area enclosed: -@ID @OneRow @Code { -"@Graph" -" width { 6.0 cm }" -" height { 4.0 cm }" -"{" -" ..." -"}" +@ID @OneRow @Code @Verbatim { +@Graph + width { 6.0c } + height { 4.0c } +{ + ... +} } This shows the default width and height, six centimetres and four centimetres. These lengths and others discussed below can be specified @@ -126,39 +149,48 @@ for the details). @PP Within the frame or axes, a small margin is kept free of data points. The size of this margin is controlled by @Code "xextra" and @Code "yextra" +graphs. @RawIndex { graphs (statistical) } +graphs.xextra @SubIndex { @Code xextra option } +xextra.graph @Index { @Code "xextra" option (graphs) } +graphs. @RawIndex { graphs (statistical) } +graphs.yextra @SubIndex { @Code yextra option } +yextra.graph @Index { @Code "yextra" option (graphs) } options: -@ID @OneRow @Code { -"@Graph" -" xextra { 0.5 cm }" -" yextra { 0.5 cm }" -"{" -" ..." -"}" +@ID @OneRow @Code @Verbatim { +@Graph + xextra { 0.5c } + yextra { 0.5c } +{ + ... +} } -Setting @Code "xextra" to @Code "0.5 cm" (the default value if the +Setting @Code "xextra" to @Code "0.5c" (the default value if the @Code style option is {@Code frame}) means that the smallest x value will be placed 0.5 centimetres to the right of the left boundary, and the largest will be placed 0.5 centimetres to the left of the right -boundary. It is quite safe to set @Code "xextra" to @Code "0 cm" if +boundary. It is quite safe to set @Code "xextra" to @Code "0c" if desired, and indeed this is the default value when @Code style is {@Code axes} or {@Code none}. The @Code "yextra" option works in exactly the same way for y values. @PP The @Code "xdecreasing" option plots the x values in decreasing order +graphs. @RawIndex { graphs (statistical) } +graphs.xdecreasing @SubIndex { @Code xdecreasing option } +xdecreasing.graph @Index { @Code "xdecreasing" option (graphs) } instead of increasing: -@ID @Code { -"@Graph" -" xdecreasing { yes }" -" abovecaption { New South Wales road deaths, 1960--1990" -"(fatalities per 100 million vehicle km) }" -"{" -" @Data" -" points { plus }" -" pairs { dashed }" -" {" -" 1963 5.6 1971 4.3 1976 3.7 1979 3.4 1982 2.9 1985 2.3 1988 2.0" -" }" -"}" +@ID @Code @Verbatim { +@Graph + xdecreasing { yes } + abovecaption { New South Wales road deaths, 1960--1990 +(fatalities per 100 million vehicle km) } +{ + @Data + points { plus } + pairs { dashed } + { + 1963 5.6 1971 4.3 1976 3.7 1979 3.4 1982 2.9 1985 2.3 1988 2.0 + } +} } produces @CD @Graph @@ -175,5 +207,8 @@ produces } The value of @Code "xdecreasing" should be either @Code "no" (the default value) or {@Code "yes"}. A similar @Code "ydecreasing" option does the same +graphs. @RawIndex { graphs (statistical) } +graphs.ydecreasing @SubIndex { @Code ydecreasing option } +ydecreasing.graph @Index { @Code "ydecreasing" option (graphs) } thing to the y axis. @End @Section diff --git a/doc/user/gra_plac b/doc/user/gra_plac index 7084eb2..b184ed5 100644 --- a/doc/user/gra_plac +++ b/doc/user/gra_plac @@ -7,15 +7,18 @@ As we have just seen, the repertoire of symbols that @Code "@Data" is able to place on the graph is quite limited. However, there is a way to place any number of arbitrary Lout objects anywhere on the graph, using the @Code objects option to the @Code "@Graph" symbol: -@ID @OneRow @Code { -"@Graph" -" objects {" -" @CTR at {2.5 6.0} @Eq { y = x sup 2 }" -" @CTR at {4.5 7.0} @Eq { y = x sup 3 }" -" }" +graphs. @RawIndex { graphs (statistical) } +graphs.objects @SubIndex { @Code objects option } +objects.graph @Index { @Code "objects" option (graphs) } +@ID @OneRow @Code @Verbatim { +@Graph + objects { + @CTR at {2.5 6.0} @Eq { y = x sup 2 } + @CTR at {4.5 7.0} @Eq { y = x sup 3 } + } } where we have used the @Code "@Eq" symbol from Chapter {@NumberOf equations} -twice to place two equations onto the graph at the points {@Code "2.5 6.0"} +to place two equations onto the graph at the points {@Code "2.5 6.0"} and {@Code "4.5 7.0"} respectively. An example result appears in the next section. @PP @@ -28,8 +31,8 @@ it over the point. By `to the northwest' we mean that the object's bottom right corner coincides with the point, and similarly for the other symbols. @PP Each of these symbols has a @Code "margin" option which enlarges the -object by adding a margin around it before placing it: -@ID @Code "@NW at {2.5 6.0} margin { 0.3 ft } @Eq { y = x sup 2 }" +object by adding a margin: +@ID @Code "@NW at {2.5 6.0} margin { 0.3f } @Eq { y = x sup 2 }" shows the default value, 0.3 times the current font size. As the margin is increased, the object moves further away from the point. @PP diff --git a/doc/user/gra_summ b/doc/user/gra_summ index 8039440..8506023 100644 --- a/doc/user/gra_summ +++ b/doc/user/gra_summ @@ -4,8 +4,10 @@ @Begin @PP The options to the @Code "@Graph" symbol, their default values, and +graphs. @RawIndex { graphs (statistical) } +graphs.summary @SubIndex { summary of all options } their possible values are: -@ID -2.1px @Break -1p @Font @Tab +@ID -2.5px @Break -1p @Font @Tab hmargin { 0.15c } @Fmta { @Col @Code { " "A } ! @Col @Code "{" ! @Col @Code B ! @Col @Code "}" ! @Col ! @Col ! @Col C } @@ -19,20 +21,20 @@ their possible values are: C { {@Code frame}, {@Code axes}, or {@Code none} } @Rowa A { width } - B { 6.0 cm } + B { 6.0c } C { any @I distance } @Rowa A { height } - B { 4.0 cm } + B { 4.0c } C { any @I distance } @Rowa A { xextra } - B { 0.5 cm } - C { any @I distance ({@Code axes} and {@Code none} default is {@Code "0 cm"}) } + B { 0.5c } + C { any @I distance ({@Code axes} and {@Code none} default is {@Code "0c"}) } @Rowa A { yextra } - B { 0.5 cm } - C { any @I distance ({@Code axes} and {@Code none} default is {@Code "0 cm"}) } + B { 0.5c } + C { any @I distance ({@Code axes} and {@Code none} default is {@Code "0c"}) } @Rowa A { xdecreasing } B { no } @@ -59,19 +61,19 @@ their possible values are: C { any Lout object } @Rowa A { leftgap } - B { 1.5 cm } + B { 1.5c } C { any @I distance } @Rowa A { rightgap } - B { 0.5 cm } + B { 0.5c } C { any @I distance } @Rowa A { abovegap } - B { 0.5 cm } + B { 0.5c } C { any @I distance } @Rowa A { belowgap } - B { 0.5 cm } + B { 0.5c } C { any @I distance } @Rowa A { hidecaptions } @@ -138,15 +140,15 @@ automatic } automatic } @Rowa A { xticklength } - B { 0.5 ft } + B { 0.5f } C { any @I distance } @Rowa A { yticklength } - B { 0.5 ft } + B { 0.5f } C { any @I distance } @Rowa A { rticklength } - B { 0.5 ft } + B { 0.5f } C { any @I distance } @Rowa A { objects } @@ -174,53 +176,30 @@ automatic } B { no } C { {@Code no} or {@Code yes} } @Rowa + A { texture } + B { solid } + C { any texture from Section {@NumberOf textures} } +@Rowa A { dataformat } B { xandy } C { {@Code xandy}, {@Code yonly}, {@Code xonly}, {@Code swapxandy} } @Rowa A { dashlength } - B { 0.2 ft } + B { 0.2f } C { any @I distance } @Rowa A { linewidth } - B { 0.5 pt } + B { 0.5p } C { any @I distance } @Rowa A { symbolsize } - B { 0.15 ft } + B { 0.15f } C { any @I distance } } @I Number means an ordinary decimal number; @I distance means a number -followed by at least one space followed by any one of the following -units of measurement: -@ID @Tab - vmargin { 0.5vx } - @Fmta { @Col @Code A ! @Col B } -{ -@Rowa - A { cm } - B { centimetres } -@Rowa - A { in } - B { inches } -@Rowa - A { em } - B { Ems (12 ems = 1 inch) } -@Rowa - A { pt } - B { Points (72 points = 1 inch) } -@Rowa - A { ft } - B { @Code "1 ft" is the size of the current font } -@Rowa - A { sp } - B { @Code "1 sp" is the width of the space character in the current font } -@Rowa - A { vs } - B { @Code "1 vs" is the current inter-line spacing } -} -In general, numbers denote x or y values while distances denote lengths -on the printed result. +with a unit of measurement (Section {@NumberOf objects}), such as +@Code { 5c } or {@Code 0.5f}. In general, numbers denote x or y +values while distances denote lengths on the printed result. @PP The minimum plottable x value is the minimum of all the x data, {@Code xticks}, {@Code xorigin}, {@Code xmin}, and {@Code xmax} whenever @@ -248,7 +227,7 @@ the following: } where @I object is an arbitrary Lout object. Each of these nine symbols also has a @Code "margin" option whose value may be any non-negative -distance, with default value {@Code "0.3 ft"}. +distance, with default value {@Code "0.3f"}. @PP The options to the @Code "@Data" symbol, their default values, and their possible values are: @@ -278,6 +257,9 @@ their possible values are: A { paint } C { {@Code no} or {@Code yes} } @Rowa + A { texture } + C { Any texture from Section {@NumberOf textures} } +@Rowa A { dataformat } C { {@Code xandy}, {@Code yonly}, {@Code xonly} } @Rowa diff --git a/doc/user/gra_tick b/doc/user/gra_tick index f6079cf..793390c 100644 --- a/doc/user/gra_tick +++ b/doc/user/gra_tick @@ -4,8 +4,13 @@ @Begin @PP @I Ticks are the short lines that mark off intervals along the axes, and +graphs. @RawIndex { graphs (statistical) } +graphs.ticks @SubIndex { ticks } ticks.graph @Index { ticks in graphs } -labels.graph @Index { labels in graphs } +graphs. @RawIndex { graphs (statistical) } +graphs.labels @SubIndex { labels } +labels. @RawIndex { labels } +labels.in.graphs @SubIndex { in graphs } @I labels are the numbers appearing near the ticks (not to be confused with captions). {@Code "@Graph"} produces ticks and labels automatically with some care, so it is probably best not to worry about them unless the @@ -13,6 +18,15 @@ result is not pleasing, in which case there are options for controlling them. @PP One simple way to control the production of x ticks is with the {@Code xmin}, {@Code xmax}, and {@Code xticksep} options to @Code +graphs. @RawIndex { graphs (statistical) } +graphs.xmin @SubIndex { @Code xmin option } +xmin.graph @Index { @Code "xmin" option (graphs) } +graphs. @RawIndex { graphs (statistical) } +graphs.xmax @SubIndex { @Code xmax option } +xmax.graph @Index { @Code "xmax" option (graphs) } +graphs. @RawIndex { graphs (statistical) } +graphs.xticksep @SubIndex { @Code xticksep option } +xticksep.graph @Index { @Code "xticksep" option (graphs) } "@Graph". For example, @ID @OneRow @Code { "@Graph" @@ -27,7 +41,9 @@ suitable values will be inferred from the data as usual. @PP Alternatively, complete control over the appearance of x ticks and labels is provided by the @Code "xticks" option. For example, -xticks.graph @Index { @Code "xticks" option to @Code "@Graph" } +graphs. @RawIndex { graphs (statistical) } +graphs.xticks @SubIndex { @Code xticks option } +xticks.graph @Index { @Code "xticks" option (graphs) } @ID @OneRow @Code { "@Graph" " xticks { 0@ 5 10@ 15 20@ }" @@ -60,7 +76,7 @@ In fact, the labels inserted automatically when @Code xticks is omitted have exponents when the axis is logarithmic, so @Code xticks is hardly necessary in this example. Anyway the result is @CD @Graph - height { 3 cm } + height { 3c } xlog { 10 } xticks { 1 (1) 10 (10) 100 (10^2) 1000 (10^3) 10000 (10^4) 100000 (10^5) } { @@ -74,17 +90,37 @@ same as omitting {@Code xticks}). @PP Similar options control ticks and labels on the y axis: {@Code "ymin"}, {@Code "ymax"}, {@Code "yticksep"}, and {@Code "yticks"}. There are -yticks.graph @Index { @Code "yticks" option to @Code "@Graph" } +graphs. @RawIndex { graphs (statistical) } +graphs.ymin @SubIndex { @Code ymin option } +ymin.graph @Index { @Code "ymin" option (graphs) } +graphs. @RawIndex { graphs (statistical) } +graphs.ymax @SubIndex { @Code ymax option } +ymax.graph @Index { @Code "ymax" option (graphs) } +graphs. @RawIndex { graphs (statistical) } +graphs.yticksep @SubIndex { @Code yticksep option } +yticksep.graph @Index { @Code "yticksep" option (graphs) } +graphs. @RawIndex { graphs (statistical) } +graphs.yticks @SubIndex { @Code yticks option } +yticks.graph @Index { @Code "yticks" option (graphs) } also @Code "xticklength" and @Code "yticklength" options which set the length of ticks: +graphs. @RawIndex { graphs (statistical) } +graphs.xticklength @SubIndex { @Code xticklength option } +xticklength.graph @Index { @Code "xticklength" option (graphs) } +graphs. @RawIndex { graphs (statistical) } +graphs.yticklength @SubIndex { @Code yticklength option } +yticklength.graph @Index { @Code "yticklength" option (graphs) } @ID @OneRow @Code { "@Graph" -" xticklength { 0.5 ft }" -" yticklength { 0.5 ft }" +" xticklength { 0.5f }" +" yticklength { 0.5f }" } shows the default values, half the current font size in both cases. @PP There is also an {@Code "rticks"} option which is similar to +graphs. @RawIndex { graphs (statistical) } +graphs.rticks @SubIndex { @Code rticks option } +rticks.graph @Index { @Code "rticks" option (graphs) } {@Code "yticks"} except that the ticks it controls appear on the right-hand side of the frame (this option is relevant only when the @Code style option is {@Code frame}). Unlike @Code "xticks" and @@ -98,9 +134,9 @@ y ticks: @Graph style { frame } width { 6c } - height { 8c } - xextra { 0 cm } - yextra { 0 cm } + height { 6c } + xextra { 0c } + yextra { 0c } rightcaption { -90d @Rotate { Precipitation mm } } rightgap { 3.0f } hidecaptions { no } @@ -109,28 +145,28 @@ y ticks: ymin { 0 } ymax { 450 } xticks { } - xticklength { 0 cm } + xticklength { 0c } rticks { 0@ 50@ 100@ 150@ 200@ 250@ 300@ 350@ 400@ 450@ } yticks {} { @Data - pairs { filledyhisto } - colour { blue } - linewidth { 1 pt } + pairs { filledyhisto } + colour { blue } + linewidth { 1 pt } { - 0 340 - 1 410 - 2 430 - 3 340 - 4 290 - 5 175 - 6 140 - 7 125 - 8 110 - 9 100 - 10 85 - 11 175 - 12 0 + 0 340 + 1 410 + 2 430 + 3 340 + 4 290 + 5 175 + 6 140 + 7 125 + 8 110 + 9 100 + 10 85 + 11 175 + 12 0 } } @@ -139,9 +175,9 @@ y ticks: @Graph style { frame } width { 6c } - height { 8c } - xextra { 0 cm } - yextra { 0 cm } + height { 6c } + xextra { 0c } + yextra { 0c } leftcaption { 90d @Rotate { Temperature {@Degree}C } } leftgap { 2.5f } hidecaptions { no } @@ -163,13 +199,13 @@ y ticks: 10.5 (N) 11.5 (D) } - xticklength { 0 cm } + xticklength { 0c } yticks { -30@ -20@ -10@ 0@ 10@ 20@ 30@ 40@ } { @Data - pairs { solid } - colour { red } - linewidth { 1 pt } + pairs { solid } + colour { red } + linewidth { 1 pt } { 0.0 24 1.0 24 @@ -193,8 +229,63 @@ Here the first graph has "rticks { 0@ 50@ 100@ 150@ 200@ 250@ 300@ 350@ 400@ 450@ }" "yticks {}" } -for its ticks. -@PP +for its ticks. This graph uses other features that we have not +come to yet, but anyway its source is: +@ID 0.95 @Scale -1px @Break @OneRow @Code @Verbatim { +@Graph + style { frame } + width { 6c } + height { 6c } + xextra { 0c } + yextra { 0c } + rightcaption { -90d @Rotate { Precipitation mm } } + rightgap { 3.0f } + hidecaptions { no } + xmin { 0 } + xmax { 12 } + ymin { 0 } + ymax { 450 } + xticks { } + xticklength { 0c } + rticks { 0@ 50@ 100@ 150@ 200@ 250@ 300@ 350@ 400@ 450@ } + yticks {} +{ + @Data pairs { filledyhisto } colour { blue } linewidth { 1 pt } + { + 0 340 1 410 2 430 3 340 4 290 5 175 6 140 + 7 125 8 110 9 100 10 85 11 175 12 0 + } +} + +@OverStrike + +@Graph + style { frame } + width { 6c } + height { 6c } + xextra { 0c } + yextra { 0c } + leftcaption { 90d @Rotate { Temperature {@Degree}C } } + leftgap { 2.5f } + hidecaptions { no } + xmin { 0 } + xmax { 12 } + ymin { -30 } + ymax { 50 } + xticks { + 0.5 (J) 1.5 (F) 2.5 (M) 3.5 (A) 4.5 (M) 5.5 (J) + 6.5 (J) 7.5 (A) 8.5 (S) 9.5 (O) 10.5 (N) 11.5 (D) + } + xticklength { 0c } + yticks { -30@ -20@ -10@ 0@ 10@ 20@ 30@ 40@ } +{ + @Data pairs { solid } colour { red } linewidth { 1 pt } + { + 0.0 24 1.0 24 2.0 25 3.0 26 4.0 26 5.0 26 6.0 + 26 7.0 27 8.0 26 9.0 27 10.0 28 11.0 28 12.0 26 + } +} +} Lout has only a hazy idea of how much space is occupied by ticks and labels. Unless @Code "xticks" is empty, Lout allows 1.7 times the current font size below the graph for x ticks and labels, which is diff --git a/doc/user/mydefs b/doc/user/mydefs index 727bb27..6a74278 100644 --- a/doc/user/mydefs +++ b/doc/user/mydefs @@ -145,31 +145,12 @@ } } - def @ShowHMark - named linewidth { 0.015 cm } - named linestyle { dashed } - named dashlength { 0.15 cm } - named paint { light } - right x + def @ShowHMark right x { - @Fig { - @Figure - shape { - @BackEnd @Case { - PostScript @Yield { - -0.3 cm ymark - {xsize ymark} ++ {0.3 cm 0} - } - PDF @Yield { "" # VT: PDF currently has no output - } - } - } - linewidth { linewidth } - linestyle { linestyle } - dashlength { dashlength } - x - } + "-0.3 cm ymark moveto xsize 0.3 cm add ymark lineto" + "[ 0.1 cm ] 0 setdash stroke" + } @Graphic x } def @ZeroWidth right x { @OneCol { |0io x |0io } } @@ -212,3 +193,29 @@ which many will start: `Patriotism is the last refuge of a scoundrel.' 2.7c @Wide @StartLeft x ||0.3c 2.2c @Wide @StartDown x } + + import @BasicSetup + def @TextureSample right x + { + @Box margin { 0i } + x @Texture @Box margin { 2.0f } paint { black } {} + } + + import @BasicSetup + def @XRGBTest right col + { + def @Thing { + @HContract @VContract { 0.9c @Wide 0.5f @High ^/ 0.5f @High } + } + + @HContract { + @Box paint { @Xrgb col } margin { 0i } @Thing + &0.2c + 2.8c @Wide downifneeded @Scale @Code col + } + } + + def @XRGBNoTest + { + @HContract { 0.9c @Wide &0.2c 2.8c @Wide {} } + } diff --git a/doc/user/pie b/doc/user/pie new file mode 100644 index 0000000..cb0fd38 --- /dev/null +++ b/doc/user/pie @@ -0,0 +1,53 @@ +@Chapter + @Title { Pie Graphs } + @Tag { pie } +@Begin +@LP +This chapter describes how to draw pie graphs, using the @Code "@Pie" +piegraphs. @Index { pie graphs } +pie. @Index { @Code "@Pie" symbol } +symbol. For example, +@ID @OneRow -1px @Break @Code @Verbatim { +@Pie +{ + @Slice + weight { 20 } + label { Admin (20%) } + @Slice + weight { 40 } + paint { green } + label { Research (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching (40%) } +} +} +produces the pie graph +@CD @Pie +{ + @Slice + weight { 20 } + label { Admin (20%) } + @Slice + weight { 40 } + paint { green } + label { Research (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching (40%) } +} +This example shows off most of what @Code "@Pie" can do. +# there are many options, but for the most part they offer +# detailed adjustments, not additional features. +@BeginSections +@Include { pie_intr } +@Include { pie_slic } +@Include { pie_over } +@Include { pie_capt } +@Include { pie_labe } +@Include { pie_erro } +@Include { pie_summ } +@EndSections +@End @Chapter diff --git a/doc/user/pie_capt b/doc/user/pie_capt new file mode 100644 index 0000000..ba28c8c --- /dev/null +++ b/doc/user/pie_capt @@ -0,0 +1,111 @@ +@Section + @Title { Captions } + @Tag { pie_capt } +@Begin +@PP +There are options for placing captions left, right, above, and below +captions. @RawIndex { captions } +captions.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.captions @SubIndex { captions } +leftcaption. @RawIndex { @Code "leftcaption" option } +leftcaption.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.leftcaption @SubIndex { @Code "leftcaption" option } +rightcaption. @RawIndex { @Code "rightcaption" option } +rightcaption.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.rightcaption @SubIndex { @Code "rightcaption" option } +abovecaption. @RawIndex { @Code "abovecaption" option } +abovecaption.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.abovecaption @SubIndex { @Code "abovecaption" option } +belowcaption. @RawIndex { @Code "belowcaption" option } +belowcaption.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.belowcaption @SubIndex { @Code "belowcaption" option } +the pie graph, following the pattern of the captions in {@Code "@Graph"}: +@ID @OneRow @Code @Verbatim { +@Pie + leftcaption { At left } + rightcaption { At right } + abovecaption { This appears above } + belowcaption { This appears below } +} +produces +@CD @Pie + leftcaption { At left } + rightcaption { At right } + abovecaption { This appears above } + belowcaption { This appears below } +{ + @Slice + weight { 20 } + label { Admin (20%) } + @Slice + weight { 40 } + paint { green } + label { Research (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching (40%) } +} +The captions may be arbitrary Lout objects, so may include +equations, {@Code "@Rotate"}, and so on. Each caption except +@Code rightcaption is printed in the +@Code "clines @Break" style, which means that multiple lines in one +caption will be centred beneath each other. The @Code rightcaption +option uses the @Code "lines @Break" style, in which the lines are +left justified beneath each other. +@PP +There are options for controlling the amount of space between each +caption and the pie graph. Here they are with their default values: +leftgap. @RawIndex { @Code "leftgap" option } +leftgap.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.leftgap @SubIndex { @Code "leftgap" option } +rightgap. @RawIndex { @Code "rightgap" option } +rightgap.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.rightgap @SubIndex { @Code "rightgap" option } +abovegap. @RawIndex { @Code "abovegap" option } +abovegap.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.abovegap @SubIndex { @Code "abovegap" option } +belowgap. @RawIndex { @Code "belowgap" option } +belowgap.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.belowgap @SubIndex { @Code "belowgap" option } +@ID @OneRow @Code @Verbatim { +@Pie + leftgap { 0.5c } + rightgap { 0.5c } + abovegap { 0.5c } + belowgap { 0.5c } +} +These gaps are inserted only if the corresponding caption is +non-empty. Lout knows exactly where captions are, and leaves +space for them and their gaps, so it would be wrong to attempt +to use the {@Code leftextra}, {@Code rightextra}, {@Code aboveextra}, +and {@Code belowextra} options from Section {@NumberOf pie_over} to +allow for the space occupied by captions. +@PP +When a pie graph is to be presented as a centred display, it is usually +best if the centring is done with respect to the pie alone, not the +captions and labels. The @Code "hidecaptions" option does this by +hidecaptions. @RawIndex { @Code "hidecaptions" option } +hidecaptions.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.hidecaptions @SubIndex { @Code "hidecaptions" option } +making the left and right captions and gaps seem to Lout to have zero +width: +@ID @OneRow @Code @Verbatim { +@Pie + hidecaptions { yes } +} +Actually @Code "yes" has been made the default value, since the vast +majority of pie graphs are centred displays. In the rare cases where +this feature is not wanted (for example, if a pie graph appears as an entry +in a table), use {@Code "hidecaptions { no }"}. +@End @Section diff --git a/doc/user/pie_erro b/doc/user/pie_erro new file mode 100644 index 0000000..fc8ed1c --- /dev/null +++ b/doc/user/pie_erro @@ -0,0 +1,35 @@ +@Section + @Title { Errors } + @Tag { pie_erro } +@Begin +@PP +Lout normally produces output that will print without mishap on +errors. @RawIndex { errors } +errors.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.errors @SubIndex { errors } +any PostScript device. However, some of the options of @Code "@Pie" +and @Code "@Slice" are passed through Lout without checking. Any +errors in this material will not be detected until the file is printed. +@PP +When an error is detected, the offending page is printed up to the +point where the error occurred, with a message nearby describing +the error. Printing of the document is then aborted. The problem +is usually easy to locate since it lies in whatever should have +been printed next. +@PP +Like {@Code "@Diag"} and {@Code "@Graph"}, @Code "@Pie" has a +@Code "save" option which causes the memory used by the pie graph +save. @RawIndex { @Code "save" option } +save.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.save @SubIndex { @Code "save" option } +to be reclaimed as soon as it is printed: +@ID @OneRow @Code @Verbatim { +@Pie + save { yes } +... +} +However @Code "@Pie" uses very little memory and so this option is +probably not going to be needed. +@End @Section diff --git a/doc/user/pie_intr b/doc/user/pie_intr new file mode 100644 index 0000000..9eca4d2 --- /dev/null +++ b/doc/user/pie_intr @@ -0,0 +1,65 @@ +@Section + @Title { Introduction } + @Tag { pie_intr } +@Begin +@PP +The Lout definitions for pie graph formatting are kept in a file called +{@Code "pie"}, which you must include at the start of your document if +pie.file @Index { @Code "pie" setup file } +you want pie graphs, like this: +@ID -1px @Break @OneRow @Code { +"@SysInclude { pie }" +"@SysInclude { doc }" +"@Doc @Text @Begin" +"..." +"@End @Text" +} +Setup files for specialized packages, such as {@Code "pie"}, should be +included before the main setup file. Once this is done, the @Code "@Pie" +symbol used below will then be available for use anywhere within your +document. As usual in Lout, the @Code "@Pie" symbol produces an object +which may appear anywhere at all -- in a centred display, for example, +or in a figure, or as an entry in a table. +@PP +A pie graph is made by a @Code "@Pie" symbol enclosing a sequence of +@Code "@Slice" symbols. These @Code "@Slice" symbols and their options +are the only things that may appear inside the @Code "@Pie" symbol. +@PP +Every option of @Code "@Slice" is also an option of {@Code "@Pie"}. +Giving a value to such an option at @Code "@Pie" will make that +the default value for very {@Code "@Slice"}. For example, +you can write +@ID -1px @Break @OneRow @Code @Verbatim { +@Pie + weight { 20 } +{ + ... +} +} +to give every slice a weight (angular extent) of 20. If all but a +few slices have the same weight, you can still do this, just giving +a @Code weight option to the exceptional slices. +@PP +Furthermore, every option of @Code "@Pie" appears in the setup +file, and giving a value to an option there makes that value the +default value for every @Code "@Pie" in your document. For example, +if you want every slice of every pie to be light red, you can set +the @Code paint option in the setup file to {@Code lightred}, +and all your slices will be painted this colour unless you +override the setup file value by giving @Code paint options to +some pies or slices. +@PP +See Section @NumberOf setup to find out how to make your own copy +of the setup file, perhaps calling it {@Code mypie}, and change +some options within it. Your document would then typically +start like this: +@ID -1px @Break @OneRow @Code { +"@Include { mypie }" +"@SysInclude { doc }" +"@Doc @Text @Begin" +"..." +"@End @Text" +} +and by changing options within file @Code "mypie" you can +affect every pie graph in your document. +@End @Section diff --git a/doc/user/pie_labe b/doc/user/pie_labe new file mode 100644 index 0000000..aca92f9 --- /dev/null +++ b/doc/user/pie_labe @@ -0,0 +1,382 @@ +@Section + @Title { Labels } + @Tag { pie_labe } +@Begin +@PP +labels. @RawIndex { labels } +labels.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.labels @SubIndex { labels } +Labels are short messages printed inside the slices, +identifying them. We've already seen the @Code label +option, in which we place the label, which can be an +arbitrary Lout object. In this section we'll show how +to change the format and position of these labels. +@PP +For changing the format of a label there are four options: +@ID -1px @Break @OneRow @Code @Verbatim { +@Slice + labelfont { -2p } + labelbreak { clines } + labelmargin { 0.2f } + labelformat { @Body } +} +This shows the default values of these options. +@PP +The @Code labelfont option determines the font in which the +labelfont. @RawIndex { @Code "labelfont" options } +labelfont.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.labelfont @SubIndex { @Code "labelfont" option } +label will be printed. The default value shown above calls +for the current font to be used, two points smaller than it +otherwise would have been. Any value acceptable to the +@Code "@Font" symbol from Section {@NumberOf fonts} is +acceptable here, including changing the family and face. +@PP +The @Code labelbreak option determines how paragraph breaking +labelbreak. @RawIndex { @Code "labelbreak" options } +labelbreak.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.labelbreak @SubIndex { @Code "labelbreak" option } +within the label will be carried out. Any value acceptable to +the @Code "@Break" symbol from Section {@NumberOf paras} is +acceptable here. The default value shown above causes each +line of the label to be one line of the result, with each +line centred with respect to the longest line. +@PP +The @Code labelmargin option places a margin around the +labelmargin. @RawIndex { @Code "labelmargin" options } +labelmargin.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.labelmargin @SubIndex { @Code "labelmargin" option } +label. The default value shown makes a margin of width +0.2 times the current font size. This margin has no effect +on the appearance or position of the label (in particular, +it is drawn outside @Code "labelformat" below, not inside). +It is only needed for adjusting the appearance of fingers, +as described as the end of this section. +@PP +The @Code labelformat option allows more radical changes +labelformat. @RawIndex { @Code "labelformat" options } +labelformat.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.labelformat @SubIndex { @Code "labelformat" option } +to the label format. Its value may be an arbitrary +object. Within it, the symbol @Code "@Body" stands for +the value of the @Code "label" option: +@ID -1px @Break @OneRow @Code @Verbatim { +@Slice + labelformat { @ShadowBox @Body } +} +will cause the text of the label to appear within a +shadow box. Of course, we could get this effect by +placing these symbols in the label itself, like this: +@ID -1px @Break @OneRow @Code @Verbatim { +@Slice + label { @ShadowBox { Admin (20%) } } +} +However, like all @Code "@Slice" options, @Code labelformat +may be given to @Code "@Pie" as well, like this: +@ID -1px @Break @OneRow @Code @Verbatim { +@Pie + labelformat { @ShadowBox @Body } +} +and there it affects every label in the pie graph: +@CD @Pie + labelformat { @ShadowBox @Body } +{ + @Slice + weight { 20 } + label { Admin (20%) } + @Slice + weight { 40 } + label { Research (40%) } + @Slice + weight { 40 } + label { Teaching (40%) } +} +When the labels all have the same format, this is much faster +and less error-prone than formatting each label independently, +especially when experimenting with different formats. +@PP +Two options are available for changing the positions of +labels: +@ID -1px @Break @OneRow @Code @Verbatim { +@Slice + labelradius { internal } + labeladjust { 0c 0c } +} +Each label occupies a rectangular area, and these options +determine the position of the centre of the rectangle. +@PP +The @Code labelradius option determines how far the +labelradius.pie @Index { @Code "labelradius" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.labelradius @SubIndex { @Code "labelradius" option } +centre of the label is from the point of the slice +(usually the same as the centre of the pie graph, +but not when the slice is detached). The default value +of {@Code labelradius} shown above, {@Code internal}, +is a synonym for 0.6, so it causes the centre of the label +to appear 60% of the way from the point of the slice to +its outside boundary. The angular position of the label +centre will be halfway around the arc of the slice. No +attempt is made to fit the label into the interior of +the slice; it lands where these rules say irrespective +of what might be overstruck when it does. It is printed +after its slice's outline and paint, so it can't be +hidden by them; but if it strays into the next slice it +will be buried under any paint in that slice. +@PP +For fine adjustments, the @Code labeladjust option +labeladjust. @RawIndex { @Code "labeladjust" options } +labeladjust.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.labeladjust @SubIndex { @Code "labeladjust" option } +may be used to move the label centre any distance in +the x and y directions. For example, +@ID -1px @Break @OneRow @Code @Verbatim { +@Slice + labeladjust { 0.2c -0.1c } +} +will move the label centre 0.2 centimetres further to +the right and 0.1 centimetres down from where it would +otherwise have appeared. +@PP +The recommended procedure for getting internal labels +to look good is to first try them without any adjustment. +Next, consider rearranging the label layout. Our running +example has poorly positioned labels, but they can be +improved just by breaking each label over two lines: +@CD @Pie + # abovecaption { Ideal breakdown of academic workload } + aboveextra { 1f } +{ + @Slice + detach { yes } + weight { 20 } + label { Admin @LLP (20%) } + @Slice + weight { 40 } + paint { green } + label { Research @LLP (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching @LLP (40%) } +} +Finally, the @Code labeladjust option is there as a last resort. +@PP +To get a label outside its slice, use +externallabels.pie @Index { external labels in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.externallabels @SubIndex { external labels } +@ID -1px @Break @OneRow @Code @Verbatim { +@Slice + labelradius { external } +} +Again, @Code external is just a synonym for the number +1.4, meaning that the label centre is to be placed 140% +of the pie chart's radius away from the point of the +slice. It can be replaced by any number. +@PP +Two issues arise when labels are placed externally. +The first issue is that Lout does not know where these labels +are being printed and so cannot leave space for them. +Section {@NumberOf pie_over} has already explained how to +handle this problem using the {@Code leftextra}, +{@Code rightextra}, {@Code aboveextra}, and {@Code belowextra} +options of {@Code "@Pie"}. Our running example, converted +to external labels, might be entered like this: +@ID -1px @Break @OneRow @Code @Verbatim { +@Pie + abovecaption { Ideal breakdown of academic workload } + labelradius { external } + aboveextra { 0.7c } + belowextra { 1.3c } +{ + @Slice + detach { yes } + weight { 20 } + label { Admin @LLP (20%) } + @Slice + weight { 40 } + paint { green } + label { Research @LLP (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching @LLP (40%) } +} +} +which produces this: +@CD @Pie + abovecaption { Ideal breakdown of academic workload } + labelradius { external } + aboveextra { 0.7c } + belowextra { 1.3c } +{ + @Slice + detach { yes } + weight { 20 } + label { Admin @LLP (20%) } + @Slice + weight { 40 } + paint { green } + label { Research @LLP (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching @LLP (40%) } +} +The amount of extra space to add has to be worked out by +experiment. It can help to temporarily remove all +captions and enclose the @Code "@Pie" symbol in a box +with zero margin: +@ID -1px @Break @Code @Verbatim { @Box margin { 0i } @Pie ... } +to show clearly how much space the @Code extra options +are covering. +@PP +The second issue raised by external labels is how to +visually connect each label with its slice, when this +fingers.pie @Index { fingers in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.fingers @SubIndex { fingers } +seems necessary. @Code "@Pie" can do this with short +line segments that we will call {@I fingers}: +@CD @Pie + abovecaption { Ideal breakdown of academic workload } + labelradius { external } + aboveextra { 1.3f } + belowextra { 3f } + finger { yes } +{ + @Slice + detach { yes } + weight { 20 } + label { Admin @LLP (20%) } + @Slice + weight { 40 } + paint { green } + label { Research @LLP (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching @LLP (40%) } +} +These were made by adding @Code "finger { yes }" as +another option to the @Code "@Pie" symbol. +@PP +Each slice has several options which control the +appearance of its own finger. Here is the full set, +showing their default values: +@ID -1px @Break @OneRow @Code @Verbatim { +@Slice + finger { no } + fingerstyle { solid } + fingerdashlength { 0.2f } + fingerwidth { thin } + fingerradius { 0.7 } + fingeradjust { 0c 0c } +} +The @Code "finger" option may be @Code "no" or @Code "yes" +finger.pie @Index { @Code "finger" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.finger @SubIndex { @Code "finger" option } +and determines whether a finger will be drawn or not. +@PP +The {@Code fingerstyle}, {@Code fingerdashlength}, and +{@Code fingerwidth} options are exactly analogous to +fingerstyle.pie @Index { @Code "fingerstyle" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.fingerstyle @SubIndex { @Code "fingerstyle" option } +fingerdashlength.pie @Index { @Code "fingerdashlength" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.fingerdashlength @SubIndex { @Code "fingerdashlength" option } +fingerwidth.pie @Index { @Code "fingerwidth" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.fingerwidth @SubIndex { @Code "fingerwidth" option } +the {@Code outlinestyle}, {@Code outlinedashlength}, and +{@Code outlinewidth} options. They take the same range +of values, and determine the style of the line segment +drawn to make the finger (solid, dashed, etc.). +@PP +The {@Code fingerradius} and {@Code fingeradjust} options +are exactly analogous to the {@Code labelradius} and +{@Code labeladjust} options, except that instead of +determining the position of the centre of the label they +determine the position of the inner endpoint of the +finger. The default values place it 70% of the way +from the point of the slice to its outer edge. The +@I outer endpoint of the finger always terminates on +the bounding box of the label, with the line pointing +through the centre of the label, and this cannot be +changed, although the @Code labelmargin option +(see the start of this section) may be used to decrease +or increase the margin around the label, thus causing +the finger to terminate closer to the label or further away. +@PP +Fingers may have arrowheads on their inner ends: +@ID @OneRow @Code @Verbatim { +@Pie + labelradius { 1.6 } + aboveextra { 2f } + belowextra { 4f } + finger { yes } + fingerarrow { yes } + fingerradius { 1 } +{ + @Slice + detach { yes } + weight { 20 } + label { Admin @LLP (20%) } + @Slice + weight { 40 } + paint { green } + label { Research @LLP (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching @LLP (40%) } +} +} +produces +@CD @Pie + labelradius { 1.6 } + aboveextra { 2f } + belowextra { 4f } + finger { yes } + fingerarrow { yes } + fingerradius { 1 } +{ + @Slice + detach { yes } + weight { 20 } + label { Admin @LLP (20%) } + @Slice + weight { 40 } + paint { green } + label { Research @LLP (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching @LLP (40%) } +} +The point of the arrowhead coincides with the inner +endpoint of the finger, so @Code "fingerradius" would +usually be set to @Code 1 when arrowheads are used. +@PP +Although @Code "@Pie" does not offer the elegant selection +of arrowhead styles of {@Code "@Diag"}, it is possible +to change the length and width of the arrowheads +with these options: +@ID @OneRow @Code @Verbatim { +@Slice + fingerarrowlength { 0.6f } + fingerarrowwidth { 0.45f } +} +This example shows the default values of these options. +These options may of course be given to @Code "@Pie" and +also in the setup file as usual. +@End @Section diff --git a/doc/user/pie_over b/doc/user/pie_over new file mode 100644 index 0000000..2445a05 --- /dev/null +++ b/doc/user/pie_over @@ -0,0 +1,117 @@ +@Section + @Title { Changing the overall appearance of the pie graph } + @Tag { pie_over } +@Begin +@PP +We've already seen that all @Code "@Slice" options may be given +piegraphs. @RawIndex { pie graphs } +piegraphs.overall @SubIndex { overall appearance } +to @Code "@Pie" as well. In addition to those, @Code "@Pie" has +its own options that affect the overall appearance of the pie graph: +@ID -1px @Break @OneRow @Code @Verbatim { +@Pie + radius { 2.5c } + initialangle { 0d } + leftextra { 0c } + rightextra { 0c } + aboveextra { 0c } + belowextra { 0c } +} +This example shows these options with their default values. +@PP +The @Code radius option determines the radius of the pie +radius. @RawIndex { @Code "radius" option } +radius.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.radius @SubIndex { @Code "radius" option } +graph. As shown, the default radius is 2.5 centimetres, giving a diameter +of 5 centimetres. +@PP +The @Code initialangle option determines the angle that the first +initialangle.pie @Index { @Code "initialangle" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.initialangle @SubIndex { @Code "initialangle" option } +slice begins at. Following mathematical convention, the default angle +@Code 0d is directly to the right of the centre of the pie graph, and +as the value of @Code initialangle is increased the initial angle moves +anticlockwise. The slices are placed in anticlockwise order immediately +adjacent to each other. If you need a gap between two slices, use a +slice with no outline, no paint, and no label. +@PP +Lout thinks that the whole pie graph occupies a square space +tightly fitting around the given radius, as we can verify by +drawing a box with zero margin around an example pie graph: +@CD @Box margin { 0i } @Pie +{ + @Slice + weight { 20 } + label { Admin (20%) } + @Slice + weight { 40 } + paint { green } + label { Research (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching (40%) } +} +Detached slices (Section {@NumberOf pie_slic}) and external +labels (Section {@NumberOf pie_labe}) can be printed outside +this square region without Lout's knowledge, and this is +likely to spoil the layout: +@CD @Box margin { 0i } @Pie +{ + @Slice + detach { yes } + weight { 20 } + label { Admin (20%) } + @Slice + weight { 40 } + paint { green } + label { Research (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching (40%) } +} +The {@Code leftextra}, {@Code rightextra}, {@Code aboveextra}, and +leftextra.pie @Index { @Code "leftextra" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.leftextra @SubIndex { @Code "leftextra" option } +rightextra.pie @Index { @Code "rightextra" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.rightextra @SubIndex { @Code "rightextra" option } +aboveextra.pie @Index { @Code "aboveextra" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.aboveextra @SubIndex { @Code "aboveextra" option } +belowextra.pie @Index { @Code "belowextra" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.belowextra @SubIndex { @Code "belowextra" option } +{@Code belowextra} options are used to tell Lout to leave extra +space to the left, right, above, and below, so as to correct these +problems: +@ID -1px @Break @OneRow @Code @Verbatim { +@Pie + aboveextra { 0.7c } +} +We have not added extra space at the right as well, since we prefer +to centre the pie graph horizontally without regard to detached +slices. The result occupies 0.7 cm extra at the top: +@CD @Box margin { 0i } @Pie aboveextra { 0.7c } +{ + @Slice + detach { yes } + weight { 20 } + label { Admin (20%) } + @Slice + weight { 40 } + paint { green } + label { Research (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching (40%) } +} +We'll see these options again when we come to external labels in +Section {@NumberOf pie_labe}. +@End @Section diff --git a/doc/user/pie_slic b/doc/user/pie_slic new file mode 100644 index 0000000..1c8f7d8 --- /dev/null +++ b/doc/user/pie_slic @@ -0,0 +1,203 @@ +@Section + @Title { Changing the appearance of slices } + @Tag { pie_slic } +@Begin +@PP +The @Code "@Slice" symbol has options for controlling the +slice. @Index { @Code "@Slice" symbol (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.slice @SubIndex { @Code "@Slice" symbol } +appearance of the slice it makes: +@ID -1px @Break @OneRow @Code @Verbatim { +@Slice + weight { 10 } + paint { none } + texture { solid } + outlinestyle { solid } + outlinedashlength { 0.2f } + outlinewidth { thin } + detach { no } +} +This example shows the default values of the options. +@PP +The @Code weight option is the weight (angular extent) of +weight.pie @Index { @Code "weight" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.weight @SubIndex { @Code "weight" option } +the slice. By default, the total weight of the complete +pie graph is 100, so a slice of weight 10, say, would occupy +10% of the pie area, or in other words an angular extent +of (10"/"100) @Multiply 360 degrees. You can change the +@I total weight by setting an option to the @Code "@Pie" symbol: +totalweight.pie @Index { @Code "totalweight" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.totalweight @SubIndex { @Code "totalweight" option } +@ID -1px @Break @OneRow @Code @Verbatim { +@Pie + totalweight { 360 } +} +The value 360 would be useful if you wanted your weights to +correspond with degrees. It would be good to get @Code "@Pie" +to add up all the weights of its constituent slices and use +that for the total weight, but problems behind the scenes +prevent this. As it is, if the total weight of all slices +is less than {@Code totalweight}, the leftover angular +extent will be blank; and if it exceeds {@Code totalweight}, +later slices will overstrike earlier ones. +@PP +The @Code paint option defines the colour of the interior +paint. @RawIndex { @Code "paint" option } +paint.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.paint @SubIndex { @Code "paint" option } +of the slice. Any colour acceptable to the {@Code "@Colour"} +symbol (Section {@NumberOf colour}) is allowed, plus the +default value {@Code none}, meaning no paint. As always, +alongside the @Code "paint" option there is a @Code "texture" +texture.option. @RawIndex { @Code "texture" option } +texture.option.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.texture @SubIndex { @Code "texture" option } +option: +@ID -1px @Break @OneRow @Code @Verbatim { +@Pie + paint { grey } +{ + @Slice + weight { 20 } + texture { striped } + label { Admin (20%) } + @Slice + weight { 40 } + texture { striped angle { 45d } } + label { Research (40%) } + @Slice + weight { 40 } + texture { striped angle { 90d } } + label { Teaching (40%) } +} +} +produces +@CD +@Pie + paint { grey } +{ + @Slice + weight { 20 } + texture { striped } + label { Admin (20%) } + @Slice + weight { 40 } + texture { striped angle { 45d } } + label { Research (40%) } + @Slice + weight { 40 } + texture { striped angle { 90d } } + label { Teaching (40%) } +} +Textures might work better in black and white prints. +@PP +The next three options affect the outline drawn around each +slice. The @Code outlinestyle option +outlinestyle. @RawIndex { @Code "outlinestyle" option } +outlinestyle.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.outlinestyle @SubIndex { @Code "outlinestyle" option } +may be {@Code solid} (the default) which +draws a solid line, {@Code dashed} which draws a dashed +line, {@Code cdashed} which draws a dashed line with +half-size dashes at the ends (this often looks better +than {@Code dashed}), @Code "dotted" which draws a dotted line, +and @Code noline which draws no outline at all. The +@Code outlinedashlength option determines the dash length +outlinedashlength. @RawIndex { @Code "outlinedashlength" option } +outlinedashlength.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.outlinedashlength @SubIndex { @Code "outlinedashlength" option } +if @Code outlinestyle is @Code dashed or {@Code cdashed}, and +the distance between dots if @Code outlinestyle is +{@Code dotted}. The length will be varied a little to ensure +that the dashes or dots fit evenly on each segment of the +outline. The @Code "outlinewidth" option determines the width +outlinewidth. @RawIndex { @Code "outlinewidth" option } +outlinewidth.in.pie @SubIndex { in pie graphs } +piegraphs. @RawIndex { pie graphs } +piegraphs.outlinewidth @SubIndex { @Code "outlinewidth" option } +of the outline, or the diameter of the dots if @Code outlinestyle +is {@Code dotted}. +@PP +You can give three values to {@Code outlinestyle}, like this: +@ID -1px @Break @OneRow @Code @Verbatim { +@Pie +{ red @Colour @Slice + weight { 75 } + outlinestyle { dashed cdashed dotted } + label { Bad debts } +} +} +and the first will apply to the first straight segment, +the second to the curved segment, and the third to the +second straight segment: +@CD @Pie +{ red @Colour @Slice + weight { 75 } + outlinestyle { dashed cdashed dotted } + label { Bad debts } +} +There is no option to change the colour of the outline, +but you can change the colour of the whole slice using +the {@Code "@Colour"} symbol from Section {@NumberOf colour} +as shown. It colours the label as well, but you can +fix that by enclosing the contents of your label in +another {@Code "@Colour"} symbol if you need to. +@PP +The @Code detach option pulls its slice radially out of the +detach.pie @Index { @Code "detach" option (pie graphs) } +piegraphs. @RawIndex { pie graphs } +piegraphs.detach @SubIndex { @Code "detach" option } +pie, without affecting any other slice: +@CD @Pie + # abovecaption { Ideal breakdown of academic workload } + aboveextra { 0.7c } +{ + @Slice + detach { yes } + weight { 20 } + label { Admin (20%) } + @Slice + weight { 40 } + paint { green } + label { Research (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching (40%) } +} +is produced by +@ID -1px @Break @OneRow @Code @Verbatim { +@Pie + aboveextra { 0.7c } +{ + @Slice + detach { yes } + weight { 20 } + label { Admin (20%) } + @Slice + weight { 40 } + paint { green } + label { Research (40%) } + @Slice + weight { 40 } + paint { lightred } + label { Teaching (40%) } +} +} +We've used the @Code aboveextra option +(Section {@NumberOf pie_over}) to compensate for Lout's +ignorance of where the slice actually ended up. +The value of @Code detach may be {@Code no} (the +default), {@Code yes}, or any number, which defines +the fraction of the pie radius that the slice is +pulled out by. For example, @Code yes is just another +name for {@Code 0.5}. +@End @Section diff --git a/doc/user/pie_summ b/doc/user/pie_summ new file mode 100644 index 0000000..471567a --- /dev/null +++ b/doc/user/pie_summ @@ -0,0 +1,187 @@ +@Section + @Title { Summary } + @Tag { pie_summ } +@Begin +@PP +Here are the options of the @Code "@Pie" symbol, +piegraphs. @RawIndex { pie graphs } +piegraphs.summary @SubIndex { summary } +with their default values and allowed values: +@ID @Tab + hmargin { 0.15c } + vmargin { 0.47vx } + @Fmta { @Col @Code { " "A } ! @Col @Code "{" ! @Col @Code B ! + @Col @Code "}" ! @Col ! @Col ! @Col C } + @Fmtb { @Col @Code A ! @Col ! @Col ! @Col ! @Col ! @Col ! @Col } +{ +@Rowb + A { "@Pie" } +@Rowa + A { save } + B { no } + C { {@Code no} or {@Code yes} } +@Rowa + A { totalweight } + B { 100 } + C { any positive number } +@Rowa + A { radius } + B { 2.5c } + C { any length } +@Rowa + A { initialangle } + B { 0d } + C { any angle (@Code {90d} etc.) } +@Rowa + A { leftextra } + B { 0c } + C { any length } +@Rowa + A { rightextra } + B { 0c } + C { any length } +@Rowa + A { aboveextra } + B { 0c } + C { any length } +@Rowa + A { belowextra } + B { 0c } + C { any length } +@Rowa + A { leftcaption } + B { } + C { any Lout object } +@Rowa + A { rightcaption } + B { } + C { any Lout object } +@Rowa + A { abovecaption } + B { } + C { any Lout object } +@Rowa + A { belowcaption } + B { } + C { any Lout object } +@Rowa + A { leftgap } + B { 0.5c } + C { any length } +@Rowa + A { rightgap } + B { 0.5c } + C { any length } +@Rowa + A { abovegap } + B { 0.5c } + C { any length } +@Rowa + A { belowgap } + B { 0.5c } + C { any length } +@Rowa + A { hidecaptions } + B { yes } + C { @Code no or @Code yes } +@Rowa + A { weight } + B { 10 } + C { Any positive number } +@Rowa + A { paint } + B { none } + C { @Code none or any colour (Section @NumberOf { colour }) } +@Rowa + A { texture } + B { solid } + C { Any texture (Section @NumberOf { textures }) } +@Rowa + A { outlinestyle } + B { solid } + C { {@Code solid}, @Code {dashed}, @Code {cdashed}, @Code { dotted }, +or @Code { noline } } +@Rowa + A { outlinedashlength } + B { 0.2f } + C { any length } +@Rowa + A { outlinewidth } + B { thin } + C { @Code { thin }, @Code { medium }, @Code { thick }, or any length } +@Rowa + A { detach } + B { no } + C { {@Code no}, {@Code yes}, or any non-negative number } +@Rowa + A { label } + B { } + C { any Lout object } +@Rowa + A { labelfont } + B { -2p } + C { any font as given to @Code "@Font" } +@Rowa + A { labelbreak } + B { clines } + C { any break style as given to @Code "@Break" } +@Rowa + A { labelmargin } + B { 0.2f } + C { any length } +@Rowa + A { labelformat } + B { "@Body" } + C { any Lout object, usually including @Code "@Body" } +@Rowa + A { labelradius } + B { internal } + C { {@Code internal}, {@Code external}, or any positive number } +@Rowa + A { labeladjust } + B { 0c 0c } + C { any point (pair of lengths) } +@Rowa + A { finger } + B { no } + C { @Code no or @Code yes } +@Rowa + A { fingerstyle } + B { solid } + C { {@Code solid}, @Code {dashed}, @Code {cdashed}, @Code { dotted }, +or @Code { noline } } +@Rowa + A { fingerdashlength } + B { 0.2f } + C { any length } +@Rowa + A { fingerwidth } + B { thin } + C { @Code { thin }, @Code { medium }, @Code { thick }, or any length } +@Rowa + A { fingerradius } + B { 0.7 } + C { any positive number } +@Rowa + A { fingeradjust } + B { 0c 0c } + C { a point (pair of lengths) } +@Rowa + A { fingerarrow } + B { no } + C { @Code no or @Code yes } +@Rowa + A { fingerarrowlength } + B { 0.6f } + C { any length } +@Rowa + A { fingerarrowwidth } + B { 0.45f } + C { any length } +} +The options from @Code "weight" downwards are also the complete +set of options of the @Code "@Slice" symbol. The value of an +option is the value given at the @Code "@Slice" symbol, if any; +otherwise, the value at the enclosing @Code "@Pie" is used +if any; if it is not given there, the setup file value is used. +@End @Section diff --git a/doc/user/preface b/doc/user/preface index c694c59..c2d3da1 100644 --- a/doc/user/preface +++ b/doc/user/preface @@ -3,7 +3,7 @@ This User's Guide brings together in one document everything needed for the day-to-day use of Version 3 of the Lout document formatting system. -@IndexBlanks +@IndexLetters @PP There are three other documents describing Lout: the Expert's Guide @Cite { $kingston1995lout.expert }, which you need if you want to add @@ -17,8 +17,8 @@ Lout is distributed free of charge under the GNU Public License. The gnu. @Index { GNU Public License } primary source is directory @ID @Code "ftp://ftp.it.usyd.edu.au/jeff/lout" -in which may be found a gzipped tar file containing the main distribution -(currently {@Code "lout-3.26.tar.gz"}), and various other things including +containing a gzipped tar file of the current version +(currently {@Code "lout-3.27.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 @@ -40,6 +40,7 @@ cherry.l @Index { Cherry, Lorinda L.} eqn. @Index { @Code eqn equation formatter } equation formatter @Cite { $kernighan1975eqn }, and also by Brian K. Reid's Scribe system @Cite { $reid1980scribe }. That +scribe. @RawIndex { Scribe } scribe.influence @SubIndex { influence on Lout } reid.b @Index { Reid, Brian K. } research phase ended in October 1991 with the first public release of Lout. diff --git a/doc/user/prg b/doc/user/prg index 3a862b3..6b64e12 100644 --- a/doc/user/prg +++ b/doc/user/prg @@ -4,6 +4,8 @@ @Begin @LP This chapter describes how to typeset computer program text using Lout +programs. @Index { programs } +computer.programs. @RawIndex { computer programs @I see programs } in conjunction with the @Code prg2lout prg2lout. @Index { @Code prg2lout filter program } @FootNote { @@ -27,11 +29,13 @@ program texts with absolutely no modifications; plus, if you wish, Lout will print keywords in bold, identifiers in italics, add line numbers, etc. @PP At the time of writing, the available programming languages are: -eiffel. @Index { Eiffel program printing } -c. @Index { C and C++ program printing } blue. @Index { Blue program printing } +c. @Index { C and C++ program printing } +eiffel. @Index { Eiffel program printing } +java. @Index { Java program printing } perl. @Index { Perl program printing } pod. @Index { Pod (for Perl) printing } +python. @Index { Python program printing } @CD @Tbl mv { 0.5vx } af { Italic } diff --git a/doc/user/prg_chan b/doc/user/prg_chan index 781e9bb..ae67eea 100644 --- a/doc/user/prg_chan +++ b/doc/user/prg_chan @@ -14,8 +14,11 @@ changing it. For general information about how to make your own setup file, consult Section {@NumberOf setup}. The options that determine the default values are in the @Code "@Use" clause which occupies most of the setup +programs. @RawIndex { programs } +programs.setup @SubIndex { setup files for } +setup.files. @RawIndex { setup files } +setup.files.for.programs @SubIndex { for programs } file. Here is part of the @Code "@Use" clause from {@Code cprint}: -cprint. @Index @Code "@CPSetup" @ID @Code @Tbl mv { 0.5vx } aformat { @Cell A | @Cell B | @Cell C } @@ -96,9 +99,9 @@ symbols, including {@Code "@Box"} and {@Code "@I"}. If you want to use these symbols here, you must include your setup file @I after @Code "@SysInclude { doc }" or whatever, the reverse of the usual arrangement, so that they are defined before Lout reads your setup -file. This reversal is carried out automatically when formatting -programs independently of any document, so you can use these symbols -in a setup file given by a @Code { -S } command line flag. +file. This is always done when formatting programs independently of +any document, so you can use these symbols in a setup file given by +a @Code { -S } command line flag. } If you do use exotic formats, remember that in some programming languages, comments and even strings may occupy more than one line: {@Code "@Box"}, for example, will give a logical but probably unwanted result when diff --git a/doc/user/prg_comm b/doc/user/prg_comm index f059388..dc7374e 100644 --- a/doc/user/prg_comm +++ b/doc/user/prg_comm @@ -4,6 +4,9 @@ @Begin @PP It is possible to embed Lout text inside program comments. How this +programs. @RawIndex { programs } +programs.loutcode @SubIndex { Lout code embedded in } +loutcode.programs @Index { Lout code embedded in programs } is done could in principle vary from language to language, but in every language supported so far it is done by starting off the comment with an @Code "@" character. If the language has several ways to get @@ -19,7 +22,56 @@ for more on this.) Or, to make a heading in an Eiffel program, do this: line.) Other possible uses for this feature include index entries and margin notes. Incredible as it may seem, you can even write @ID @Code "/*@ @CD @Heading { Function @CP { treeprint() } } */" -with a @Code "@CP" symbol and some C code inside the Lout code -inside the C code. You probably can't go further, however, at least -not in C, since that would require a C comment inside a C comment. +with @Code "@CP" and C code inside the Lout code inside the C code. You +probably can't go further, however, at least not in C, since that would +require a C comment inside a C comment. +@PP +It's possible to get quite long Lout insertions, with a bit of +care. For example, here's how to get a filled paragraph of text +into a computer program: +@ID @OneRow @Code @Verbatim { +@Eiffel { +--@@ID ragged @Break { +--@This program is free software; you can redistribute +--@it and"/"or modify it under the terms of the +--@@B { GNU General Public License } as published by +--@the Free Software Foundation; either Version 2, or +--@(at your option) any later version. +--@} + +launch(x: APPLICATION) is + -- launch the application + deferred +} +} +produces +@ID @OneRow @Eiffel { +--@@ID ragged @Break { +--@This program is free software; you can redistribute +--@it and"/"or modify it under the terms of the +--@@B { GNU General Public License } as published by +--@the Free Software Foundation; either Version 2, or +--@(at your option) any later version. +--@} + +launch(x: APPLICATION) is + -- launch the application + deferred +} +This example relies on the fact that @Code prg2lout passes +escape comments like these through to Lout absolutely +untouched. Notice the use of both a display symbol ({@Code "@ID"}) +and a change to the break style ({@Code "ragged @Break"}). If +the change of break style had been omitted, the break +style of the surrounding program, {@Code "lines @Break"}, +would have been applied to the displayed paragraph. The +display symbol is needed because without it the paragraph +would be an integral part of the surrounding program (which +is actually considered by Lout to be one paragraph), making +the @Code "ragged @Break" ineffective since you can't change +the paragraph style in the middle of a paragraph. +@PP +Clearly, use of such escape comments in conjunction with line +numbers is going to be problematic. No promise is made +that the result of doing that will make sense. @End @Section diff --git a/doc/user/prg_embe b/doc/user/prg_embe index cfa84d4..37a5dd2 100644 --- a/doc/user/prg_embe +++ b/doc/user/prg_embe @@ -20,20 +20,20 @@ of the table at the start of this chapter. The program texts within the Lout document are enclosed in braces preceded by the Lout symbol from the third column of the table, like this for the C language: -@ID @OneRow @Code { -"@IndentedDisplay @CP {" -"#include <stdio.h>" -"" -"treeprint(p) /* print tree p recursively */" -"struct tnode *p;" -"{" -" if (p != NULL) {" -" treeprint(p->left);" -" printf(\"%4d %s\\n\", p->count, p->word);" -" treeprint(p->right);" -" }" -"}" -"}" +@ID @OneRow @Code @Verbatim { +@IndentedDisplay @CP { +#include <stdio.h> + +treeprint(p) /* print tree p recursively */ +struct tnode *p; +{ + if (p != NULL) { + treeprint(p->left); + printf(\%4d %s\\n\, p->count, p->word); + treeprint(p->right); + } +} +} } Although computer programs violate the rules of legal Lout input in many ways, these rules are suspended by the {@Code "@CP"}, {@Code "@Eiffel"} etc. symbols, @@ -61,6 +61,10 @@ anywhere. When including a program text within a paragraph, use other languages) to prevent it being broken across two lines, if desired. @PP In cases where the program text has unbalanced braces, it is necessary to +programs. @RawIndex { programs } +programs.braces @SubIndex { braces in } +braces. @RawIndex { braces } +braces.in.program @SubIndex { in program formatting } use the alternative form @Code "@CP @Begin ... @End @CP" (or the equivalent for other languages), so that Lout does not confuse program braces with Lout braces. In that case the program text must not diff --git a/doc/user/prg_erro b/doc/user/prg_erro index a5a19fa..ee4d784 100644 --- a/doc/user/prg_erro +++ b/doc/user/prg_erro @@ -5,6 +5,10 @@ @PP In order to understand the error messages produced by program printing, it is necessary to understand that Lout's first step when +programs. @RawIndex { programs } +programs.errors @SubIndex { errors } +errors. @RawIndex { errors } +errors.in.programs @SubIndex { in program formatting } given a program text is to pass it to the separate {@Code prg2lout} program for analysis. This separate program is the source of most of the error messages associated with program printing. diff --git a/doc/user/prg_form b/doc/user/prg_form index 58b0e37..d76f44e 100644 --- a/doc/user/prg_form +++ b/doc/user/prg_form @@ -4,6 +4,9 @@ @Begin @PP The formfeed (Control-L) character is traditionally taken to be a +programs. @RawIndex { programs } +programs.formfeeds @SubIndex { formfeed characters in } +formfeeds.programs @Index { formfeed characters in programs } request to start a new page. This is explicitly recognized by the formal definition of the C language and many others, which treat this character as white space from a language point of view, with diff --git a/doc/user/prg_lone b/doc/user/prg_lone index 324f79e..950fa05 100644 --- a/doc/user/prg_lone +++ b/doc/user/prg_lone @@ -4,6 +4,9 @@ @Begin @PP Printing of program files independently of any document is accomplished by +programs. @RawIndex { programs } +programs.standalone @SubIndex { stand-alone } +standalone.programs @Index { stand-alone programs } the following Unix pipeline: @ID @Code "prg2lout -l language options files | lout -s > out.ps" where @Code language stands for any one of the programming language diff --git a/doc/user/prg_opti b/doc/user/prg_opti index 0b8dbb6..f48e662 100644 --- a/doc/user/prg_opti +++ b/doc/user/prg_opti @@ -7,28 +7,41 @@ The {@Code "@CP"}, {@Code "@Eiffel"} etc. symbols have a number of options for changing the appearance of the printed program. These options are the same for all symbols, although their default values may vary. The @Code "style" option changes the printing style; its +programs. @RawIndex { programs } +programs.style @SubIndex { @Code "style" option } +style. @RawIndex { @Code "style" option } +style.in.programs @SubIndex { in programs } +programs. @RawIndex { programs } +programs.fixed @SubIndex { @Code "fixed" style } +fixed.programs @Index { @Code "fixed" style (programs) } value may be {@Code "fixed"} (fixed-width font), {@Code "varying"} +programs. @RawIndex { programs } +programs.varying @SubIndex { @Code "varying" style } +varying.programs @Index { @Code "varying" style (programs) } +programs. @RawIndex { programs } +programs.symbol @SubIndex { @Code "symbol" style } +symbol.programs @Index { @Code "symbol" style (programs) } (varying-width font), or {@Code "symbol"} (varying-width font with mathematical symbols used for some operators). Its default value depends on the language, and may be found in the fourth column of the table at the start of this chapter. The example in the previous section was in @Code fixed style; we can switch styles like this: -@ID @OneRow @Code { -"@CP" -" style { varying }" -"{" -"#include <stdio.h>" -"" -"treeprint(p) /* print tree p recursively */" -"struct tnode *p;" -"{" -" if (p != NULL) {" -" treeprint(p->left);" -" printf(\"%4d %s\\n\", p->count, p->word);" -" treeprint(p->right);" -" }" -"}" -"}" +@ID @OneRow @Code @Verbatim { +@CP + style { varying } +{ +#include <stdio.h> + +treeprint(p) /* print tree p recursively */ +struct tnode *p; +{ + if (p != NULL) { + treeprint(p->left); + printf(\%4d %s\\n\, p->count, p->word); + treeprint(p->right); + } +} +} } The result in this case will be @ID @OneRow @CP style { varying } @@ -65,31 +78,44 @@ with mathematical symbols replacing some of the operators. The {@Code "@CP"}, {@Code "@Eiffel"} etc. symbols have additional options which allow a finer control over the style. Here they all are, with their default values: -@ID @OneRow @Code { -"@CP [ or @Eiffel, @Blue, etc. ]" -" style { fixed }" -" numbered { No }" -" font { Courier }" -" size { -1.0p }" -" line { 1.0vx }" -" tabin { 8 }" -" tabout { 8s }" -" identifiers { Base }" -" keywords { Base }" -" operators { Base }" -" numbers { Base }" -" strings { Base }" -" comments { Base }" -"{" -" ..." -"}" +@ID @OneRow @Code @Verbatim { +@CP [ or @Eiffel, @Blue, etc. ] + style { fixed } + numbered { No } + font { Courier } + size { -1.0p } + line { 1.0vx } + tabin { 8 } + tabout { 8s } + identifiers { Base } + keywords { Base } + operators { Base } + numbers { Base } + strings { Base } + comments { Base } +{ + ... +} } We are already familiar with {@Code "style"}. After that comes {@Code "numbered"}, whose value may be {@Code "No"} (the default), {@Code "Yes"}, or a number, and which determines whether or not +programs. @RawIndex { programs } +programs.numbered @SubIndex { @Code "numbered" option } +numbered.programs @Index { @Code "numbered" option (programs) } line numbers are to be added and if so the value of the first one. Next we have {@Code "font"}, which determines the font family to use, {@Code "size"}, +programs. @RawIndex { programs } +programs.font @SubIndex { @Code "font" option } +font.option. @RawIndex { @Code "font" option } +font.option.in.programs @SubIndex { in program formatting } +programs. @RawIndex { programs } +programs.size @SubIndex { @Code "size" option } +size.programs @Index { @Code "size" option (programs) } +programs. @RawIndex { programs } +programs.line @SubIndex { @Code "line" option } +line.programs @Index { @Code "line" option (programs) } the font size to use, and {@Code "line"}, the inter-line spacing. The default value for @Code "size" asks for one point smaller than in the surrounding document; this was done to compensate for Courier's relatively @@ -98,6 +124,24 @@ large appearance compared to other fonts of the same nominal size. The @Code "tabin" and @Code "tabout" options are the subject of Section {@NumberOf tabs}. After them come six options giving the particular font faces in which to print identifiers, keywords, operators, +programs. @RawIndex { programs } +programs.identifiers @SubIndex { @Code "identifiers" option } +identifiers.programs @Index { @Code "identifiers" option (programs) } +programs. @RawIndex { programs } +programs.keywords @SubIndex { @Code "keywords" option } +keywords.programs @Index { @Code "keywords" option (programs) } +programs. @RawIndex { programs } +programs.operators @SubIndex { @Code "operators" option } +operators.programs @Index { @Code "operators" option (programs) } +programs. @RawIndex { programs } +programs.numbers @SubIndex { @Code "numbers" option } +numbers.programs @Index { @Code "numbers" option (programs) } +programs. @RawIndex { programs } +programs.strings @SubIndex { @Code "strings" option } +strings.programs @Index { @Code "strings" option (programs) } +programs. @RawIndex { programs } +programs.comments @SubIndex { @Code "comments" option } +comments.programs @Index { @Code "comments" option (programs) } numbers, strings, and comments. {@Code "Base"} means the basic face; other commonly available choices are {@Code "Slope"} and {@Code "Bold"}. These options may all be set to different faces if desired. The default values diff --git a/doc/user/prg_perl b/doc/user/prg_perl index 643afa6..e1fa0d6 100644 --- a/doc/user/prg_perl +++ b/doc/user/prg_perl @@ -4,6 +4,9 @@ @Begin @PP The Perl programming language +programs. @RawIndex { programs } +programs.perl @SubIndex { Perl problems } +perl.programs @Index { Perl problems (programs) } @FootNote { My thanks to Mark Summerfield for help with Perl and Pod. } is quite a difficult one for the @Code { prg2lout } program to deal with, and our boast that programs can be included with `absolutely no @@ -82,6 +85,9 @@ space before the semicolon. Further work may eliminate some of these problems. @PP The Pod language is used by Perl programmers for creating documentation, +programs. @RawIndex { programs } +programs.pod @SubIndex { Pod problems } +pod.programs @Index { Pod problems (programs) } and may be found within Perl programs or standing alone. Lout supports both arrangements without any special action by the user. At the beginning of the @Code perl setup line, the following line has been placed: diff --git a/doc/user/prg_pipe b/doc/user/prg_pipe index 813a691..3867a28 100644 --- a/doc/user/prg_pipe +++ b/doc/user/prg_pipe @@ -4,6 +4,9 @@ @Begin @PP We have said that program text within @Code "@CP { ... }" and the other +programs. @RawIndex { programs } +programs.include @SubIndex { @Code "@Include" within } +include.programs @Index { @Code "@Include" within programs } symbols is passed directly to @Code prg2lout for analysis. However, there is an exception. The program text may contain an @Code "@Include" or @Code "@SysInclude" command, which, as for the @@ -25,6 +28,9 @@ When including files in this way it often happens that only part of an actual program file is wanted for display. Rather than placing the wanted part in a separate file, which is error-prone and tedious when the program is changing, Unix users can use the @Code "pipe" option +programs. @RawIndex { programs } +programs.pipe @SubIndex { @Code "pipe" option } +pipe.programs @Index { @Code "pipe" option (programs) } to pipe the entire file through an arbitrary sequence of Unix commands, which may be used to make the wanted selection before the program text is passed to {@Code prg2lout}. diff --git a/doc/user/prg_prog b/doc/user/prg_prog index 19a525e..398dd29 100644 --- a/doc/user/prg_prog +++ b/doc/user/prg_prog @@ -4,6 +4,9 @@ @Begin @PP The standard reference for the Eiffel language @Cite { $meyer1992eiffel } +programs. @RawIndex { programs } +programs.programtext @SubIndex { program text in comments } +programtext.programs @Index { program text in program comments } specifies that identifiers within comments may or should be enclosed in ` and ' so that they may be noticed and printed in an italic font: diff --git a/doc/user/prg_tabs b/doc/user/prg_tabs index 9fe101d..f3ffa67 100644 --- a/doc/user/prg_tabs +++ b/doc/user/prg_tabs @@ -4,12 +4,17 @@ @Begin @PP Tab characters provide a convenient way to indent and align parts of -tab.c @Index { tab characters in programs } +programs. @RawIndex { programs } +programs.tab.characters @SubIndex { tab characters } +tab.characters.programs @Index { tab characters in programs } computer programs. With care, this alignment can be preserved in the final print even with varying-width fonts. @PP The distance between two tab stops in the program text is by default taken to be 8 characters, which is standard for Unix. This can be changed with +programs. @RawIndex { programs } +programs.tabin @SubIndex { @Code "tabin" option } +tabin.programs @Index { @Code "tabin" option (programs) } the @Code "tabin" option. For example, @ID @Code "@CP tabin { 4 }" informs Lout that tab stops occur every 4 characters in the program @@ -19,6 +24,9 @@ we will stick with C for the rest of this section. @PP The distance between two tab stops on the printed page is quite a different thing, and it is determined by the value of the @Code "tabout" option, which +programs. @RawIndex { programs } +programs.tabout @SubIndex { @Code "tabout" option } +tabout.programs @Index { @Code "tabout" option (programs) } must be a Lout length. For example, @ID @Code "@CP tabout { 0.5i }" requests that tab stops be placed at half-inch intervals. In other diff --git a/doc/user/ref_chan b/doc/user/ref_chan index befc860..d346de3 100644 --- a/doc/user/ref_chan +++ b/doc/user/ref_chan @@ -13,29 +13,33 @@ For a general introduction to setup files and their options, see Section {@NumberOf setup}. Here we just describe the setup file options that relate to references. Here they are, with their default values: -@ID @OneRow @Code { -"@MakeReferences { Yes }" -"@RefCiteStyle { [cite] }" -"@RefCiteLabels { @RefNum }" -"@RefNumbers { Arabic }" -"@RefListFormat { Labels }" -"@RefListLabels { [@RefNum] }" -"@RefListTitle { references }" -"@ChapRefListTitle { references }" -"@RefListIndent { 0c }" -"@RefListRightIndent { 0c }" -"@RefListGap { 1.00v }" -"@RefListFont { }" -"@RefListBreak { }" -"@RefListLabelWidth { 2.00f }" -"@RefListSortKey { @Tag }" +@ID @OneRow @Code @Verbatim { +@MakeReferences { Yes } +@RefCiteStyle { [cite] } +@RefCiteLabels { @RefNum } +@RefNumbers { Arabic } +@RefListFormat { Labels } +@RefListLabels { [@RefNum] } +@RefListTitle { references } +@ChapRefListTitle { references } +@RefListIndent { 0c } +@RefListRightIndent { 0c } +@RefListGap { 1.00v } +@RefListFont { } +@RefListBreak { } +@RefListLabelWidth { 2.00f } +@RefListSortKey { @Tag } } -makereferences.sym @Index { @Code "@MakeReferences" } +references. @RawIndex { references } +references.makereferences @SubIndex { @Code "@MakeReferences" } +makereferences.references @Index { @Code "@MakeReferences" (references) } Setting @Code "@MakeReferences" to @Code "No" will cause Lout to ignore all citation symbols and omit all reference lists. @PP @Code "@RefCiteStyle" and @Code "@RefCiteLabels" combine to -refcitestyle.sym @Index { @Code "@RefCiteStyle" } +references. @RawIndex { references } +references.refcitestyle @SubIndex { @Code "@RefCiteStyle" } +refcitestyle.references @Index { @Code "@RefCiteStyle" (references) } determine the appearance of citations. The result of each @Code "@Cite" symbol is the value of @Code "@RefCiteStyle" with the @Code "cite" symbol replaced by the object following the @Code "@Cite" symbol. For @@ -44,7 +48,9 @@ brackets. The @Code "cite" symbol must appear exactly once within {@Code "@RefCiteStyle"}. @PP @Code "@RefCiteLabels" determines the appearance of each label within -refcitelabels.sym @Index { @Code "@RefCiteLabels" } +references. @RawIndex { references } +references.refcitelabels @SubIndex { @Code "@RefCiteLabels" } +refcitelabels.references @Index { @Code "@RefCiteLabels" (references) } the citation. Within it, the @Code "@RefNum" symbol will produce the number of the reference, and you may also use any of the options of the @Code "@Reference" symbol listed at the beginning of Section @@ -68,7 +74,9 @@ if there is one, rather than the @Code "@Label" option of the reference; this @Code "label" option is explained in Section {@NumberOf labelled}. @PP @Code "@RefNumbers" determines the kind of numbering produced by the -refnumbers.sym @Index { @Code "@RefNumbers" } +references. @RawIndex { references } +references.refnumbers @SubIndex { @Code "@RefNumbers" } +refnumbers.references @Index { @Code "@RefNumbers" (references) } @Code "@RefNum" symbol used within @Code "@RefCiteLabels" above and @Code "@RefListLabels" below. Its value may be {@Code Arabic}, {@Code Roman}, {@Code UCRoman}, {@Code Alpha}, or {@Code UCAlpha}, as @@ -77,7 +85,9 @@ usual for numbering in Lout. If you don't use {@Code "@RefNum"}, @PP The remaining eleven setup file options are all concerned with the appearance of the reference list. The first, {@Code "@RefListFormat"}, -reflistformat.sym @Index { @Code "@RefListFormat" } +references. @RawIndex { references } +references.reflistformat @SubIndex { @Code "@RefListFormat" } +reflistformat.references @Index { @Code "@RefListFormat" (references) } determines the overall format of the list. Here is what its four @NoCite { $strunk1979style } possible values do: @ID @Tab @@ -106,7 +116,9 @@ determines the overall format of the list. Here is what its four labels and references, only with where they appear. @PP @Code "@RefListLabels" determines the appearance of the labels in the -reflistlabels.sym @Index { @Code "@RefListLabels" } +references. @RawIndex { references } +references.reflistlabels @SubIndex { @Code "@RefListLabels" } +reflistlabels.references @Index { @Code "@RefListLabels" (references) } reference list (and so has no effect if @Code "@RefListFormat" is {@Code "NoLabels"}). It is a combination of @Code "@RefCiteStyle" and {@Code "@RefCiteLabels"}; you can use @Code "@RefNum" and all the @@ -122,38 +134,54 @@ either use @Code "DropLabels" or else increase the @Code "@RefListLabelWidth" option described below. @PP @Code "@RefListTitle" determines the heading placed just before the -reflisttitle.sym @Index { @Code "@RefListTitle" } +references. @RawIndex { references } +references.reflisttitle @SubIndex { @Code "@RefListTitle" } +reflisttitle.references @Index { @Code "@RefListTitle" (references) } reference list at the end of the document: @ID @Code "@RefListTitle { Further Reading }" Two special values, @Code "references" and {@Code "bibliography"}, produce References and Bibliography in English and their equivalents in other languages. @Code "@ChapRefListTitle" is the same as -chapreflisttitle.sym @Index { @Code "@ChapRefListTitle" } +references. @RawIndex { references } +references.chapreflisttitle @SubIndex { @Code "@ChapRefListTitle" } +chapreflisttitle.references @Index { @Code "@ChapRefListTitle" (references) } {@Code "@RefListTitle"}, but applied to the reference list at the end of each chapter of a book when @Code "@ChapCite" is used. @PP {@Code "@RefListIndent"}, {@Code "@RefListRightIndent"}, and -reflistindent.sym @Index { @Code "@RefListIndent" } -reflistrightindent.sym @Index { @Code "@RefListRightIndent" } -reflistgap.sym @Index { @Code "@RefListGap" } +references. @RawIndex { references } +references.reflistindent @SubIndex { @Code "@RefListIndent" } +reflistindent.references @Index { @Code "@RefListIndent" (references) } +references. @RawIndex { references } +references.reflistrightindent @SubIndex { @Code "@RefListRightIndent" } +reflistrightindent.references @Index { @Code "@RefListRightIndent" (references) } {@Code "@RefListGap"} determine the left indent, right indent, and gap +references. @RawIndex { references } +references.reflistgap @SubIndex { @Code "@RefListGap" } +reflistgap.references @Index { @Code "@RefListGap" (references) } between reference list items, analogously to the {@Code "indent"}, {@Code "rightindent"}, and {@Code "gap"} options of the @Code "@List" symbol (Section {@NumberOf lists}). @Code "@RefListFont" and +references. @RawIndex { references } +references.reflistfont @SubIndex { @Code "@RefListFont" } +reflistfont.references @Index { @Code "@RefListFont" (references) } +references. @RawIndex { references } +references.reflistbreak @SubIndex { @Code "@RefListBreak" } +reflistbreak.references @Index { @Code "@RefListBreak" (references) } @Code "@RefListBreak" determine the font and -reflistfont.sym @Index { @Code "@RefListFont" } -reflistbreak.sym @Index { @Code "@RefListBreak" } paragraph breaking style of the reference list. For example, -@ID @OneRow @Code { -"@RefListFont { -2p }" -"@RefListBreak { 1.2fx outdent }" +@ID @OneRow @Code @Verbatim { +@RefListFont { -2p } +@RefListBreak { 1.2fx outdent } } switches to a smaller size with outdented paragraphs (these work well with {@Code NoLabels}). The empty default values produce the same font and break style as in the document as a whole. @PP @Code "@RefListLabelWidth" determines the distance from the left -reflistlabelwidth.sym @Index { @Code "@RefListLabelWidth" } +references. @RawIndex { references } +references.reflistlabelwidth @SubIndex { @Code "@RefListLabelWidth" } +reflistlabelwidth.references @Index { @Code "@RefListLabelWidth" (references) } edge of the labels to the left edge of the references, when @Code "@RefListFormat" is @Code Labels or {@Code DropLabels} (it has no effect when @Code "@RefListFormat" is @Code NoLabels or @@ -169,11 +197,13 @@ changed to any length (Section {@NumberOf objects}). Regrettably, Lout is not clever enough to choose a good value by itself. @PP Finally, @Code "@RefListSortKey" determines the sorting key used when +references. @RawIndex { references } +references.reflistsortkey @SubIndex { @Code "@RefListSortKey" } +reflistsortkey.references @Index { @Code "@RefListSortKey" (references) } sort.ref @Index { sorting of reference lists } -reflistsortkey.sym @Index { @Code "@RefListSortKey" } ordering the reference list. The default value, @ID @Code "@RefListSortKey { @Tag }" -sorts by tag. Another popular possibility is to sort by the +sorts by tag. Another possibility is to sort by the @Code "@Label" option: @ID @Code "@RefListSortKey { @Label }" As usual @Code "@Label" will use the value of a @Code "label" option diff --git a/doc/user/ref_cite b/doc/user/ref_cite index 7746841..925d61e 100644 --- a/doc/user/ref_cite +++ b/doc/user/ref_cite @@ -4,10 +4,11 @@ @Begin @PP To cite one or more references, use the @Code "@Cite" symbol like this: -citing @Index { citing references } -cite. @Index @Code "@Cite" -@ID @Code { -"This feature is beyond our scope @Cite { $kingston1995lout.expert, page 97 }." +references. @RawIndex { references } +references.cite @SubIndex { @Code "@Cite" } +cite.references @Index { @Code "@Cite" (references) } +@ID @Code @Verbatim { +This feature is beyond our scope @Cite { $kingston1995lout.expert, page 97 }. } The following object must be enclosed in braces. It may be an arbitrary object as usual. Within it the @Code "$" character is a symbol with a @@ -29,7 +30,9 @@ tag and labelled with Arabic numbers, although this can be changed by setting options in the setup file (Section {@NumberOf changeref}). @PP If you are making a book, there is a @Code "@ChapCite" symbol which is -chap.cite @Index @Code "@ChapCite" +references. @RawIndex { references } +references.chap.cite @SubIndex { @Code "@ChapCite" } +chap.cite.references @Index { @Code "@ChapCite" (references) } the same as @Code "@Cite" except that its references come out at the end of the current preface, introduction, chapter, or appendix, rather than at the end of the document. @@ -46,7 +49,9 @@ list at the end of the chapter), the reference will come out in the wrong list. Although it is frowned upon by the authorities, some people include references which are not cited anywhere in the body of their document. For this there is {@Code "@NoCite"}: -no.cite @Index @Code "@NoCite" +references. @RawIndex { references } +references.no.cite @SubIndex { @Code "@NoCite" } +no.cite.references @Index { @Code "@NoCite" (references) } @ID @Code { "... our scope @NoCite { $kingston1995lout.expert $kingston1993lout.design }." } @@ -59,34 +64,38 @@ references will nevertheless appear in the reference list as usual. Note that if you put commas between the references inside @Code "@NoCite" you will get commas in the output (so don't). There is a @Code "@NoChapCite" symbol that combines @Code "@NoCite" and -no.chap.cite @Index @Code "@NoChapCite" +references. @RawIndex { references } +references.no.chap.cite @SubIndex { @Code "@NoChapCite" } +no.chap.cite.references @Index { @Code "@NoChapCite" (references) } {@Code "@ChapCite"}. For compatibility with previous versions of Lout, there is a @Code "@Ref" symbol: -ref. @Index @Code "@Ref" +ref. @Index { @Code "@Ref" (references) } @ID @Code "@Ref kingston1995lout.expert" is the same as @Code "@Cite { $kingston1995lout.expert }" without the brackets. There are analogous {@Code "@ChapRef"}, {@Code "@NoRef"}, and {@Code "@NoChapRef"} -chap.ref @Index @Code "@ChapRef" -no.ref @Index @Code "@NoRef" -no.chap.ref @Index @Code "@NoChapRef" +chap.ref @Index { @Code "@ChapRef" (references) } +no.ref @Index { @Code "@NoRef" (references) } +no.chap.ref @Index { @Code "@NoChapRef" (references) } symbols, which are not recommended. @PP The @Code "@RefPrint" symbol will print a reference on the spot: -ref.print @Index @Code "@RefPrint" resume. @Index { resumes } curriculum. @Index { curriculum vitae } +references. @RawIndex { references } +references.refprint @SubIndex { @Code "@RefPrint" } +refprint.references @Index { @Code "@RefPrint" (references) } @ID @Code "@RefPrint kingston1995lout.expert" has result @ID @RefPrint kingston1995lout.expert unrelated to any reference list. For example, -@ID @OneRow @Code { -"@Heading { Journal Articles }" -"@NumberedList" -"@LI @RefPrint kingston1985tree" -"..." -"@LI @RefPrint kingston1993lout.design" -"@EndList" +@ID @OneRow @Code @Verbatim { +@Heading { Journal Articles } +@NumberedList +@LI @RefPrint kingston1985tree +... +@LI @RefPrint kingston1993lout.design +@EndList } might appear in someone's resume. @End @Section diff --git a/doc/user/ref_crea b/doc/user/ref_crea index 994f8d3..637bca5 100644 --- a/doc/user/ref_crea +++ b/doc/user/ref_crea @@ -10,13 +10,16 @@ can add your own reference types and change the formatting of existing types. To do this you must be using your own setup file, as explained in Section {@NumberOf setup}. At the end of the setup file you will find this line: -reference.print @Index { reference printing style } -ref.style @Index @Code "@RefStyle" +references. @RawIndex { references } +references.refstyle @SubIndex { @Code "@RefStyle" } +refstyle.references @Index { @Code "@RefStyle" (references) } @ID @Code "@SysDatabase @RefStyle { refstyle }" This tells Lout to consult a database file of reference styles called {@Code "refstyle.ld"}. These are not references, they are formatting styles, one for each reference type. The @Code "Sys" in @Code "@SysDatabase" -sys.database @Index @Code "@SysDatabase" +references. @RawIndex { references } +references.sysdatabase @SubIndex { @Code "@SysDatabase" } +sysdatabase.references @Index { @Code "@SysDatabase" } means that this file is stored in the @I { Lout system database directory }, system.database.dir @Index { system database directory } refstyle.ld.file @Index { @Code "refstyle.ld" file} @@ -50,19 +53,19 @@ searches only the system directory. In practice you will probably want to store your database of reference styles in some library directory, so that it can be used by many documents. A Unix pathname is appropriate for this: -@ID @Code "@Database @RefStyle { \"/usr/jeff/lib/mystyle\" }" +@ID @Code @Verbatim { @Database @RefStyle { "/usr/jeff/lib/mystyle" } } Quotes are needed because of the @Code "/" characters. @PP The database entries within @Code "refstyle.ld" and @Code "mystyle.ld" might look something like this: -@ID @OneRow @Code { -"{ Book @RefStyle @Style" -" { @Reference&&reftag @Open" -" {" -" @Author. @I @Title. @Publisher, @Year." -" }" -" }" -"}" +@ID @OneRow @Code @Verbatim { +{ Book @RefStyle @Style + { @Reference&&reftag @Open + { + @Author. @I @Title. @Publisher, @Year. + } + } +} } The meaning of the first two lines is beyond our scope, except that @Code "Book" on the first line means that this is the entry which @@ -113,14 +116,9 @@ to great lengths to do the right thing when options are omitted: @Rowa A { "}" } } The meaning is that each object to the left of an @Code "@If" will be -if. @Index @Code "@If" printed only if the condition to the right of the @Code "@If" is true. The condition may contain options, which are considered to be true if they are not omitted (non-empty), and it may contain {@Code "@And"}, -and. @Index @Code "@And" -or. @Index @Code "@Or" -not. @Index @Code "@Not" -true. @Index @Code "@True" {@Code "@Or"}, {@Code "@Not"}, and @Code "@True" with the usual precedence and meaning. Sub-conditions may be enclosed in braces if desired, although it is best to keep the conditions as simple as possible given the diff --git a/doc/user/ref_entr b/doc/user/ref_entr index 63516b2..e4c4b17 100644 --- a/doc/user/ref_entr +++ b/doc/user/ref_entr @@ -144,6 +144,9 @@ give the full four digits of the year to avoid trouble in the year 2000. Multi-word tags are possible but not recommended. @PP Unusually for Lout, you can have unquoted @Code "/" and @Code "~" +references. @RawIndex { references } +references.url @SubIndex { @Code "@URL" } +url.references @Index { @Code "@URL" (references) } characters inside the @Code "@URL" option: @ID @Code "@URL { ftp://ftp.cs.su.oz.au/jeff/lout }" In fact it is better not to use quotes because then Lout will @@ -153,25 +156,27 @@ since URLs tend to be long and prone to causing bad line breaks. Since the types within each broad category are similar, our plan is to give one example of each and briefly note how the others differ. Here is a @Code Book entry showing all its options: -book.ref.type @Index { @Code Book reference type } -@ID @OneRow @Code { -"{ @Reference" -" @Tag { homer.odyssey }" -" @Type { Book }" -" @Author { Homer }" -" @Title { The Odyssey }" -" @TitleNote { Translated by E. V. Rieu }" -" @Pinpoint { Chapter VI }" -" @Pages { 102--111 }" -" @Page { 102 }" -" @Publisher { Penguin Books }" -" @Address { Harmondsworth, Middlesex }" -" @Edition { Penguin Classics Edition }" -" @Month { August }" -" @Year { 1942 }" -" @Note { The date of composition is unknown," -"but is thought to be about the tenth century BC. }" -"}" +references. @RawIndex { references } +references.book @SubIndex { @Code Book reference type } +book.references @Index { @Code "Book" reference type } +@ID @OneRow @Code @Verbatim { +{ @Reference + @Tag { homer.odyssey } + @Type { Book } + @Author { Homer } + @Title { The Odyssey } + @TitleNote { Translated by E. V. Rieu } + @Pinpoint { Chapter VI } + @Pages { 102--111 } + @Page { 102 } + @Publisher { Penguin Books } + @Address { Harmondsworth, Middlesex } + @Edition { Penguin Classics Edition } + @Month { August } + @Year { 1942 } + @Note { The date of composition is unknown, +but is thought to be about the tenth century BC. } +} } And here is what it produces: @ID @RefPrint homer.odyssey @@ -182,7 +187,9 @@ right thing when you omit others. A basic book would have just {@Code "@Publisher"}, and {@Code "@Year"} options. @PP @Code Proceedings is similar, except you -proceedings.ref.type @Index { @Code Proceedings reference type } +references. @RawIndex { references } +references.proceedings @SubIndex { @Code Proceedings reference type } +proceedings.references @Index { @Code "Proceedings" reference type } may have an @Code "@Organization" or @Code "@Institution" option for the sponsoring organization if you wish, and the author will either be absent or an editor: @@ -190,27 +197,31 @@ absent or an editor: There is no option specifically for editors, translators, and so forth. @PP @Code PhDThesis is very similar again, with @Code "@Institution" -phdthesis.ref.type @Index { @Code PhDThesis reference type } +references. @RawIndex { references } +references.phdthesis @SubIndex { @Code PhDThesis reference type } +phdthesis.references @Index { @Code "PhDThesis" reference type } instead of {@Code "@Publisher"}, and the phrase `Ph.D. thesis' appearing by magic in the right spot. Like all words and phrases introduced automatically by Lout, it will be translated into the current language if this is not English. @PP Moving now to the second broad category, here is a typical {@Code TechReport}: -techreport.ref.type @Index { @Code TechReport reference type } -@ID @OneRow @Code { -"{ @Reference" -" @Tag { christofides1976tsp }" -" @Type { TechReport }" -" @Author { Christofides, N. }" -" @Title { Worst-case analysis of a new heuristic" -"for the travelling salesman problem }" -" @Number { 388 }" -" @Institution { Graduate School of Industrial" -"Administration, Carnegie-Mellon University }" -" @Address { Pittsburgh, PA }" -" @Year { 1976 }" -"}" +references. @RawIndex { references } +references.techreport @SubIndex { @Code TechReport reference type } +techreport.references @Index { @Code "TechReport" reference type } +@ID @OneRow @Code @Verbatim { +{ @Reference + @Tag { christofides1976tsp } + @Type { TechReport } + @Author { Christofides, N. } + @Title { Worst-case analysis of a new heuristic +for the travelling salesman problem } + @Number { 388 } + @Institution { Graduate School of Industrial +Administration, Carnegie-Mellon University } + @Address { Pittsburgh, PA } + @Year { 1976 } +} } Here is the result: @ID @RefPrint christofides1976tsp @@ -220,27 +231,33 @@ need some other phrase instead, use the @Code "@TRType" option: @ID @Code "@TRType { Programmer's Manual }" or whatever. The phrase will be `Master's Thesis' in the current language for type {@Code MastersThesis}, and absent in type -mastersthesis.ref.type @Index { @Code MastersThesis reference type } -misc.ref.type @Index { @Code Misc reference type } +references. @RawIndex { references } +references.mastersthesis @SubIndex { @Code MastersThesis reference type } +mastersthesis.references @Index { @Code "MastersThesis" reference type } +references. @RawIndex { references } +references.misc @SubIndex { @Code Misc reference type } +misc.references @Index { @Code "Misc" reference type } {@Code Misc}. You may use the pinpointing options ({@Code "@Pinpoint"}, {@Code "@Page"}, and {@Code "@Pages"}) and {@Code "@TitleNote"}, {@Code "@Month"}, and {@Code "@Note"} in the same way as for books. @PP Journal articles are referenced by journal name, volume, number, and page(s): -article.ref.type @Index { @Code Article reference type } -@ID @OneRow @Code { -"{ @Reference" -" @Tag { kingston1993lout.design }" -" @Type { Article }" -" @Author { Jeffrey H. Kingston }" -" @Title { The design and implementation of the" -"Lout document formatting language }" -" @Journal { Software---Practice and Experience }" -" @Volume { 23 }" -" @Pages { 1001--1041 }" -" @Year { 1993 }" -"}" +references. @RawIndex { references } +references.article @SubIndex { @Code Article reference type } +article.references @Index { @Code "Article" reference type } +@ID @OneRow @Code @Verbatim { +{ @Reference + @Tag { kingston1993lout.design } + @Type { Article } + @Author { Jeffrey H. Kingston } + @Title { The design and implementation of the +Lout document formatting language } + @Journal { Software---Practice and Experience } + @Volume { 23 } + @Pages { 1001--1041 } + @Year { 1993 } +} } The result of this is @ID @RefPrint kingston1993lout.design @@ -249,25 +266,29 @@ refer to the whole article so are not available for pinpointing here, but you may still use {@Code "@Pinpoint"}. @PP Finally, small works that appear within large works have @Code "@Author" -inbook.ref.type @Index { @Code InBook reference type } +references. @RawIndex { references } +references.inbook @SubIndex { @Code InBook reference type } +inbook.references @Index { @Code "InBook" reference type } and @Code "@Title" options for the work itself, and @Code "@InAuthor" and @Code "@InTitle" for the work that it appears within: -@ID @OneRow @Code { -"{ @Reference" -" @Tag { rieu1942intro }" -" @Type { InBook }" -" @Author { E. V. Rieu }" -" @Title { Introduction to @I { The Odyssey } }" -" @InAuthor { Homer }" -" @InTitle { The Odyssey }" -" @Publisher { Penguin }" -" @Year { 1942 }" -"}" +@ID @OneRow @Code @Verbatim { +{ @Reference + @Tag { rieu1942intro } + @Type { InBook } + @Author { E. V. Rieu } + @Title { Introduction to @I { The Odyssey } } + @InAuthor { Homer } + @InTitle { The Odyssey } + @Publisher { Penguin } + @Year { 1942 } +} } @Code "@InAuthor" would often be absent or an editor. The result is @ID @RefPrint rieu1942intro The other options are as for large works. Type @Code InProceedings is -inproceedings.ref.type @Index { @Code InProceedings reference type } +references. @RawIndex { references } +references.inproceedings @SubIndex { @Code InProceedings reference type } +inproceedings.references @Index { @Code "InProceedings" reference type } similar to {@Code InBook}. @PP A database usually has a long life, and some day it might find itself @@ -275,17 +296,17 @@ used in a document whose language is not the one its original compiler had in mind. For this reason, a truly meticulous compiler of database entries would enclose @I all language-specific options in @Code "@Language" symbols: -@ID @OneRow @Code { -"{ @Reference" -" @Tag { zimand1986size.sets.strings }" -" @Type { Article }" -" @Author { French @Language { M. Zimand } }" -" @Title { English @Language { On the topological size of sets of random strings } }" -" @Journal { German @Language { Zeitschr. f. math. Logik und Grundlagen d. Math. } }" -" @Volume { 32 }" -" @Pages { 81--88 }" -" @Year { 1986 }" -"}" +@ID @OneRow @Code @Verbatim { +{ @Reference + @Tag { zimand1986size.sets.strings } + @Type { Article } + @Author { French @Language { M. Zimand } } + @Title { English @Language { On the topological size of sets of random strings } } + @Journal { German @Language { Zeitschr. f. math. Logik und Grundlagen d. Math. } } + @Volume { 32 } + @Pages { 81--88 } + @Year { 1986 } +} } (My apologies to M. Zimand if he or she is not French.) This ensures correct hyphenation whatever the language of the document in which the diff --git a/doc/user/ref_labe b/doc/user/ref_labe index 1b8cc54..1cc5644 100644 --- a/doc/user/ref_labe +++ b/doc/user/ref_labe @@ -5,26 +5,31 @@ @Begin @PP Lout ordinarily assigns a number to each reference, and prints this -labelled.refs @Index { labelled references } +references. @RawIndex { references } +references.labelled @SubIndex { labelled } +labelled.references @Index { labelled references } number beside the reference in the reference list and at the point(s) of citation. There is a way to make Lout use a label of your choice instead of a number for each reference. First change the following setup file options to the values shown (these options are explained in Section {@NumberOf changeref}): -@ID @OneRow @Code { -"@RefCiteLabels { @Label }" -"@RefListLabels { @Label. }" -"@RefListLabelWidth { 4.00f }" -"@RefListSortKey { @Label }" +@ID @OneRow @Code @Verbatim { +@RefCiteLabels { @Label } +@RefListLabels { @Label. } +@RefListLabelWidth { 4.00f } +@RefListSortKey { @Label } } Then make sure that every reference you cite has a {@Code "@Label"} option: -@ID @OneRow @Code { -"{ @Reference" -" @Tag { kingston1995lout.expert }" -" @Type { TechReport }" -" @Label { Kin94 }" -" ..." -"}" +references. @RawIndex { references } +references.label @SubIndex { @Code "@Label" } +label.references @Index { @Code "@Label" (references) } +@ID @OneRow @Code @Verbatim { +{ @Reference + @Tag { kingston1995lout.expert } + @Type { TechReport } + @Label { Kin94 } + ... +} } @Code "@Label" may contain several words, and even font changes, but not an arbitrary object. diff --git a/doc/user/ref_sett b/doc/user/ref_sett index 283cb11..fe6b99d 100644 --- a/doc/user/ref_sett +++ b/doc/user/ref_sett @@ -4,31 +4,41 @@ @Begin @PP The basic idea is to store your references in a separate -database.file @Index { database file } +references. @RawIndex { references } +references.database.files @SubIndex { database.files } +database.files.references @Index { database files of references } @I { database file }, in a form which does not include formatting details such as font changes. This makes it easy to use the same references in many documents, and it leaves the formatting to Lout. Here is an example of a reference as it would appear in a database file: -@ID @OneRow @Code { -"{ @Reference" -" @Tag { vanleunen1992 }" -" @Type { Book }" -" @Author { Mary-Claire van Leunen }" -" @Title { A Handbook for Scholars }" -" @Publisher { Oxford }" -" @Edition { Revised Edition }" -" @Year { 1992 }" -"}" +@ID @OneRow @Code @Verbatim { +{ @Reference + @Tag { vanleunen1992 } + @Type { Book } + @Author { Mary-Claire van Leunen } + @Title { A Handbook for Scholars } + @Publisher { Oxford } + @Edition { Revised Edition } + @Year { 1992 } +} } -reference. @Index @Code "@Reference" +references. @RawIndex { references } +references.reference @SubIndex { @Code "@Reference" } +reference.references @Index { @Code "@Reference" (references) } @Code "@Reference" is a symbol, and {@Code "@Tag"}, {@Code "@Type"}, {@Code "@Author"}, and so on are its options. The database file as a whole consists of a sequence of references, each enclosed in braces as shown. @PP The @Code "@Tag" option is compulsory: since you cite a reference by +references. @RawIndex { references } +references.tag @SubIndex { @Code "@Tag" } +tag.option. @RawIndex { @Code "@Tag" option } +tag.option.in.references @SubIndex { in references } giving its tag, there must be one. The @Code "@Type" option is also -type. @Index { @Code "@Type" option } +references. @RawIndex { references } +references.type @SubIndex { @Code "@Type" option } +type.references @Index { @Code "@Type" (references) } compulsory, since it says whether the reference is to a book, a journal article, or whatever, and this determines what other options are required. Section {@NumberOf entries} describes all the types provided @@ -41,7 +51,9 @@ refs.ld.file @Index { @Code "refs.ld" file } @Code "refs.ld" and put it in the same directory as your document. Next, place @ID @Code "@Database @Reference { refs }" -database. @Index @Code "@Database" +references. @RawIndex { references } +references.database @SubIndex { @Code "@Database" } +database.references @Index { @Code "@Database" (references) } at the start of your document, just before {@Code "@Doc"}, {@Code "@Document"}, {@Code "@Report"}, or whatever. Alternatively, you may place it at the end of your setup file. It informs Lout that @@ -56,6 +68,8 @@ or whatever. Quotes are needed because of the @Code "/" characters. @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 +references. @RawIndex { references } +references.database.index.file @SubIndex { database index file } database.index.file @Index { database index file } index.file @Index { index file } database is used, Lout will create an @I { index file } whose purpose diff --git a/doc/user/str b/doc/user/str index 0312dfb..4460e8f 100644 --- a/doc/user/str +++ b/doc/user/str @@ -12,6 +12,7 @@ @Include { str_larg } @Include { str_cros } @Include { str_cont } +@Include { str_glos } @Include { str_indx } @Include { str_colu } @Include { str_defs } diff --git a/doc/user/str_colu b/doc/user/str_colu index b54a404..dc50194 100644 --- a/doc/user/str_colu +++ b/doc/user/str_colu @@ -21,7 +21,7 @@ at the beginning of your document (Section {@NumberOf ordinary}). value 1 as shown, and @Code "@ColumnGap" may be any length (Section {@NumberOf objects}). The column width is derived from these options column.width @RawIndex { column width } -column.width.pages @SubIndex { on pages } +column.width.in.pages @SubIndex { in pages } using the obvious formula @ID @Eq { columnwidth = { pagewidth - margins - ({@Code "@ColumnNumber"} - 1) times {@Code "@ColumnGap"} } diff --git a/doc/user/str_cont b/doc/user/str_cont index 148447e..3a802ae 100644 --- a/doc/user/str_cont +++ b/doc/user/str_cont @@ -5,7 +5,7 @@ @PP Lout takes note of the titles of all your large-scale structure symbols contents. @Index { contents, tables of } -tables.of.contents. @Index { tables of contents } +tables.zzz.of.contents. @Index { tables of contents } (Section {@NumberOf largescale}) and what pages they begin on, and it uses this information to produce a table of contents like the one at the start of the present document. It is totally automatic; you do diff --git a/doc/user/str_cros b/doc/user/str_cros index bbabfc9..984da8d 100644 --- a/doc/user/str_cros +++ b/doc/user/str_cros @@ -39,7 +39,6 @@ Inserting @Code "@PageMark decl.of.ind" will not affect the result, but Lout makes a note of the number of the page on which the word preceding it appears, and inserts that number in place of {@Code "@PageOf decl.of.ind"}. The tag, {@Code "decl.of.ind"}, may be -tag. @Index { tag } any simple word (actually Lout will accept a multi-word tag, but they are very inconvenient and better avoided). The braces are there, as usual, to control grouping: we don't want the following punctuation @@ -58,7 +57,7 @@ option), as well as @Code { "@FootNote" }, @Code { "@EndNote" }, symbols, and @Code "@ListItem" and @Code "@DropListItem" (but not @Code "@TagItem" and {@Code "@DropTagItem"}). Each of these symbols has a @Code "@Tag" option: -tag.sym @Index @Code "@Tag" +tag.option. @Index { @Code "@Tag" option } @ID @OneRow @Code { "@Section" " @Title { Cross references }" @@ -88,8 +87,8 @@ there is also the @Code "@TitleOf" symbol: } produces @QD { -"For further information on this point, please consult" -"the @TitleOf { cross } section." +For further information on this point, please consult +the @TitleOf { cross } section. } But this symbol won't work for footnotes, list items, and other things without a title. diff --git a/doc/user/str_figs b/doc/user/str_figs index 154e355..60e2677 100644 --- a/doc/user/str_figs +++ b/doc/user/str_figs @@ -64,7 +64,7 @@ sufficient space. } A { EvenPageTop } B { Like @Code PageTop except that the first page of the figure or table will be an even-numbered (left-hand or verso) page -- useful -for double-pace spreads. } +for double-page spreads. } @Rowa A { FullPage } B { Like {@Code PageTop} except that nothing else will appear on the @@ -269,7 +269,7 @@ in your setup file to get a smaller font size in your captions. @PP The @Code "@FigureCaptionFormat" option determines the format of the caption. Within it, the symbol @Code word stands for the `Figure' -word as defined by {@Code "@FigureWord"}); the @Code number +word as defined by {@Code "@FigureWord"}; the @Code number symbol stands for the number of the figure; and @Code caption stands for the body of the caption. The default value shown above prints the word and number and a period in bold, inserted together with a diff --git a/doc/user/str_glos b/doc/user/str_glos new file mode 100644 index 0000000..95a91e9 --- /dev/null +++ b/doc/user/str_glos @@ -0,0 +1,209 @@ +@Section + @Title { Glossaries } + @Tag { glossaries } +@Begin +@PP +A glossary +@FootNote { +The features described in this section are closely based on a +design by Thorsten Seitz. } +is a section at the end of a document containing terms +and their definitions, with a reference back to the page of the +document where each term is first used. It's similar to an index, +except that there are fewer entries and they are longer and more +spaced out -- for reading rather than just reference. +@PP +In order to get a glossary, you have to be using either the @Code book +or @Code report setup file, and you have to make your own copy of +the setup file (as described in Section {@NumberOf setup}) and change +the @Code "@MakeGlossary" option within it to {@Code "Yes"}. Lout +does not insert a glossary automatically. The glossary will appear +at the end of the document, immediately before any index. +@PP +To make an entry in the glossary, place something like this in +your main text at the point you are defining the term: +@ID @Code @Verbatim { +Object @Glossary { +Part of a document occupying a rectangular area; +may be a simple word, or a collection of smaller +objects composed in arbitrary ways. +} +} +The object to the left of @Code "@Glossary" is the term being defined, +and the object to the right is its definition. Nothing will appear +in the main text where you put this, but the term will appear in the +glossary, accompanied by its definition and the page number of this spot. +@PP +The term should be just a word or a short sequence of words. The +definition may be as long and complex as you wish, containing +paragraphs, displays, and so on. +@PP +The glossary items will appear sorted alphabetically. You can use +the @Code "sortkey" option of @Code "@Glossary" to provide a separate +sorting key: +@ID @Code @Verbatim { +{@Char florin} @Glossary sortkey { florin } { +The florin character. +} +} +This entry will appear in the list where things beginning with +@Code f do, not where the @Code florin character code would +place it. If you do this, since the term being defined is no +longer used as a sort key it is free to be an arbitrary object, not +restricted to be a word or a short sequence of words. +@PP +Creating a glossary entry does not automatically create an index +entry (Section {@NumberOf indexes}). If you want an index entry +for your glossary term as well (as you probably will) you need to +make that separately, and you will need to use a different tag +from the tag used by the glossary entry (which is either the term +being defined, or @Code sortkey if given). To make an index entry +that points into the actual glossary, which you also probably need, +just place your index entry somewhere inside the definition. +@PP +In your main text you may want to indicate to the reader that +some word or phrase appears in the glossary. For that there +is the @Code "@InGlossary" symbol: +@ID @Code "... where you can put one @InGlossary { object } ..." +The thing between braces does not actually have to be in the +glossary; @Code "@InGlossary" usually just changes the font, +by default to small capitals, and it does not change anything +unless @Code "@MakeGlossary" is {@Code Yes}. +@PP +The remainder of this section explains how to change the appearance +of the printed glossary, by setting options in the setup file. For +a general introduction to setup files and their options, see +Section {@NumberOf setup}; here we just explain how the particular +options relating to glossaries work. +@PP +Most of the glossary options appear within the @Code "@DocumentSetup" +@Code "@Use" clause. Here they are (except {@Code "@GlossaryFormat"} +which we'll discuss in a moment) with their default values: +@ID @Code @OneRow @Verbatim { +@MakeGlossary { No } +@GlossaryText { @Null } +@GlossaryFont {} +@GlossaryBreak {} +@GlossaryGap { @DisplayGap } +@GlossaryColumnNumber{ 2 } +@GlossaryColumnGap { 1.00c @OrIfPlain 6s } +@InGlossaryFont { smallcaps } +@InGlossaryFormat { @Body } +} +First comes {@Code "@MakeGlossary"}, which determines whether to +make a glossary, as we know. +@PP +{@Code "@GlossaryText"} is some arbitrary text that will be +placed before the first entry of the glossary. You can also +give this option to the @Code "@Book" and @Code "@Report" symbols, +and that would probably be the best place since such text is +usually part of the document content, not the setup. +@PP +@Code "@GlossaryFont" and @Code "@GlossaryBreak" are font and +break style options which are applied to each glossary entry. The +default values don't change the font or break style at all. +@PP +@Code "@GlossaryGap" determines the vertical separation between +one glossary entry and the next. You can give any length +(Section {@NumberOf objects}) here; the default is the gap used +around displays. +@PP +@Code "@GlossaryColumnNumber" and @Code "@GlossaryColumnGap" +determine the number of columns on glossary pages, and the +width of the gap between them. By default you get two columns +per page and a one centimetre gap (or six spaces in plain text +output), as for indexes (Section {@NumberOf indexes}). +@PP +@Code "@InGlossaryFont" and @Code "@InGlossaryFormat" determine +the appearance of the result of the @Code "@InGlossary" symbol. The +first changes the font; the second allows for more radical +formatting. Within it, {@Code "@Body"} stands for the object +following the {@Code "@InGlossary"} object, and you can do +anything you like with it here. For example, +@ID @Code "@InGlossaryFormat { @CurveBox @Body }" +would cause @Code "@InGlossary" to enclose the following +object in a curvebox (which would look horrible, of course). +The default values change to small capitals but nothing more. +@PP +{@Code "@GlossaryFormat"}, which we omitted earlier because +it is more complex, determines the format of each glossary +entry. Here it is with its default value: +@ID @OneRow @Code @Verbatim { +@GlossaryFormat { + +3p @Font @S @Name @Right @I { @Word&&page @PageNum } + @DP + @RawIndentedDisplay @Body +} +} +We'll go through this bit by bit. +@PP +First, the value of the option is longer than usual so we have +spread it over three lines. There is nothing significant in +this; end of line is the same as a space to Lout, and we've +used three lines just to show the value clearly. +@PP +Within @Code "@GlossaryFormat" three symbols are made +available specially: +@QD @OneRow @Tbl + aformat { @Cell @Code A | @Cell B } +{ +@Rowa + A { "@Name" } + B { Will be replaced by the term being defined } +@Rowa + A { "@PageNum" } + B { Will be replaced by the number of the page of the +spot where the @Code "@Glossary" symbol is placed } +@Rowa + A { "@Body" } + B { Will be replaced by the definition } +} +Now let's look at what the default format does. The first bit, +@ID @Code "+3p @Font @S @Name" +produces the term being defined, three points larger than would +have been the case otherwise, and in small capitals. The +@Code "@Right" symbol causes what follows it to appear at the +far right, so +@ID @Code "@I { @Word&&page @PageNum }" +will appear at the right of the column on the same line as +the term. The value of {@Code "@Word&&page"} is just +{@Code page} in the current language, and @Code "@PageNum" is a +page number as we know, so this produces something like +@ID @I { page 143 } +at the right. After that we have {@Code "@DP"} which leaves +a display-sized vertical gap, then the body appears in an +indented display, made Raw so that there is no trailing +vertical space. +@PP +You can change this option to anything you like. For example, +suppose you prefer bold to small capitals, you want the page number +in parentheses after the term, and you want each entry to be +kept together in one column: +@ID @OneRow @Code @Verbatim { +@GlossaryFormat { + @OneRow { + @B @Name (@I { @Word&&page @PageNum }) + @DP + @RawIndentedDisplay @Body + } +} +} +And so on. +@PP +There are a few more setup file options for glossaries, to be found +in the {@Code "@BookSetup"} or {@Code "@ReportSetup"} @Code "@Use" +clause of the setup file. Here they are with their default values: +@ID @OneRow @Code @Verbatim { +@GlossaryWord { glossary } +@GlossaryInContents { Yes } +@GlossaryPrefix {} +} +The first determines the word that will be used as the title of +the glossary. The default value shown produces {@Code Glossary} +in English and its equivalent in other languages. You could change +it, for example, to +@ID @Code "@GlossaryWord { List of Definitions }" +@Code "@GlossaryInContents" determines whether the glossary will +be listed in the table of contents if there is one; and +@Code "@GlossaryPrefix" is used by structure page numbers. +@End @Section diff --git a/doc/user/str_indx b/doc/user/str_indx index be6ca5d..f300707 100644 --- a/doc/user/str_indx +++ b/doc/user/str_indx @@ -34,6 +34,7 @@ To get this into your index, type @ID @Code "galileo @Index { Galileo Galilei }" at the point where you mention Galileo. Nothing will be printed there, but the object following the @Code "@Index" symbol will be placed in +index.sym @Index { @Code "@Index" symbol } the index, with a comma and the correct page number appended automatically. @PP @@ -53,6 +54,8 @@ collation. If the sorting you get turns out to be not what you expected, the first thing to try is the replacement of all accented letters in index keys by unaccented ones. Sorting is quite an intractable problem: even +collation.order @Index { collation order } +sorting.order @Index { sorting order } if @Code "strcoll()" gets the sorting right for one language, there still remains the problem of sorting multilingual indexes. @PP @@ -70,36 +73,15 @@ merged entries (see below). @PP Our first trick, raw entries (no page number attached), is very easy: just use @Code "@RawIndex" instead of {@Code "@Index"}. So the +rawindex.sym @Index { @Code "@RawIndex" symbol } first line of our ambitious example is obtained by @ID @Code "galileo @RawIndex { Galileo Galilei }" This could go anywhere, since no page numbers are involved. @PP -Another use for @Code "@RawIndex" is to get blank lines into the index -between the letters of the alphabet, by inserting phantom entries: -@ID @OneRow @Code { -"b @RawIndex {}" -"c @RawIndex {}" -"d @RawIndex {}" -"..." -"z @RawIndex {}" -} -In fact there is a symbol called @Code "@IndexBlanks" that makes -indexblanks. @Index @Code "@IndexBlanks" -exactly these 25 entries. Unfortunately, these blanks will occasionally -appear at the top of a column, and if there are no tags beginning with -x, for example, there will be two blank lines between the w and y -entries. You can start off with @Code "@IndexBlanks" and replace it -later by the appropriate subset, if necessary. -@FootNote { -For Lout to solve this problem automatically, it would need to be told -which letter each index entry belongs under, perhaps by symbols -{@Code "@AIndex"}, {@Code "@BIndex"}, etc. The author felt that this -would have been too tedious. -} -@PP Our second trick, sub-entries, is also very easy, since a sub-entry differs from an ordinary entry only by having an indent. The symbol is {@Code "@SubIndex"}, so the second line of our ambitious example is +subindex.sym @Index { @Code "@SubIndex" symbol } produced by @ID @Code "galileo.life @SubIndex { life of }" You should always give sub-entries the same sorting key as their @@ -250,22 +232,84 @@ 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. @PP +Large indexes may benefit from {@I spacers} -- empty spaces or +spacers. @Index { spacers in indexes } +even headings between the parts for each letter of the alphabet. One +simple way to get blank line spacers is with {@Code "@RawIndex"}, +like this: +@ID @OneRow @Code { +"b @RawIndex {}" +"c @RawIndex {}" +"d @RawIndex {}" +"..." +"z @RawIndex {}" +} +These phantom entries will insert blank lines before the region of each +English letter except `a'. In fact there is a symbol called +@Code "@IndexBlanks" that makes +indexblanks. @Index @Code "@IndexBlanks" +exactly these 25 entries. Unfortunately, these blanks will occasionally +appear at the top of a column, and if there are no tags beginning with +x, for example, there will be two blank lines between the w and y +entries. You can start off with @Code "@IndexBlanks" and replace it +later by the appropriate subset, if necessary. +@FootNote { +For Lout to solve this problem automatically, it would need to be told +which letter each index entry belongs under, perhaps by symbols +{@Code "@AIndex"}, {@Code "@BIndex"}, etc. The author felt that this +would have been too tedious. +} +@PP +A more elaborate kind of spacer can be placed into the index with +indexspacer. @Index @Code "@IndexSpacer" +the @Code "@IndexSpacer" symbol, like this: +@ID @Code "a @IndexSpacer A" +This is roughly equivalent to @Code "a @RawIndex A" in that it puts +the entry @Code A at sort position {@Code a}; but it also places +extra space above and below it, and it includes a font change, so +that the @Code A stands out like a heading (you can see the effect +in the index of this document). @Code "@IndexSpacer" also includes +a conditional new page effect, so that the spacer never appears +alone at the bottom of a column. +@PP +You need to change things slightly for the first spacer: +initialindexspacer. @Index @Code "@InitialIndexSpacer" +@ID @Code "a @InitialIndexSpacer A" +to tell Lout to omit the unwanted space above it. There is an +@Code "@IndexLetters" symbol which places the 26 spacers +indexletters. @Index @Code "@IndexLetters" +@ID @OneRow @Code @Verbatim { +a @InitialIndexSpacer A +b @IndexSpacer B +... +z @IndexSpacer Z +} +into your document for you in one go. Users of other alphabets are +recommended to define a similar symbol of their own. +@PP The remainder of this section describes how to change the appearance of the index by setting options in the setup file. For setup files and their options in general, consult Section {@NumberOf setup}. @PP -There are eight setup file options for the index. Here they are with +There are several setup file options for the index. Here they are with their default values: @ID @OneRow @Code @Verbatim { @MakeIndex { No } @IndexText { @Null } @IndexFont { } @IndexBreak { oragged 1.2fx } +@IndexFormat { @Body } +@SubIndexFormat { {1f @Wide}@Body } +@SubSubIndexFormat { {2f @Wide}@Body } @IndexColumnNumber { 2 } @IndexColumnGap { 1.00c } @IndexCtd { Yes } @IndexCtdWord { continued } @IndexCtdFormat { @Body @I (@CtdWord) } +@IndexSpacerAbove { 2v } +@IndexSpacerBelow { 1v } +@IndexSpacerFont { +3p } +@IndexSpacerFormat { @Body } } The @Code "@MakeIndex" option, which may be @Code Yes or {@Code No}, makeindex. @Index @Code "@MakeIndex" @@ -288,6 +332,22 @@ indexbreak. @Index @Code "@IndexBreak" paragraph breaking style applied to index entries; @Code oragged is the traditional and best way. @PP +@Code "@IndexFormat" allows a more radical control of the appearance +indexformat. @Index @Code "@IndexFormat" +of the index entry than just its font and break style. Within it, +the @Code "@Body" symbol stands for the entry, not including any page +numbers. The default value just leaves the index entry as is, but the +corresponding options for formatting subindexes ({@Code "@SubIndexFormat"} +and {@Code "@SubSubIndexFormat"}) are more interesting: +@ID @Code "@SubIndexFormat { {1f @Wide}@Body }" +causes subindexes to begin with an indent of width {@Code 1f}, +immediately followed by the entry. For more information about +lengths like {@Code 1f}, see Section {@NumberOf objects}. Another +possible format is +@ID @Code "@SubIndexFormat { -- @Body }" +which causes the subindex to begin with an en-dash and two spaces +instead of an indent. +@PP @Code "@IndexColumnNumber" and @Code "@IndexColumnGap" determine the indexcolumnnumber. @Index @Code "@IndexColumnNumber" indexcolumngap. @Index @Code "@IndexColumnGap" @@ -295,12 +355,27 @@ number of index columns per page, and the gap between them, and are exactly analogous to the @Code "@ColumnNumber" and @Code "@ColumnGap" options described in Section {@NumberOf columns}. @PP -The last three options work together to control the appearance of +The next three options work together to control the appearance of running headers @FootNote { -Index running headers are new in Version 3.19 of Lout. +Index running headers are new in Version 3.19 of Lout. Owing to problems +behind the scenes, if more than three copies of the same running header +appear on the same page, their horizontal positions will become confused, +probably resulting in the apparent disappearance of all but the last +three. Of course, this is highly unlikely to happen, since it means there +must be a four-column index with a page on which all four columns have +the same running header. } -in the index. If an @Code "@Index" entry has @Code "@SubIndex" entries +in the index: +indexctd. @Index { @Code "@IndexCtd" } +indexctdword. @Index { @Code "@IndexCtdWord" } +indexctdformat. @Index { @Code "@IndexCtdFormat" } +@ID @OneRow @Code @Verbatim { +@IndexCtd { Yes } +@IndexCtdWord { continued } +@IndexCtdFormat { @Body @I (@CtdWord) } +} +If an @Code "@Index" entry has @Code "@SubIndex" entries that run over to the next column, Lout will print an unobtrusive running header at the top of that column, something like this in English: @ID { procrastination @I (ctd.) } @@ -314,14 +389,50 @@ its equivalent in other languages. This is what the default value, want some other word, change that option to the word you want. Finally, you can control the format of the running headers using {@Code "@IndexCtdFormat"}. Within this option, the symbol @Code "@Body" -stands for the value of the index entry that is running over (minus any -page numbers), and @Code "@CtdWord" stands for the word produced by the -@Code "@IndexCtdWord" option. The default value of {@Code "@IndexCtdFormat"}, -shown above, yields the index entry followed by @Code "@IndexCtdWord" in +stands for the value of the index entry that is running over (as formatted +by {@Code "@IndexFormat"}, {@Code "@SubIndexFormat"}, or +{@Code "@SubSubIndexFormat"} but without any page numbers), and +@Code "@CtdWord" stands for the word produced by the @Code "@IndexCtdWord" +option. The default value of {@Code "@IndexCtdFormat"}, shown above, +yields the index entry followed by @Code "@IndexCtdWord" in italics and parentheses. @PP +Finally, we have four options to control the appearance of index +spacers: +indexspacerabove. @Index { @Code "@IndexSpacerAbove" } +indexspacerbelow. @Index { @Code "@IndexSpacerBelow" } +indexspacerfont. @Index { @Code "@IndexSpacerFont" } +indexspacerformat. @Index { @Code "@IndexSpacerFormat" } +@ID @OneRow @Code @Verbatim { +@IndexSpacerAbove { 2v } +@IndexSpacerBelow { 1v } +@IndexSpacerFont { +3p } +@IndexSpacerFormat { @Body } +} +@Code "@IndexSpacerAbove" and @Code "@IndexSpacerBelow" determine the +amount of extra space to insert above and below index spacers (except +that {@Code "@InitialIndexSpacer"} uses @Code {0v} for its above space). Any +lengths from Section {@NumberOf objects} are acceptable here; the default +lengths shown are two times and one times the current inter-line +spacing. @Code "@IndexSpacerFont" may contain any font change acceptable +to the {@Code "@Font"} symbol; the default increases the size by 3 +points. For more radical changes to the spacer format, +@Code "@IndexSpacerFormat" allows any symbols to be applied to the +spacer object, which is represented by the symbol @Code "@Body" within +this option. For example, +@ID @Code "@IndexSpacerFormat { @Underline @Body }" +will cause the spacer to be underlined. +@PP +The @Code "@IndexSpacer" symbol has {@Code above}, {@Code below}, +{@Code font}, and {@Code format} options which override the four +setup file options. For example, @Code "@InitialIndexSpacer" is +equivalent to +@ID @Code "@IndexSpacer above { 0v }" +Whether you will ever need to vary the appearance of index spacers +individually in this way is very doubtful, but the capacity is there. +@PP Lout offers the possibility of having up to three independent indexes -(useful for glossaries, author indexes, etc.). The other two are called +(useful for author indexes, etc.). The other two are called index A and index B, and they precede the main index in the output. Just replace @Code Index by @Code IndexA to refer to index A, and by @Code IndexB to refer to index B. For example, diff --git a/doc/user/str_list b/doc/user/str_list index 890acbf..e87a637 100644 --- a/doc/user/str_list +++ b/doc/user/str_list @@ -8,13 +8,13 @@ lists. @Index { lists } list. @Index @Code "@List" l. @Index @Code "@L" made into a displayed list: -@ID @OneRow @Code { -"preceding text" -"@List" -"@ListItem @I Emma" -"@ListItem @I { Mansfield Park }" -"@EndList" -"following text" +@ID @OneRow @Code @Verbatim { +preceding text +@List +@ListItem @I Emma +@ListItem @I { Mansfield Park } +@EndList +following text } After the initial @Code "@List" symbol, each item is introduced by list.item. @Index @Code "@ListItem" @@ -51,13 +51,13 @@ Other list symbols generate a @I label for each item. For example, @Code "@NumberedList" causes the items to be numbered: numberedlist. @Index @Code "@NumberedList" nl. @Index @Code "@NL" -@ID @OneRow @Code { -"@Heading { Quiz }" -"@NumberedList" -"@ListItem { Which American statesman owned a two-storey clock? }" -"@ListItem { Which Yankee commander from the Civil War cut a" -"swathe of destruction through the State of Georgia? }" -"@EndList" +@ID @OneRow @Code @Verbatim { +@Heading { Quiz } +@NumberedList +@ListItem { Which American statesman owned a two-storey clock? } +@ListItem { Which Yankee commander from the Civil War cut a +swathe of destruction through the State of Georgia? } +@EndList } has result @ID @OneRow { @@ -146,18 +146,18 @@ tagitem. @Index @Code "@TagItem" ti. @Index @Code "@TI" {@Code "@ListItem"}. Since such labels tend to be quite wide, there are @Code "@WideTaggedList" and @Code "@VeryWideTaggedList" symbols -widetaggedlist @Index @Code "@WideTaggedList" +widezzztaggedlist @Index @Code "@WideTaggedList" wtl. @Index @Code "@WTL" verywidetaggedlist @Index @Code "@VeryWideTaggedList" vwtl. @Index @Code "@VWTL" which leave extra space for them: -@ID @OneRow @Code { -"@WideTaggedList" -"@TagItem { 9 a.m. } { Breakfast in the Ipamena Lounge," -"served with Irish coffee and fresh croissants. }" -"@TagItem { 10 a.m. } { Prof. A. Smith" -"speaks on `The Wealth of Nations.' }" -"@EndList" +@ID @OneRow @Code @Verbatim { +@WideTaggedList +@TagItem { 9 a.m. } { Breakfast in the Ipamena Lounge, +served with Irish coffee and fresh croissants. } +@TagItem { 10 a.m. } { Prof. A. Smith +speaks on `The Wealth of Nations.' } +@EndList } Each @Code "@TagItem" symbol is followed by the desired label between braces, and then the item proper. The label may be empty, but still its @@ -197,15 +197,15 @@ raw.list. @Index @Code "@RawList" raw.end.list. @Index @Code "@RawEndList" @Code "@EndList" has a raw version which omits the following space. These are mainly used when an item is itself a list: -@ID @OneRow @Code { -"@ParenNumberedList" -"@ListItem {" -" @RawParenRomanList" -" @ListItem { MV Nominees," -"hereinafter called the vendor, ... }" -" @RawEndList" -"}" -"@EndList" +@ID @OneRow @Code @Verbatim { +@ParenNumberedList +@ListItem { + @RawParenRomanList + @ListItem { MV Nominees, +hereinafter called the vendor, ... } + @RawEndList +} +@EndList } produces @ID @OneRow { @@ -242,12 +242,12 @@ any kind of list. @PP Another special list item is {@Code "@ListInterruptItem"}. This prints its content without any numbering or formatting: -@ID @OneRow @Code { -"@NumberedList" -"@ListItem { This is the first list item. }" -"@ListInterruptItem { This is an interruption to the list. }" -"@ListItem { This is the second list item. }" -"@EndList" +@ID @OneRow @Code @Verbatim { +@NumberedList +@ListItem { This is the first list item. } +@ListInterruptItem { This is an interruption to the list. } +@ListItem { This is the second list item. } +@EndList } produces @ID @OneRow { @@ -273,15 +273,15 @@ Expert users will be interested to learn that all of the list symbols described in this section are derived from the two basic ones, @Code "@List" and {@Code "@RawList"}, merely by setting options. Here are all the options, together with their default values: -@ID @OneRow @Code { -"@List" -" type { num }" -" style { num }" -" labelwidth { 2f }" -" indent { 0c }" -" rightindent { 0c }" -" gap { 1v }" -" start { 1 }" +@ID @OneRow @Code @Verbatim { +@List + type { num } + style { num } + labelwidth { 2f } + indent { 0c } + rightindent { 0c } + gap { 1v } + start { 1 } } These options may be used with all of the list and raw list symbols, except that some combinations don't make sense, for example @Code "indent" @@ -295,14 +295,14 @@ determines the format of the label, any @Code "num" symbol within it being replaced by the number (in Arabic, Roman, etc. as determined by the @Code "type" option) of the item. For example, @Code "@ParenNumberedList" is just -@ID @OneRow @Code { -"@List" -" style { (num) }" +@ID @OneRow @Code @Verbatim { +@List + style { (num) } } and @Code "@BulletList" is just -@ID @OneRow @Code { -"@List" -" style { @Bullet }" +@ID @OneRow @Code @Verbatim { +@List + style { @Bullet } } with @Code "num" not mentioned since no number is wanted. The @Code "@TaggedList" symbol and its variants also have the @@ -336,9 +336,9 @@ setup file option, described below. @PP The @Code "start" option is the number assigned to the first item. It must be decimal: -@ID @OneRow @Code { -"@ParenRomanList" -" start { 25 }" +@ID @OneRow @Code @Verbatim { +@ParenRomanList + start { 25 } } looks strange, but it is the correct way to number the first item (xxv). @@ -346,18 +346,18 @@ item (xxv). Here is a larger example of these options in action. Setting both @Code "indent" and @Code "rightindent" to @Code "@DisplayIndent" produces an effect similar to {@Code "@QuotedDisplay"}: -@ID @OneRow @Code { -"preceding text" -"@List" -" style { @I {Item num}: }" -" indent { @DisplayIndent }" -" rightindent { @DisplayIndent }" -" labelwidth { @WideIndent }" -" start { 10 }" -"@ListItem { The vendor ... in the case of accident. }" -"@ListItem { The vendor ... adjacent to the facility. }" -"@EndList" -"following text" +@ID @OneRow @Code @Verbatim { +preceding text +@List + style { @I {Item num}: } + indent { @DisplayIndent } + rightindent { @DisplayIndent } + labelwidth { @WideIndent } + start { 10 } +@ListItem { The vendor ... in the case of accident. } +@ListItem { The vendor ... adjacent to the facility. } +@EndList +following text } The result is @ID @OneRow { @@ -387,8 +387,8 @@ You can change the @I default values of the {@Code "labelwidth"}, by setting options called {@Code "@ListTagWidth"}, {@Code "@ListIndent"}, {@Code "@ListRightIndent"}, and {@Code "@ListGap"} in the setup file (Section {@NumberOf setup}). These default values will then apply -automatically to every list in the document unless overridden by an option, -just as the usual default values do. The setup file also has a -{@Code "@ListOuterGap"} option which determines the gap before the first -and after the last list item in non-raw lists. +to every list in the document unless overridden by an option, +just like the usual default values. The setup file also has a +{@Code "@ListOuterGap"} option which determines the gap before +the first and after the last list item in non-raw lists. @End @Section diff --git a/doc/user/str_marg b/doc/user/str_marg index e2eba2d..fdb58f4 100644 --- a/doc/user/str_marg +++ b/doc/user/str_marg @@ -86,7 +86,7 @@ place. @Index @Code "@Place" page is provided by the @Code "@Place" symbol: @ID @OneRow @Code { "@Place" -" x { right - 1 cm - xsize }" +" x { right - 1c - xsize }" " y { { foot + top } / 2 }" "{" " @Box { Hello }" @@ -97,15 +97,15 @@ box whose @I x (horizontal) position is such that its right edge is one centimetre from the right edge of the page, and whose @I y (vertical) position is halfway up & @Place - x { right - 1 cm - xsize } + x { right - 1c - xsize } y { { foot + top } / 2 } { @Box { Hello } } the page. @PP -In addition to numbers, Lout lengths (Section {@NumberOf objects}), -and Diag lengths (Section {@NumberOf dia_summ}), the following symbols +In addition to numbers, with or without units of measurement +(Section {@NumberOf objects}), the following symbols may be used inside the @Code "x" and @Code "y" options: @ID @Tab @Fmta { @Col @Code A ! @Col B } diff --git a/doc/user/tbl b/doc/user/tbl index 545e867..012f20e 100644 --- a/doc/user/tbl +++ b/doc/user/tbl @@ -38,7 +38,7 @@ Section {@NumberOf tbl_alig} for the details. @BeginSections @Include { tbl_intr } # introduction -@Include { tbl_cell } # basic cell formatting: font, break, width, paint +@Include { tbl_cell } # cell formatting: font, break, width, paint @Include { tbl_rows } # row formats and the @Row symbol @Include { tbl_rule } # rules @Include { tbl_marg } # margins diff --git a/doc/user/tbl_alig b/doc/user/tbl_alig index 69e5588..0634f75 100644 --- a/doc/user/tbl_alig +++ b/doc/user/tbl_alig @@ -4,6 +4,8 @@ @Begin @PP Columns of numbers are often presented with decimal points aligned: +tables. @RawIndex { tables } +tables.aligned @SubIndex { aligned columns } aligned.columns @Index { aligned columns in tables } @CD @OneRow @Tbl marginvertical { 0.5vx } diff --git a/doc/user/tbl_cell b/doc/user/tbl_cell index 159372e..e68fd0b 100644 --- a/doc/user/tbl_cell +++ b/doc/user/tbl_cell @@ -4,7 +4,18 @@ @Begin @PP The @Code "@Cell" symbol offers a few options for changing the appearance -cell.option @Index { cell options in tables } +tables. @RawIndex { tables } +tables.paint @SubIndex { @Code "paint" option } +paint. @RawIndex { @Code "paint" option } +paint.in.tables @SubIndex { in tables } +tables. @RawIndex { tables } +tables.font @SubIndex { @Code "font" option } +font.option. @RawIndex { @Code "font" option } +font.option.in.tables @SubIndex { in tables } +tables. @RawIndex { tables } +tables.break @SubIndex { @Code "break" option } +break. @RawIndex { @Code "break" option } +break.tables @SubIndex { in tables } of entries placed in it. Like all options, these appear immediately after the @Code "@Cell" symbol, with their values in braces: @ID @OneRow @Code @Verbatim { @@ -29,9 +40,61 @@ Do not throw stones at this notice } with a light grey background, Italic font, and @Code "clines" paragraph breaking style. The paint colour -may be any colour from Section {@NumberOf colour}. Another option, -{@Code background}, allows an arbitrary object to be placed in the -background of the cell, in front of any paint but behind the entry. +may be any colour from Section {@NumberOf colour}. +@PP +Wherever there is a @Code paint option in the standard packages, there +is a neighbouring @Code texture option, which causes the paint to be +tables. @RawIndex { tables } +tables.texture @SubIndex { @Code "texture" option } +texture.option. @RawIndex { @Code "texture" option } +texture.option.in.tables @SubIndex { in tables } +applied according to a given texture. For a list of available +textures, consult Section {@NumberOf textures}; for how the @Code texture +option works, consult the description of the @Code texture option to the +@Code "@Box" symbol in Section {@NumberOf boxes} (all @Code texture +options work in the same way). Here's an example: +@ID @OneRow @Code @Verbatim { +@Tbl + width { 2f } + height { 2f } + aformat { +@Cell paint { black } texture { brickwork } A | @Cell B | +@Cell paint { black } texture { brickwork } C | @Cell D } + bformat { +@Cell A | @Cell paint { black } texture { brickwork } B | +@Cell C | @Cell paint { black } texture { brickwork } D } +{ +@Rowa +@Rowb +@Rowa +@Rowb +} +} +produces +@FootNote { If you can't see any textures here, the fault is probably +with your PostScript viewer. See Section {@NumberOf textures}. } +@CD @OneRow +@Tbl + width { 2f } + height { 2f } + aformat { +@Cell paint { black } texture { brickwork } A | @Cell B | +@Cell paint { black } texture { brickwork } C | @Cell D } + bformat { +@Cell A | @Cell paint { black } texture { brickwork } B | +@Cell C | @Cell paint { black } texture { brickwork } D } +{ +@Rowa +@Rowb +@Rowa +@Rowb +} +Another option, {@Code background}, allows an arbitrary object to be +tables. @RawIndex { tables } +tables.background @SubIndex { @Code "background" option } +background.tables @Index { @Code "background" option (tables) } +placed in the background of the cell, in front of any paint but behind +the entry. @PP Later sections introduce other @Code "@Cell" options, for fixed-width columns, indented entries, margins, and rules. It is also @@ -92,6 +155,6 @@ setup file (Section {@NumberOf tbl_setu}), which if set will paint every table in the document. When a more general setting of an option is contradicted by a more specific setting (e.g. when @Code "@Tbl" has @Code "paint { lightgrey }" but some cell or row has -{@Code "paint { nopaint }"}), the more specific setting applies. For a +{@Code "paint { none }"}), the more specific setting applies. For a precise description, see Section {@NumberOf tbl_summ}. @End @Section diff --git a/doc/user/tbl_inde b/doc/user/tbl_inde index 62080c0..c8e02d4 100644 --- a/doc/user/tbl_inde +++ b/doc/user/tbl_inde @@ -5,6 +5,9 @@ @PP By default, entries appear at the left within cells, not counting the cell margin. The @Code indent option causes entries to be indented +tables. @RawIndex { tables } +tables.indent @SubIndex { @Code "indent" option } +indent.tables @Index { @Code "indent" option (tables) } horizontally. For example, @ID @OneRow @Code "@Cell indent { ctr }" horizontally centres the entry within the cell. Other possible values @@ -15,6 +18,9 @@ are {@Code "left"} (the default value), {@Code "right"}, example, {@Code 2f}) meaning that much indent. @PP There is a corresponding @Code "indentvertical" option for vertical indenting +tables. @RawIndex { tables } +tables.indentvertical @SubIndex { @Code "indentvertical" option } +indentvertical.tables @Index { @Code "indentvertical" option (tables) } within the cell. It takes the same values except that @Code "left" is renamed {@Code "top"} (the default), and @Code "right" is renamed {@Code foot}. A common problem with vertical placement is that words that @@ -44,6 +50,10 @@ we see that the words are aligned correctly despite these worries. This is because by default @Code "@Tbl" adds a @I { vertical strut } to each entry: an invisible object of zero width and height {@Code "1f"}, which covers for any absent +tables. @RawIndex { tables } +tables.strut @SubIndex { @Code "strut" option } +strut.option. @RawIndex { @Code "strut" option } +strut.option.in.tables @SubIndex { in tables } ascenders and descenders. The option @ID @OneRow @Code "@Cell strut { no }" can be used to remove the strut; other acceptable values for this @@ -51,6 +61,9 @@ option are {@Code yes} (the default value), and any length, which will add a strut of that length. @PP For completeness there is a corresponding @Code "struthorizontal" option; it +tables. @RawIndex { tables } +tables.struthorizontal @SubIndex { @Code "struthorizontal" option } +struthorizontal.tables @Index { @Code "struthorizontal" option (tables) } takes the same values, its default value is {@Code no}, and it unlikely ever to be used. @End @Section diff --git a/doc/user/tbl_intr b/doc/user/tbl_intr index 1c9160e..bb0727c 100644 --- a/doc/user/tbl_intr +++ b/doc/user/tbl_intr @@ -31,7 +31,9 @@ your own setup file, you may place the include commands within it, near the start. @PP To begin with a very simple example, the table -tbl. @Index @Code "@Tbl" +tables. @RawIndex { tables } +tables.tbl @SubIndex { @Code "@Tbl" } +tbl.tables @Index { @Code "@Tbl" (tables) } @CD @Tbl aformat { @Cell A | @Cell B | @Cell C } @@ -70,7 +72,16 @@ is produced by the following input: } Immediately after the @Code "@Tbl" symbol, which introduces the table, comes a @I { format option }, {@Code "aformat"}, describing the format of +tables. @RawIndex { tables } +tables.aformat @SubIndex { @Code "aformat" option } +aformat.tables @Index { @Code "aformat" option (tables) } +tables. @RawIndex { tables } +tables.format @SubIndex { format of } +format.tables @Index { format of tables } each row. It says that each row contains three cells: {@Code "@Cell A"}, +tables. @RawIndex { tables } +tables.cell @SubIndex { @Code "@Cell" } +cell.tables @Index { @Code "@Cell" (tables) } {@Code "@Cell B"}, and {@Code "@Cell C"}. The format option may have up to 26 cells, with names chosen freely from the upper-case letters from @Code A to {@Code Z}. The symbol @Code "|" separates each cell from the next. @@ -78,6 +89,9 @@ to 26 cells, with names chosen freely from the upper-case letters from After the format option comes the body of the table, enclosed in braces. It consists entirely of a sequence of rows, each introduced by a @Code "@Rowa" symbol and containing one entry for each cell of the +tables. @RawIndex { tables } +tables.rowa @SubIndex { @Code "@Rowa" } +rowa.tables @Index { @Code "@Rowa" (tables) } format option, as shown (the row may occupy any number of lines of the input file). The entries may be arbitrary Lout objects, such as words, paragraphs, equations, figures, and so on without restriction. An entry diff --git a/doc/user/tbl_marg b/doc/user/tbl_marg index ddbab55..6c156d3 100644 --- a/doc/user/tbl_marg +++ b/doc/user/tbl_marg @@ -4,8 +4,10 @@ @Begin @PP The @Code "@Cell" symbol offers a @Code margin option for changing the -margins @RawIndex { margins } -margins.in.tables @SubIndex { margins in tables } +tables. @RawIndex { tables } +tables.margin @SubIndex { @Code "margin" options } +margin.options @RawIndex { margin options } +margin.options.in.tables @SubIndex { in tables } amount of margin left between the entry and the boundary of the cell: @ID @Code "@Cell margin { 0.3f }" The default values are different for horizontal and vertical margins, diff --git a/doc/user/tbl_mark b/doc/user/tbl_mark index 51d71e7..ec86f6d 100644 --- a/doc/user/tbl_mark +++ b/doc/user/tbl_mark @@ -4,13 +4,15 @@ @Begin @PP Occasionally the vertical alignment of a table with objects to its left +tables. @RawIndex { tables } +tables.vertical.alignment @SubIndex { vertical alignment of } vertical.alignment @Index { vertical alignment of tables } and right becomes an issue. Examples are hard to find, but let's say that we need to construct a symbol @ID @AmberLight and include it in running text. The obvious first attempt at a table with three rows is -@ID @OneRow @Code @Verbatim { +@ID -1px @Break @OneRow @Code @Verbatim { @Tbl aformat { @Cell A } margin { 0i } @@ -36,10 +38,13 @@ but this produces in running text, because vertical alignment is by default through the top boundary of the table. To make the alignment pass through one of the rows, replace its @Code "@Row" symbol by a corresponding +tables. @RawIndex { tables } +tables.markrow @SubIndex { @Code "@MarkRow" symbols } +thing.tables @Index { @Code "@MarkRow" symbols (tables) } @Code "@MarkRow" symbol. Here is the revised table, enclosed in a definition for ease of use: amberlight @Index { @Code "@AmberLight" symbol } -@ID @OneRow @Code @Verbatim { +@ID -1px @Break @OneRow @Code @Verbatim { import @TblSetup def @AmberLight { diff --git a/doc/user/tbl_mult b/doc/user/tbl_mult index b523223..7ab66c9 100644 --- a/doc/user/tbl_mult +++ b/doc/user/tbl_mult @@ -4,14 +4,37 @@ @Begin @PP The tables produced by @Code "@Tbl" permit page breaks (including breaking +tables. @RawIndex { tables } +tables.multipage @SubIndex { multi-page } multi.page.tables @Index { multi-page tables } to a new column) between every two rows, except rows that have a vertically spanning cell in common. Page breaks cannot occur within rows. The choice of page breaks can either be left to Lout, or it can be forced by placing the new page symbol @Code "@NP" between two -np.tables @Index { @Code "@NP" (new page) in tables } +tables. @RawIndex { tables } +tables.np @SubIndex { @Code "@NP" (new page) in } +np. @RawIndex { @Code "@NP" (new page) } +np.in.tables @SubIndex { in tables } rows. @PP +To prevent page breaks within a table, precede the @Code "@Tbl" +symbol by {@Code "@OneRow"}: +@ID @Code "@CD @OneRow @Tbl ..." +@Code "@OneRow" is a general Lout symbol which binds the following +object into a single, unbreakable row. Make sure your table is +small enough to fit on one page when you do this, otherwise an error +message will be printed and it will be scaled to fit. Display symbols +like @Code "@CD" often have this effect anyway. +@PP +To prevent a page break between two particular rows, but not in +general, replace the @Code "@Row" symbol of the second row with +tables. @RawIndex { tables } +tables.nobreakrow @SubIndex { @Code "@NoBreakRow" symbols } +nobreakrow.tables @Index { @Code "@NoBreakRow" symbols (tables) } +the corresponding @Code "@NoBreakRow" symbol (@Code "@NoBreakRowa" +instead of {@Code "@Rowa"}, @Code "@NoBreakRowb" instead of +{@Code "@Rowb"}, and so on). +@PP Some care is needed over where to put multi-page tables. They can't go within any of the display symbols, because display symbols are not clever enough to break tables between rows, even though they are sometimes able @@ -34,14 +57,27 @@ rightmost column to the full page width; one way to prevent this is to add a @Code "|" after the last cell within each {@Code format} option, creating an empty extra column. @PP -One practical problem with multi-page tables is that of getting a +One practical problem in multi-page tables is getting the rules +right. The simplest way to do this is to set @Code "rulehorizontal" +to {@Code yes}. This places a rule above every row including the +first on each page, and a rule below every row including the last +on each page. There is nothing equivalent to running headers +(described below) at the bottom of the page -- nothing that would allow +you to insert a rule after the last line of each page, but not +elsewhere. (However, if you are using the @Code "@Table" +symbol, its @Code "@Format" option can be used to do this.) +@PP +Another practical problem with multi-page tables is that of getting a heading over every page after the first. This is easy if you know where the page breaks are going to fall (if you are using {@Code "@NP"}, for example), but you usually don't. To solve this problem, @Code {"@Tbl"} offers the @Code "@HeaderRowa" ... @Code "@HeaderRowh" and +tables. @RawIndex { tables } +tables.headerrow @SubIndex { @Code "@HeaderRow" symbols } +headerrow.tables @Index { @Code "@HeaderRow" symbols (tables) } @Code "@EndHeaderRow" symbols. For example, the multi-page table in Section {@NumberOf tbl_summ} is arranged like this: -@ID @OneRow @Code @Verbatim { +@ID -1px @Break @OneRow @Code @Verbatim { @Tbl ... { @@ -59,7 +95,7 @@ Section {@NumberOf tbl_summ} is arranged like this: rulebelow { yes } @Rowa A { paint p } - B { nopaint } + B { none } D { any colour from Section {@NumberOf colour} } ... @Rowa @@ -70,24 +106,22 @@ Section {@NumberOf tbl_summ} is arranged like this: @EndHeaderRow } } -where we have omitted a lot of irrelevant things. @Code "@HeaderRowd" -is exactly like {@Code "@Rowd"}, except that the row is not printed at -all where it occurs; instead, it is saved up and used as a running header -on subsequent pages. +@Code "@HeaderRowd" is exactly like {@Code "@Rowd"}, except that the row is +not printed at all where it occurs; instead, it is saved up and used as a +running header on subsequent pages. @PP The @Code "@EndHeaderRow" symbol goes where a @Code "@Row" symbol might go. Notice that it does not end with a letter between {@Code a} and -{@Code h}, and that it has no options. Its meaning is that the most -recent running header is not wanted on pages after this point: in other -words, it cancels the previous @Code "@HeaderRowa" ... @Code "@HeaderRowh" -symbol. Forgetting @Code "@EndHeaderRow" is disastrous, because every page -from this point on will then have the running header, even though the table -ended long before. +{@Code h}, and that it has no options. Its effect is to cancel the +closest preceding @Code "@HeaderRowa" ... @Code "@HeaderRowh" symbol. +If you forget it, the result is bizarre: the header row will remain +in effect, and then every page from this point on will have the running +header, even though the table ended long before. @PP There may be any number of header rows saved up at any moment, all to be printed at the top of subsequent pages. Having @Code "@EndHeaderRow" -allows them to be `nested.' For example, just schematically, -@ID @OneRow @Code @Verbatim { +allows them to be `nested.' For example, +@ID -1px @Break @OneRow @Code @Verbatim { @HeaderRowa ... @HeaderRowb ... @EndHeaderRow @@ -97,46 +131,24 @@ allows them to be `nested.' For example, just schematically, } could be used in a table to say that the entire table has the first header row; and that the first part also has the second header row, -but the second part of the table has a different second header row, -but still the same first header row. +but that subsequent parts of the table have their own, different +second header row, but still the same first header row. @PP -These header symbols have some peculiarities not likely to trouble the -ordinary user, but worth pointing out. Each copy of a running header -will be identical to every other copy, so any attempt to use cross -references to add (say) page numbers to the running header is doomed to -disappointment. (If you want to change the header, use -@Code "@EndHeaderRow" followed by a new header row.) Basser Lout -copies running header rows into the table after each page break, -with no check on whether the next page has enough space to -accommodate them, so if your running headers are so high that -there is no room for ordinary rows on the page after they are -inserted, then the document will never end. Finally, header -rows are taken account of by Lout when deciding column widths, -whether they are actually printed or not. +Certain kinds of objects are not allowed in header rows, and Lout will +complain and quit if you try to put them there. Galleys +(e.g. {@Code "@FootNote"} and {@Code "@Index"}) are not allowed, nor are +cross references (e.g. {@Code "@NumberOf"} and {@Code "@PageOf"}), nor +are {@Code "@HExpand"}, {@Code "@VExpand"}, or {@Code "@Scale"} in the +form that works out its own scale factor. Spanning symbols +({@Code "@StartHSpan"}, {@Code "@StartVSpan"} etc.) work well in header +row formats, however. @PP -Another practical problem in multi-page tables is getting the rules -right. The simplest way to do this is to set @Code "rulehorizontal" -to {@Code yes}. This places a rule above every row including the -first on each page, and a rule below every row including the last -on each page. There is nothing equivalent to running headers -at the bottom of the page -- nothing that would allow you to -insert a rule after the last line of each page, but not -elsewhere. (However, if you are using the @Code "@Table" -symbol, its @Code "@Format" option can be used to do this.) -@PP -To prevent page breaks within a table, precede the @Code "@Tbl" -symbol by {@Code "@OneRow"}: -@ID @Code "@CD @OneRow @Tbl ..." -@Code "@OneRow" is a general Lout symbol which binds the following -object into a single, unbreakable row. Make sure your table is -small enough to fit on one page when you do this, otherwise an error -message will be printed and it will be scaled to fit. Of course, we -said earlier that display symbols like @Code "@CD" do this anyway, -but that might change some day. -@PP -To prevent a page break between two particular rows, but not in -general, replace the @Code "@Row" symbol of the second row with -the corresponding @Code "@NoBreakRow" symbol (@Code "@NoBreakRowa" -instead of {@Code "@Rowa"}, @Code "@NoBreakRowb" instead of -{@Code "@Rowb"}, and so on). +Header rows have some other peculiarities, not likely to trouble +the ordinary user but worth pointing out. Header rows are taken +account of by Lout when deciding column widths, whether they are +actually printed or not. Basser Lout copies running header rows +into the table after each page break, with no check on whether the +next page has enough space to accommodate them, so if your running +headers are so high that there is no room for ordinary rows on the +page after they are inserted, then the document will never end. @End @Section diff --git a/doc/user/tbl_plai b/doc/user/tbl_plai index d887b86..ca20f4b 100644 --- a/doc/user/tbl_plai +++ b/doc/user/tbl_plai @@ -4,8 +4,10 @@ @Begin @PP Tables work well with plain text output (Section {@NumberOf plain}): +tables. @RawIndex { tables } +tables.plaintext @SubIndex { plain text output } plain.text.tables @Index { plain text tables } -@CD @OneRow -1px @Break @F @Verbatim { +@CD @OneRow 0.9 @Scale 1.0fx @Break @F @Verbatim { ................................................... . . . . Johnson . Johnson suddenly uttered, in . @@ -48,7 +50,7 @@ document. @PP @Code "@Tbl" changes the default values of several options when used in a plain text document: -@ID @Code @Verbatim { +@ID @OneRow @Code @Verbatim { @Tbl marginvertical { 2f } marginhorizontal { 2s } @@ -62,6 +64,9 @@ multiples of {@Code "1f"}, and horizontal distances whole multiples of {@Code "1s"}, since this avoids fractional spacing which cannot be successful in plain text files and produces quite messy results. There is also a @Code ruleplainchar option for changing the character used to +tables. @RawIndex { tables } +tables.ruleplainchar @SubIndex { @Code "ruleplainchar" option } +ruleplainchar.tables @Index { @Code "ruleplainchar" option (tables) } draw rules. For example, @ID @Code @Verbatim { @Tbl diff --git a/doc/user/tbl_rows b/doc/user/tbl_rows index d7950b1..bbc620a 100644 --- a/doc/user/tbl_rows +++ b/doc/user/tbl_rows @@ -6,6 +6,8 @@ We've seen that the @Code aformat option of @Code "@Tbl" determines the format of the rows introduced by the @Code "@Rowa" symbol. There are eight row format options: {@Code aformat}, +tables. @RawIndex { tables } +tables.row.formats @SubIndex { row formats } row.formats @Index { row formats in tables } {@Code bformat}, and so on up to {@Code hformat}, and for each there is a corresponding {@Code "@Row"} symbol: {@Code "@Rowa"}, {@Code "@Rowb"}, @@ -47,6 +49,9 @@ formatted using {@Code bformat}. @PP In addition to the eight @Code format options of {@Code "@Tbl"}, it is possible to specify the format of a row at the row itself, using the +tables. @RawIndex { tables } +tables.format.option @SubIndex { @Code "format" option } +format.tables @Index { @Code "format" option (tables) } @Code "@Row" symbol like this: @ID @OneRow @Code @Verbatim { @Row diff --git a/doc/user/tbl_rule b/doc/user/tbl_rule index 25858df..63cdb3c 100644 --- a/doc/user/tbl_rule +++ b/doc/user/tbl_rule @@ -4,6 +4,9 @@ @Begin @PP There is a @Code "rule" option for drawing a rule around a cell: +tables. @RawIndex { tables } +tables.rule @SubIndex { @Code "rule" options } +rule.tables @Index { @Code "rule" options (tables) } @ID @OneRow @Code "@Cell rule { yes }" Other values are {@Code no} (the default), {@Code single} (the same as {@Code yes}), and {@Code double} (for a diff --git a/doc/user/tbl_setu b/doc/user/tbl_setu index 74bdb9a..6caedbb 100644 --- a/doc/user/tbl_setu +++ b/doc/user/tbl_setu @@ -4,7 +4,10 @@ @Begin @PP All of the options apart from the @Code format options can be changed -setup.files.tables @Index { setup files for tables } +tables. @RawIndex { tables } +tables.setup @SubIndex { setup file } +setup.files. @RawIndex { setup files } +setup.files.for.tables @SubIndex { for tables } in the @Code { tbl } setup file, in which case the new values become the default values for every table in the document. This section explains how to do it. Changing options in the setup file can save a @@ -37,7 +40,7 @@ of the @Code tbl package, so it should not be changed. After it comes the @Code "@TblSetup" @Code "@Use" clause, which looks like this: @ID @OneRow @Code @Verbatim { @Use { @TblSetup - # paint { nopaint } + # paint { none } # font { } # break { } } @@ -48,7 +51,7 @@ example, suppose you want all table entries two points smaller than the surrounding text: @ID @OneRow @Code @Verbatim { @Use { @TblSetup - # paint { nopaint } + # paint { none } font { -2p } # break { } } diff --git a/doc/user/tbl_span b/doc/user/tbl_span index ec568dc..f6757c9 100644 --- a/doc/user/tbl_span +++ b/doc/user/tbl_span @@ -4,10 +4,18 @@ @Begin @PP To make a cell span across several columns, precede the @Code "@Cell" +tables. @RawIndex { tables } +tables.span @SubIndex { spanning columns and rows } spanning.columns @Index { spanning columns and rows in tables } symbol with @Code "@StartHSpan" and replace each spanned cell's +tables. @RawIndex { tables } +tables.starthspan @SubIndex { @Code "@StartHSpan" option } +starthspan.tables @Index { @Code "@StartHSpan" option (tables) } @Code "@Cell" symbol with {@Code "@HSpan"}, like this: -@ID @OneRow @Code @Verbatim { +tables. @RawIndex { tables } +tables.hspan @SubIndex { @Code "@HSpan" option } +hspan.tables @Index { @Code "@HSpan" option (tables) } +@ID @OneRow -1px @Break @Code @Verbatim { @Tbl rule { yes } aformat { @StartHSpan @Cell indent { ctr } @B A | @HSpan | @HSpan } @@ -51,8 +59,14 @@ but actually has a use (Section {@NumberOf tbl_alig}). @PP Spanning rows work in the same way; the spanning cell is preceded by {@Code "@StartVSpan"}, and the spanned cells are replaced by +tables. @RawIndex { tables } +tables.startvspan @SubIndex { @Code "@StartVSpan" option } +startvspan.tables @Index { @Code "@StartVSpan" option (tables) } +tables. @RawIndex { tables } +tables.vspan @SubIndex { @Code "@VSpan" option } +vspan.tables @Index { @Code "@VSpan" option (tables) } {@Code "@VSpan"}: -@ID @OneRow @Code @Verbatim { +@ID @OneRow -1px @Break @Code @Verbatim { @Tbl rule { yes } aformat { @StartVSpan @Cell @I A | @Cell B | @Cell C } @@ -96,7 +110,7 @@ The result of this is C { Introductory Computer Science } } Here is a notorious larger example, the `spiral': -@ID @OneRow @Code @Verbatim { +@ID @OneRow -1px @Break @Code @Verbatim { @QuotedDisplay @Tbl rule { yes } { @@ -131,17 +145,14 @@ It is important when constructing mind-boggling tables like this one to ensure that every format has exactly the same number of @Code "|" symbols. Otherwise the number of columns will differ from row to row. The names given to the entries ({@Code "A"}, {@Code "B"}, {@Code "C"}, -etc.) are quite irrelevant: having a @Code "@Cell D" in one row and a -@Code "@Cell D" in another does not mean that the cells will appear in -the same column. -# @PP -# There is an asymmetry in the spiral above: the first column -# occupies slightly more space than the other two. This arises -# because the left margin of the leftmost column is excluded from the -# calculation of how much space is available. This anomaly might be -# corrected some day. +etc.) are quite irrelevant: having a @Code "@Cell D" in one row and +a @Code "@Cell D" in another does not mean that the cells will appear +in the same column. @PP There is a @Code "@StartHVSpan" symbol which combines the effects +tables. @RawIndex { tables } +tables.starthvspan @SubIndex { @Code "@StartHVSpan" option } +starthvspan.tables @Index { @Code "@StartHVSpan" option (tables) } of @Code "@StartHSpan" and {@Code "@StartVSpan"}. You need to use it in this arrangement: @ID @OneRow @Tbl diff --git a/doc/user/tbl_summ b/doc/user/tbl_summ index f5d5343..259cf99 100644 --- a/doc/user/tbl_summ +++ b/doc/user/tbl_summ @@ -4,6 +4,8 @@ @Begin @PP This summary applies to all @Code "@Tbl" options except the @Code format +tables. @RawIndex { tables } +tables.summary @SubIndex { summary of all options } options described in Section {@NumberOf tbl_rows}. Here is the complete list of these options, one option per line, showing its alternative spellings, default values (PostScript and PDF, and plain text) from the setup @@ -47,9 +49,13 @@ plain text } rulebelow { yes } @Rowa A { paint p } - B { nopaint } + B { none } D { any colour from Section {@NumberOf colour} } @Rowa + A { texture t } + B { solid } + D { any texture from Section {@NumberOf textures} } +@Rowa A { background bg } D { any object } @Rowa diff --git a/doc/user/tbl_widt b/doc/user/tbl_widt index f988962..f2d799d 100644 --- a/doc/user/tbl_widt +++ b/doc/user/tbl_widt @@ -4,6 +4,8 @@ @Begin @PP Lout is quite good a choosing suitable widths for cells. It leaves +column.width @RawIndex { column width } +column.width.in.tables @SubIndex { in tables } narrow cells at their natural width, then uses paragraph breaking to reduce the wider cells to a common width which is as large as the available space allows: @@ -23,6 +25,10 @@ parts; many varieties. } This usually looks good, but if you need something else, there is the @Code width option: +tables. @RawIndex { tables } +tables.width @SubIndex { @Code "width" option } +width. @RawIndex { @Code "width" option } +width.in.tables @SubIndex { in tables } @ID @OneRow @Code "@Cell width { 3c }" Here we have asked for a cell width of three centimetres; this includes the cell margins. When using @Code width to fine-tune the appearance of @@ -34,6 +40,8 @@ given a common width equal to the width of the widest. One simple way to approximate this is to give these cells the same @Code width value. The @Code width option also has a special value, {@Code "expand"}. All cells with @Code "width { expand }" are assigned a common width +tables. @RawIndex { tables } +tables.expand @SubIndex { @Code expand cell width } expand.cell.width @Index { @Code expand cell width in tables } equal to the maximum amount permitted by the available space. For example, @ID @OneRow @Code @Verbatim { @@ -78,6 +86,10 @@ the result will be with the total table width reduced to four inches. @PP There is an analogous @Code height option which makes a cell take on +tables. @RawIndex { tables } +tables.height @SubIndex { @Code height option } +height. @RawIndex { @Code "height" option } +height.in.tables @SubIndex { in tables } a particular fixed height, again including margins. Make sure there is enough height in the cell to hold its entry when you use this option. The @Code "expand" value is not available for height. diff --git a/doc/user/typ_book b/doc/user/typ_book index 059029a..6daa713 100644 --- a/doc/user/typ_book +++ b/doc/user/typ_book @@ -7,7 +7,7 @@ To produce a book, start off with the @Code book setup file and the books. @Index { books } book. @Index @Code "@Book" @Code "@Book" symbol: -@ID @OneRow @Code { +@ID @OneRow -1px @Break @Code { "@SysInclude { book }" "@Book" " @Title {}" @@ -28,6 +28,10 @@ book. @Index @Code "@Book" " @FirstPageNumber { 1 }" " @IntroFirstPageNumber { 1 }" " @OptimizePages { No }" +" @GlossaryText { @Null }" +" @IndexText { @Null }" +" @IndexAText { @Null }" +" @IndexBText { @Null }" "//" } This shows all the options of @Code "@Book" with their default values. As @@ -128,6 +132,11 @@ optimizer to cycle, never settling on a single final best version; this is usually caused by footnotes or floating figures inserted at points which end up near page boundaries. @PP +The {@Code "@GlossaryText"}, {@Code "@IndexText"}, {@Code "@IndexAText"}, +and {@Code "@IndexBText"} symbols allow you to insert some arbitrary +text after the title of the glossary, index, etc., and before the +entries. +@PP After the compulsory @Code "//" comes an optional preface: preface. @Index @Code "@Preface" @ID @OneRow @Code { @@ -352,7 +361,8 @@ vertical space between the chapter heading and body. separate.intro.numbering @Index @Code "@SeparateIntroNumbering" determines whether the introductory part of the book is to have a separate numbering sequence or not. @Code "@ReferencesBeforeAppendices" -references.before.appendices @Index @Code "@ReferencesBeforeAppendices" +references. @RawIndex references +references.references.before.appendices @SubIndex @Code "@ReferencesBeforeAppendices" determines whether any final list of references appears before or after any appendices. @Code "@ChapterWord" determines the word used in chapter titles; its default value, {@Code "chapter"}, diff --git a/doc/user/typ_ordi b/doc/user/typ_ordi index 9fbd07a..e171115 100644 --- a/doc/user/typ_ordi +++ b/doc/user/typ_ordi @@ -42,7 +42,6 @@ values. As usual with options, the options of {@Code "@Document"} may be given in any order, and only the ones that need to be changed need be given at all. Notice the @Code "//" after the last option. Its meaning is beyond our -"//" @Index { @Code "//" symbol } scope, but total disaster will ensue if it is forgotten. The @Code "@Doc" symbol is an abbreviation for {@Code "@Document //"}, which is why you don't need @Code "//" with {@Code "@Doc"}. diff --git a/doc/user/typ_repo b/doc/user/typ_repo index a536b12..ece7fe0 100644 --- a/doc/user/typ_repo +++ b/doc/user/typ_repo @@ -9,7 +9,7 @@ reports. @Index { reports } technical.reports. @Index { technical reports } report. @Index @Code "@Report" file and the @Code "@Report" symbol: -@ID @OneRow @Code { +@ID @OneRow -1px @Break @Code { "@SysInclude { report }" "@Report" " @Title {}" @@ -31,20 +31,17 @@ file and the @Code "@Report" symbol: " @AbstractDisplay { Yes }" " @AbstractTitle { Abstract }" " @Abstract {}" +" @GlossaryText { @Null }" +" @IndexText { @Null }" +" @IndexAText { @Null }" +" @IndexBText { @Null }" "//" } This shows all the options of {@Code "@Report"} @FootNote { -Version 3.13 of Lout is not completely upwardly compatible with -previous versions in its handling of technical reports. The change -concerns the abstract, and if you see the error message -@ID @Code "symbol @Abstract unknown or misspelt" -you probably need to convert your document. To convert an older -document to Version 3.13, move any @Code "@Abstract" from after the -@Code "//" to before it, delete any options to the @Code "@Abstract" -symbol, and delete any initial paragraph symbol within the abstract. -You can use the @Code "@AbstractTitle" option described in this section -to change the title of the abstract. +Before Version 3.13, @Code "@Abstract" followed "//" rather than +preceded it, and had some options that are now withdrawn. Old +documents may therefore need some superficial rearrangement. } with their default values. As usual with options, they may be given in any order, and only the ones whose values need to be changed need be @@ -187,6 +184,11 @@ abstract. @Index @Code "@Abstract" abstract itself; it may be empty or absent, in which case there will be no abstract. The abstract may contain footnotes in the usual way. @PP +The {@Code "@GlossaryText"}, {@Code "@IndexText"}, {@Code "@IndexAText"}, +and {@Code "@IndexBText"} symbols allow you to insert some arbitrary +text after the title of the glossary, index, etc., and before the +entries. +@PP After the compulsory {@Code "//"} comes the report body in the form of a sequence of sections: section.reports @SubIndex { in reports } diff --git a/doc/user/vbgr b/doc/user/vbgr new file mode 100644 index 0000000..48f1466 --- /dev/null +++ b/doc/user/vbgr @@ -0,0 +1,8 @@ +gvim bgr +gvim bgr_colo +gvim bgr_text +gvim bgr_boxs +gvim bgr_outl +gvim bgr_rota +gvim bgr_scal +gvim bgr_incl diff --git a/doc/user/vdia b/doc/user/vdia new file mode 100644 index 0000000..27c456c --- /dev/null +++ b/doc/user/vdia @@ -0,0 +1,13 @@ +gvim dia +gvim dia_intr +gvim dia_node +gvim dia_link +gvim dia_tags +gvim dia_labe +gvim dia_posi +gvim dia_tree +gvim dia_synt +gvim dia_erro +gvim dia_defi +gvim dia_geom +gvim dia_summ diff --git a/doc/user/vequ b/doc/user/vequ new file mode 100644 index 0000000..87cdf93 --- /dev/null +++ b/doc/user/vequ @@ -0,0 +1,9 @@ +gvim equ +gvim equ_intr +gvim equ_symb +gvim equ_vert +gvim equ_spac +gvim equ_disp +gvim equ_defs +gvim equ_summ +gvim equ_tequ diff --git a/doc/user/vfmt b/doc/user/vfmt index 39d5efe..3e6af88 100644 --- a/doc/user/vfmt +++ b/doc/user/vfmt @@ -1 +1,5 @@ -vi fmt fmt_setu fmt_size fmt_marg fmt_head +gvim fmt +gvim fmt_setu +gvim fmt_size +gvim fmt_marg +gvim fmt_head diff --git a/doc/user/vgra b/doc/user/vgra new file mode 100644 index 0000000..a4d173d --- /dev/null +++ b/doc/user/vgra @@ -0,0 +1,11 @@ +gvim gra +gvim gra_intr +gvim gra_over +gvim gra_capt +gvim gra_tick +gvim gra_data +gvim gra_plac +gvim gra_func +gvim gra_keys +gvim gra_erro +gvim gra_summ diff --git a/doc/user/vpie b/doc/user/vpie new file mode 100644 index 0000000..5f9e2e4 --- /dev/null +++ b/doc/user/vpie @@ -0,0 +1,15 @@ +gvim pie +sleep 2 +gvim pie_intr +sleep 2 +gvim pie_slic +sleep 2 +gvim pie_over +sleep 2 +gvim pie_capt +sleep 2 +gvim pie_labe +sleep 2 +gvim pie_erro +sleep 2 +gvim pie_summ diff --git a/doc/user/vprg b/doc/user/vprg index 935d4af..5922150 100644 --- a/doc/user/vprg +++ b/doc/user/vprg @@ -1 +1,12 @@ -vi prg prg_lone prg_embe prg_opti prg_chan prg_tabs prg_form prg_comm prg_prog prg_pipe prg_erro prg_perl +gvim prg +gvim prg_lone +gvim prg_embe +gvim prg_opti +gvim prg_chan +gvim prg_tabs +gvim prg_form +gvim prg_comm +gvim prg_prog +gvim prg_pipe +gvim prg_erro +gvim prg_perl diff --git a/doc/user/vref b/doc/user/vref index 55e3596..7e85672 100644 --- a/doc/user/vref +++ b/doc/user/vref @@ -1 +1,7 @@ -vi ref ref_sett ref_cite ref_labe ref_entr ref_chan ref_crea +gvim ref +gvim ref_sett +gvim ref_cite +gvim ref_labe +gvim ref_entr +gvim ref_chan +gvim ref_crea diff --git a/doc/user/vtbl b/doc/user/vtbl index 164c3f6..68159ce 100644 --- a/doc/user/vtbl +++ b/doc/user/vtbl @@ -1,2 +1,15 @@ -vi tbl tbl_intr tbl_cell tbl_rows tbl_rule tbl_marg tbl_widt tbl_inde \ - tbl_alig tbl_span tbl_mark tbl_mult tbl_plai tbl_setu tbl_summ +gvim tbl +gvim tbl_intr +gvim tbl_cell +gvim tbl_rows +gvim tbl_rule +gvim tbl_marg +gvim tbl_widt +gvim tbl_inde +gvim tbl_alig +gvim tbl_span +gvim tbl_mark +gvim tbl_mult +gvim tbl_plai +gvim tbl_setu +gvim tbl_summ |