diff options
Diffstat (limited to 'doc/user')
130 files changed, 20473 insertions, 0 deletions
diff --git a/doc/user/README b/doc/user/README new file mode 100644 index 0000000..fd69ccb --- /dev/null +++ b/doc/user/README @@ -0,0 +1,37 @@ +Directory lout/doc/user + +This directory contains the Lout source files for the User's Guide +to the Lout Document Formatting System. To produce the Guide, +type the command + + lout all > op + +in this directory. This must be done five times to completely +resolve all cross references, although the PostScript file op is +printable after the first run. Auxiliary files with .li and .ld +suffixes will be created in this directory. + +The first run will produce a large number of error messages, +nearly all beginning with "unresolved cross reference". These +should gradually go away on later runs. The following shows the +error message output on the fifth run for A4 size printing: + +lout file "cpp_tabs" (from "cpp" line 24, from "all" line 38): + 53,23: c2lout: C text ended inside a comment + 55,35: c2lout: C text ended inside a comment + +These two warnings point to two places where a C program text ended +inside a comment, which in these cases was deliberate so is no problem. +If you set the document in Letter size paper, you will also get a +couple of other warning messages pointing to places where Lout had +to slightly scale a display to fit the smaller page. + +Optimal page breaking has been turned off for this document owing to +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.17.user.ps.gz". + +Jeffrey H. Kingston +17 September 1999 diff --git a/doc/user/all b/doc/user/all new file mode 100644 index 0000000..1b131f6 --- /dev/null +++ b/doc/user/all @@ -0,0 +1,47 @@ +@SysInclude { tab } +@SysInclude { tbl } +@SysInclude { eq } +@SysInclude { fig } +@SysInclude { graph } +@SysInclude { pas } +@SysInclude { diag } +@SysInclude { cprint } +@SysInclude { book } +# @Include { letterbook } # for testing Letter size formatting + +@SysDatabase @Reference { loutrefs } + +@Book + @Title { A User's Guide to the + +Lout + +Document Formatting System +} + @Author { Jeffrey H. Kingston } + @Edition { Version 3.17 +September, 1999 } + @Publisher { +Copyright @CopyRight 1991, 1999 Jeffrey H. Kingston, +Basser Department of Computer Science, +The University of Sydney 2006, Australia. ISBN 0 86758 951 5. +} + @InitialLanguage { English } + # @OptimizePages { Yes } +// + +@Include { preface } +@Include { bas } +@Include { str } +@Include { typ } +@Include { fmt } +@Include { ref } +@Include { tbl } +@Include { equ } +@Include { bgr } +@Include { dia } +@Include { gra } +@Include { cpp } +@Include { pascal } +@Include { ap_qck } +@Include { ap_byp } diff --git a/doc/user/ap_byp b/doc/user/ap_byp new file mode 100644 index 0000000..a1c1bd7 --- /dev/null +++ b/doc/user/ap_byp @@ -0,0 +1,98 @@ +@Appendix + @Title { Bypass Symbols } + @Tag { bypass } +@Begin +@PP +The `bypass' symbols described in this appendix are intended to be +used only in Lout which is generated by computer programs. Their +purpose is to bypass the Lout cross reference database, and so reduce +the number of passes needed to finalise a document. These symbols +should not be used by people, because that would only lead back to the +consistency problems that prompted the introduction of cross references +in the first place. +@PP +To produce a bypass table of contents, set the @Code "@MakeContents" +setup file option to @Code "Bypass" and use @Code "@BypassContentsEntry" +symbols at the outermost level just before the introduction or first +chapter: +@ID @Tab + @Fmta { @Col @Code A ! @Col ! @Col B } + vmargin { 0.5vx } +{ +@Rowa + A { "@BypassContentsEntry" } +@Rowa + A { " indent { 0f }" } + B { the indent, e.g. {@Code "0f"}, {@Code "2f"}, {@Code "4f"} ... } +@Rowa + A { " number {}" } + B { the section (etc.) number e.g. {@Code "5.2"} } +@Rowa + A { " title {}" } + B { the section (etc.) title e.g. @Code "Azaleas" } +@Rowa + A { " pagenum {}" } + B { the page number e.g. @Code "@PageOf azaleas" } +} +For major entries such as chapters, use @Code "@BypassMajorContentsEntry" +with the same options. This increases the vertical spacing and uses +bold font. When @Code "@MakeContents" is {@Code "Bypass"}, no contents +entries will be produced automatically. +@PP +To bypass Lout's automatic numbering of large-scale structure symbols, +use the @Code "@BypassNumber" option: +@ID @Code { +"@Section" +" @Title { Azaleas }" +" @Tag { azaleas }" +" @BypassNumber { 5.2 }" +"..." +} +Give the full `path number' (5.2, B.3 or whatever) of the symbol. There is +a @Code "@BypassNumber" option for every symbol that has a @Code "@Title" +option and is usually assigned a number automatically by Lout, plus +@Code "@Figure" and {@Code "@Table"}. No changes to the setup file are +required in order to use {@Code "@BypassNumber"}, and it is permitted +for some large-scale structure symbols to have this option and others not. +@PP +To produce a bypass reference list, set the @Code "@MakeReferences" +setup file option to @Code "Bypass" and place reference entries at the +end of the document, after the last chapter or other large-scale structure +symbol but before any bypass index entries (see below), like this: +@ID @Code { +"@BypassReference" +" label { [Kin94a] }" +" value { @RefPrint kingston1995lout.expert }" +} +The two options are objects which become the label and value of the +reference entry. The @Code "value" option can be any object, including +an explicit reference; but @Code "@RefPrint" does not introduce any +cross-referencing delay if the @Code "@Reference" symbols lie in a +separate database file. No sorting or removal of duplicate entries +will be done by Lout. When @Code "@MakeReferences" is {@Code "Bypass"}, +@Code "@Cite" and related symbols are ignored. +@PP +There is also @Code "@BypassChapReference" with the same options for +producing bypass chapter reference lists; these symbols should be +placed at the outer level immediately after the preface, introduction, +chapter or appendix that they refer to. +@PP +To produce bypass indexes, set the @Code "@MakeIndex" setup file +option to {@Code Bypass} and use the @Code "@BypassRawIndex" symbol +repeatedly at the very end of the document, enclosed in +@Code "@BypassBeginIndex" and @Code "@BypassEndIndex" symbols: +@ID @Code { +"@BypassBeginIndex" +"@BypassRawIndex indent { 0f } { Azaleas, @PageOf azaleas }" +"..." +"@BypassEndIndex" +} +The @Code "indent" option gives the indent ({@Code "0f"}, @Code {"1f"}, +@Code {2f}, etc.), and the right parameter is as for @Code "@RawIndex". No +@Code "@PageMark" operations, sorting, merging, or attachment of page +numbers will be done by Lout. When @Code "@MakeIndex" is {@Code Bypass}, +@Code "@Index" and related symbols are ignored. At present, bypass +index symbols work only in books, not with ordinary documents or +technical reports. There are corresponding symbols for creating +bypass indexes A and B. +@End @Appendix diff --git a/doc/user/ap_qck b/doc/user/ap_qck new file mode 100644 index 0000000..92ea7ad --- /dev/null +++ b/doc/user/ap_qck @@ -0,0 +1,369 @@ +@Appendix + @Title { Lout Quick Reference Guide } +@Begin +10p @Font 1.15fx @Break @OneCol +@Tab @Fmta { @Col 20c @Wide A ! @Col 20c @Wide B } +{ +@Rowa A { +@Heading { 1. Running Lout } +@LD @Code { +"lout filename > postscript.ps" +} + +@LP +@Heading { 2. Ordinary documents (simple form) } +@LD @Code { +"@SysInclude { doc }" +"@Doc @Text @Begin" +"..." +"@End @Text" +} + +@LP +@Heading { 3. Ordinary documents (full form) } +@LD @Code { +"@SysInclude { doc }" +"@Document" +" @InitialFont { Times Base 12p }" +" @InitialBreak { adjust 1.2fx hyphen }" +" @InitialLanguage { English }" +" @PageHeaders { Simple }" +" @FirstPageNumber { 1 }" +" @ColumnNumber { 1 }" +" @PageOrientation { Portrait }" +"//" +"@Text @Begin" +"..." +"@BeginSections" +"@Section ... @End @Section" +"@EndSections" +"@End @Text" +} + +@LP +@Heading { 4. Technical reports } +@LD @Code { +"@SysInclude { report }" +"@Report" +" @Title { ... }" +" @Author { ... }" +" @Institution { ... }" +" @DateLine { No }" +" @CoverSheet { Yes }" +" @InitialFont { Times Base 12p }" +" @InitialBreak { adjust 1.2fx hyphen }" +" @InitialLanguage { English }" +" @PageHeaders { Simple }" +" @FirstPageNumber { 1 }" +" @ColumnNumber { 1 }" +"//" +"@Abstract ... @End @Abstract" +"@Section ... @End @Section" +"@Appendix ... @End @Appendix" +} +} + +B { +@Heading { 5. Large-scale structure symbols } +@LL +@LI @Code { +"@Section" +" @Title { ... }" +" @RunningTitle { ... }" +" @Tag { ... }" +"@Begin" +"@PP" +"..." +"@End @Section" +} +@LI lines @Break { +@Code "@Section / @SubSection / @SubSubSection" +@Code "@Appendix / @SubAppendix / @SubSubAppendix" +@Code "@BeginSubSections" ... @Code "@EndSubSections" if inner. +} +@EndList + +@LP +@Heading { 6. Cross references } +@LD @Tab + @Fmta { @Col @Code A ! @Col ! @Col @Code B } +{ +@Rowa + A { "@Tag { foo }" } + B { "@PageOf foo" } +@Rowa + A { "@PageMark foo" } + B { "@NumberOf foo" } +} + +@LP +@Heading { 7. Font changes } +@LL +@LI @Tab + @Fmta { @Col @Code A ! @Col @Code B } + vmargin { 0.5vx } +{ +@Rowa + A { "@B { bold font }" } + B { "@I { italic font }" } +@Rowa + A { "@BI { bold-italic font }" } + B { "@R { Roman font }" } +@Rowa + A { "@S { small-caps font}" } + B { "@F { fixed-width font }" } +@Rowa + B { "@II { italic bold or Roman }" } +} +@LI @Code { +"{ family face size } @Font { ... }" +} +@LI @Code { +"Times Helvetica Courier ..." +"Base Slope Bold BoldSlope ..." +"10p 12p +2p -2p 2.0f ..." +} +@EndList + +@LP +@Heading { 8. Paragraph breaking styles } +@LL +@LI @Code { +"{ breakstyle linesep hyphen } @Break { ... }" +} +@LI @Code { +"adjust ragged lines clines ..." +"1.2fx 2vx 0.9vx ..." +"hyphen nohyphen" +} +@EndList + +@LP +@Heading { 9. New paragraph and new page } +@LD @Tab + @Fmta { @Col @Code A ! @Col B } + vmargin { 0.5vx } +{ +@Rowa A { "@PP" } B { Plain paragraph } +@Rowa A { "@LP" } B { Left paragraph } +@Rowa A { "@LLP" } B { New line } +@Rowa A { "@DP" } B { Display paragraph } +@Rowa A { "@NP" } B { New page } +@Rowa A { "@CNP" } B { Conditional new page } +} +} + +} # end first table +@LP +10p @Font 1.15fx @Break @OneCol +@Tab @Fmta { @Col 20c @Wide A ! @Col 20c @Wide B } +{ +@Rowa A { +@Heading { 10. Displays and headings } +@LL +@LI @Code { +"@CD @Heading { A centred heading }" +"@ID { An indented display }" +} +@LI @Tab + @Fmta { @Col @Code A ! @Col @Code B } + vmargin { 0.5vx } +{ +@Rowa A { "@D" } B { "@Display" } +@Rowa A { "@LD" } B { "@LeftDisplay" } +@Rowa A { "@ID" } B { "@IndentedDisplay" } +@Rowa A { "@QD" } B { "@QuotedDisplay" } +@Rowa A { "@CD" } B { "@CentredDisplay" } +@Rowa B { "@CenteredDisplay" } +@Rowa B { "@RightDisplay" } +} +@EndList + +@LP +@Heading { 11. Lists} +@LL +@LI @Code { +"@List" +"@ListItem { A list item }" +"@ListItem { Another list item }" +"@EndList" +} +@LI @Tab + @Fmta { @Col @Code A ! @Col @Code B } + vmargin { 0.5vx } +{ +@Rowa + A { "@L" } + B { "@List" } +@Rowa + A { "@LL" } + B { "@LeftList" } +@Rowa + A { "@IL" } + B { "@IndentedList" } +@Rowa + A { "@QL" } + B { "@QuotedList" } +@Rowa + A { "@CL" } + B { "@CentredList" } +@Rowa + B { "@CenteredList" } +@Rowa + A { "@NL" } + B { "@NumberedList" } +@Rowa + A { "@RL" } + B { "@RomanList" } +@Rowa + A { "@UCRL" } + B { "@UCRomanList" } +@Rowa + A { "@AL" } + B { "@AlphaList" } +@Rowa + A { "@UCAL" } + B { "@UCAlphaList" } +@Rowa + A { "@PNL" } + B { "@ParenNumberedList" } +@Rowa + A { "@PRL" } + B { "@ParenRomanList" } +@Rowa + A { "@PUCRL" } + B { "@ParenUCRomanList" } +@Rowa + A { "@PAL" } + B { "@ParenAlphaList" } +@Rowa + A { "@PUCAL" } + B { "@ParenUCAlphaList" } +@Rowa + A { "@BL" } + B { "@BulletList" } +@Rowa + A { "@SL" } + B { "@StarList" } +@Rowa + A { "@DL" } + B { "@DashList" } +} +@LI @Code { +"@TaggedList" +"@TagItem { label } { A list item }" +"@TagItem { label } { Another list item }" +"@EndList" +} +@LI @Tab + @Fmta { @Col @Code A ! @Col @Code B } + vmargin { 0.5vx } +{ +@Rowa + A { "@TL" } + B { "@TaggedList" } +@Rowa + A { "@WTL" } + B { "@WideTaggedList" } +@Rowa + A { "@VWTL" } + B { "@VeryWideTaggedList" } +} +@EndList + +@LP +@Heading { 12. Footnotes, endnotes, margin notes } +@LD @Tab + @Fmta { @Col @Code A ! @Col @Code B } + vmargin { 0.5vx } +{ +@Rowa + A { "@FootNote { ... }" } + B { "@EndNote { ... }" } +@Rowa + A { "@LeftNote { ... }" } + B { "@RightNote { ... }" } +@Rowa + A { "@OuterNote { ... }" } + B { "@InnerNote { ... }" } +} +} + +B { +@Heading { 13. Floating figures and tables } +@LD @Tab + @Fmta { @Col @Code A ! @Col ! @Col ! @Col @Code B } +{ +@Rowa + A { +"@Figure" +" @Caption { ... }" +" @Tag { ... }" +"@Begin" +"..." +"@End @Figure" +} + B { +"@Table" +" @Caption { ... }" +" @Tag { ... }" +"@Begin" +"..." +"@End @Table" +} +} + +@LP +@Heading { 14. Tables } +@LD @Code { +"@SysInclude { tbl }" +"@SysInclude { doc }" +"..." +"@Tbl" +" aformat { @Cell A | @Cell B }" +" marginvertical { 0.5vx }" +"{" +"@Rowa" +" A { ... }" +" B { ... }" +"@Rowa" +" ..." +"}" +} + +@LP +@Heading { 15. Equations } +@LD @Code { +"@SysInclude { eq }" +"@SysInclude { doc }" +"..." +"@Eq { sum from i=0 to n { r sup i over sqrt pi } }" +} + +@LP +@Heading { 16. Basic graphics } +@LD @Code { +"grey @Colour { ... }" +"gray @Color { ... }" +"@Box { ... }" +"@CurveBox { ... }" +"@ShadowBox { ... }" +"60d @Rotate { ... }" +"0.71 @Scale { ... }" +"@QuotedDisplay @Scale { ... }" +"@IncludeGraphic filename.eps" +} + +@LP +@Heading { 17. Miscellaneous } +@LD lines @Break { +@Code "@Underline { will be underlined }" +@Code "@Date" +@Code "@Time" +@Code "German @Language { ... }" +@Code "\# comment to end of line" +@Code "\"#&/@^{}|~\"" (enclose these characters in quotes) +} +} +} # end second table +@End @Appendix diff --git a/doc/user/bas b/doc/user/bas new file mode 100644 index 0000000..239d35a --- /dev/null +++ b/doc/user/bas @@ -0,0 +1,31 @@ +@Chapter + @Title { The Basics } + @Tag { basics } +@Begin +@LP +The Lout document formatting system has been designed with the needs of +the ordinary user very much in mind. Although the features of Lout are +virtually endless, and include mathematical equations, diagrams made from +lines and shapes, bibliographic databases, and so on, the system is very +simple to use. +@BeginSections +@Include { bas_star } +@Include { bas_objs } +@Include { bas_spac } +@Include { bas_char } +@Include { bas_empt } +@Include { bas_font } +@Include { bas_head } +@Include { bas_par1 } +@Include { bas_par2 } +@Include { bas_line } +@Include { bas_hyph } +@Include { bas_unde } +@Include { bas_date } +@Include { bas_lang } +@Include { bas_supe } +@Include { bas_verb } +@Include { bas_drop } +@Include { bas_conv } +@EndSections +@End @Chapter diff --git a/doc/user/bas_char b/doc/user/bas_char new file mode 100644 index 0000000..7efa566 --- /dev/null +++ b/doc/user/bas_char @@ -0,0 +1,325 @@ +@Section + @Title { Characters } + @Tag { characters } +@Begin +@PP +The usual way to get characters into a document is simply to type them as +characters. @Index characters +we have been doing all along. However, for some characters this is not +possible, either because they have some special meaning, as @Code "{" +and @Code "}" do, or because the keyboard has no button for them. This +section explains how to get every possible character: every printable +character in the ISO-LATIN-1 character set, every character in the Adobe +Systems Symbol font, plus the characters {@Char quotesinglbase}, +{@Char quotedblbase}, {@Char ellipsis}, {@Char OE}, {@Char oe}, +{@Char quotedblleft}, {@Char quotedblright}, {@Char fi}, +{@Char fl}, {@Char endash}, {@Char emdash}, {@Char bullet}, {@Char dagger}, +{@Char daggerdbl}, {@Char florin}, {@Char fraction}, and @Euro. If it +exists at all, you will find it here. ISO-LATIN-2 and Russian characters +are available separately. In principle, there is no limit to the characters +available, but to go beyond those given in this section requires expertise +in defining encoding vectors and fonts @Cite { $kingston1995lout.expert}. +@PP +First up we have the characters that you get simply by typing +them. The characters themselves are shown at the left, and what you +type to get them at the right: +@ID @OneRow @Tab + vmargin { 0.5vx } + @Fmta { @Col @CC A ! @Col @Code A ! @Col ! @Col @CC B ! @Col @Code B ! + @Col ! @Col @CC C ! @Col @Code C ! @Col ! @Col @CC D ! @Col @Code D ! + @Col ! @Col @CC E ! @Col @Code E ! @Col ! @Col @CC F ! @Col @Code F } +{ +@Rowa A { ! } B { $ } C { % } D { ' } E { ( } F { ) } +@Rowa A { * } B { + } C { , } D { - } E { 0 } F { 1 } +@Rowa A { 2 } B { 3 } C { 4 } D { 5 } E { 6 } F { 7 } +@Rowa A { 8 } B { 9 } C { : } D { ; } E { < } F { = } +@Rowa A { > } B { ? } C { A } D { B } E { C } F { D } +@Rowa A { E } B { F } C { G } D { H } E { I } F { J } +@Rowa A { K } B { L } C { M } D { N } E { O } F { P } +@Rowa A { Q } B { R } C { S } D { T } E { U } F { V } +@Rowa A { W } B { X } C { Y } D { Z } E { [ } F { ] } +@Rowa A { _ } B { ` } C { a } D { b } E { c } F { d } +@Rowa A { e } B { f } C { g } D { h } E { i } F { j } +@Rowa A { k } B { l } C { m } D { n } E { o } F { p } +@Rowa A { q } B { r } C { s } D { t } E { u } F { v } +@Rowa A { w } B { x } C { y } D { z } E { } F { } +} +Next come characters that have buttons but have a special meaning if +they are typed directly, and consequently have to be enclosed in double +quotes to turn off this meaning: +quote.chars @Index { quote characters } +@ID @OneRow @Tab + @Fmta { @Col @CC A ! @Col @Code B ! @Col ! + @Col @CC C ! @Col @Code D ! @Col ! + @Col @CC E ! @Col @Code F ! @Col ! + @Col @CC G ! @Col @Code H ! @Col I + } +{ +@Rowa + A { "\"" } B { "\"\\\"\"" } + C { "#" } D { "\"#\"" } + E { "&" } F { "\"&\"" } + G { "/" } H { "\"/\"" } +@Rowa + A { "@" } B { "\"@\"" } + C { "\\" } D { "\"\\\\\"" } + E { "^" } F { "\"^\"" } + G { "{" } H { "\"{\"" } +@Rowa + A { "|" } B { "\"|\"" } + C { "}" } D { "\"}\"" } + E { "~" } F { "\"~\"" } + G { } H { "\" \"" } + I { (space character) } +} +If you think you want {@Code "\""}, you probably really want `` and '', +for which see below. You can place whole sequences of characters, special +or not, inside one pair of double quotes: +@ID @OneRow @Tab + @Fmta { @Col A ! @Col ! @Col @Code B } +{ +@Rowa + A { "jeff/includes/su_crest.eps" } + B { "\"jeff/includes/su_crest.eps\"" } +@Rowa + A { "\"@PP\"" } + B { "\"\\\"@PP\\\"\"" } +} +Next we have some miscellaneous characters which have been deemed +sufficiently important to deserve their own symbols: +@ID @OneRow @Tab + vmargin { 0.5vx } + @Fmta { @Col A ! @Col @Code B ! @Col ! @Col C ! @Col @Code D ! + @Col ! @Col E ! @Col @Code F } +{ + @Rowa + A { `` } + B { "``" } + C { ,, } + D { ",," } + E { -- } + F { "--" } + @Rowa + A { '' } + B { "''" } + C { ... } + D { "..." } + E { --- } + F { "---" } + @Rowa + A { @Bullet bullet @Index @Code "@Bullet" } + B { "@Bullet" } + C { @Star star @Index @Code "@Star" } + D { "@Star" } + E { @ParSym parsym @Index @Code "@ParSym" } + F { "@ParSym" } + @Rowa + A { @SectSym sectsym @Index @Code "@SectSym" } + B { "@SectSym" } + C { @Dagger dagger @Index @Code "@Dagger" } + D { "@Dagger" } + E { @DaggerDbl daggerdbl @Index @Code "@DaggerDbl" } + F { "@DaggerDbl"} + @Rowa + A { @CDot cdot @Index @Code "@CDot" } + B { "@CDot" } + C { @Sterling sterling @Index @Code "@Sterling" } + D { "@Sterling" } + E { @Yen yen @Index @Code "@Yen" } + F { "@Yen" } + @Rowa + A { @Florin florin @Index @Code "@Florin" } + B { "@Florin" } + C { @Degree degree @Index @Code "@Degree" } + D { "@Degree" } + E { @Minute minute @Index @Code "@Minute" } + F { "@Minute" } + @Rowa + A { @Second second @Index @Code "@Second" } + B { "@Second" } + C { @Lozenge lozenge @Index @Code "@Lozenge" } + D { "@Lozenge" } + E { @Multiply multiply @Index @Code "@Multiply"} + F { "@Multiply" } + @Rowa + A { @Divide divide @Index @Code "@Divide" } + B { "@Divide" } + C { @CopyRight copyright @Index @Code "@CopyRight" } + D { "@CopyRight"} + E { @Register register @Index @Code "@Register" } + F { "@Register" } + @Rowa + A { @TradeMark trademark @Index @Code "@TradeMark" } + B { "@TradeMark"} + C { @Euro euro @Index @Code "@Euro" } + D { "@Euro"} +} +Next we have the complete ISO-LATIN-1 character set, whose members you +iso.latin.1 @Index { ISO-LATIN-1 character set } +char. @Index { @Code "@Char" symbol } +get with the @Code "@Char" symbol followed by the name of the character +you want: +@ID @OneRow -3p @Font @Tab + hmargin { 0.1c } + vmargin { 0.4vo } + @Fmta { @Col @CC @Char A ! @Col @Code { "@Char" A } ! @Col ! + @Col @CC @Char B ! @Col @Code { "@Char" B } ! @Col ! + @Col @CC @Char C ! @Col @Code { "@Char" C } ! @Col ! + @Col @CC @Char D ! @Col @Code { "@Char" D } } + @Fmtb { @Col @CC @Char A ! @Col @Code { "@Char" A } ! @Col ! + @Col ! @Col ! @Col ! @Col ! @Col ! @Col ! @Col ! @Col } +{ +@Rowa A { space } B { exclam } C { quotedbl } D { numbersign } +@Rowa A { dollar } B { percent } C { ampersand } D { quoteright } +@Rowa A { parenleft } B { parenright } C { asterisk } D { plus } +@Rowa A { comma } B { hyphen } C { period } D { slash } +@Rowa A { zero } B { one } C { two } D { three } +@Rowa A { four } B { five } C { six } D { seven } +@Rowa A { eight } B { nine } C { colon } D { semicolon } +@Rowa A { less } B { equal } C { greater } D { question } +@Rowa A { at } B { A } C { B } D { C } +@Rowa A { D } B { E } C { F } D { G } +@Rowa A { H } B { I } C { J } D { K } +@Rowa A { L } B { M } C { N } D { O } +@Rowa A { P } B { Q } C { R } D { S } +@Rowa A { T } B { U } C { V } D { W } +@Rowa A { X } B { Y } C { Z } D { bracketleft } +@Rowa A { backslash } B { bracketright } C { asciicircum } D { underscore } +@Rowa A { quoteleft } B { a } C { b } D { c } +@Rowa A { d } B { e } C { f } D { g } +@Rowa A { h } B { i } C { j } D { k } +@Rowa A { l } B { m } C { n } D { o } +@Rowa A { p } B { q } C { r } D { s } +@Rowa A { t } B { u } C { v } D { w } +@Rowa A { x } B { y } C { z } D { braceleft } +@Rowa A { bar } B { braceright } C { asciitilde } D { dotlessi } +@Rowa A { grave } B { acute } C { circumflex } D { tilde } +@Rowa A { macron } B { breve } C { dotaccent } D { dieresis } +@Rowa A { ring } B { cedilla } C { hungarumlaut } D { ogonek } +@Rowa A { caron } B { space } C { exclamdown } D { cent } +@Rowa A { sterling } B { currency } C { yen } D { brokenbar } +@Rowa A { section } B { dieresis } C { copyright } D { ordfeminine } +@Rowa A { guillemotleft } B { logicalnot } C { hyphen } D { registered } +@Rowa A { macron } B { degree } C { plusminus } D { twosuperior } +@Rowa A { threesuperior } B { acute } C { mu } D { paragraph } +@Rowa A { periodcentered } B { cedilla } C { onesuperior } D { ordmasculine } +@Rowa A { guillemotright } B { onequarter } C { onehalf } D { threequarters } +@Rowa A { questiondown } B { Agrave } C { Aacute } D { Acircumflex } +@Rowa A { Atilde } B { Adieresis } C { Aring } D { AE } +@Rowa A { Ccedilla } B { Egrave } C { Eacute } D { Ecircumflex } +@Rowa A { Edieresis } B { Igrave } C { Iacute } D { Icircumflex } +@Rowa A { Idieresis } B { Eth } C { Ntilde } D { Ograve } +@Rowa A { Oacute } B { Ocircumflex } C { Otilde } D { Odieresis } +@Rowa A { multiply } B { Oslash } C { Ugrave } D { Uacute } +@Rowa A { Ucircumflex } B { Udieresis } C { Yacute } D { Thorn } +@Rowa A { germandbls } B { agrave } C { aacute } D { acircumflex } +@Rowa A { atilde } B { adieresis } C { aring } D { ae } +@Rowa A { ccedilla } B { egrave } C { eacute } D { ecircumflex } +@Rowa A { edieresis } B { igrave } C { iacute } D { icircumflex } +@Rowa A { idieresis } B { eth } C { ntilde } D { ograve } +@Rowa A { oacute } B { ocircumflex } C { otilde } D { odieresis } +@Rowa A { divide } B { oslash } C { ugrave } D { uacute } +@Rowa A { ucircumflex } B { udieresis } C { yacute } D { thorn } +@Rowb A { ydieresis } +} +Of course, many of these characters can also be typed directly, or with the +aid of double quotes, as we have seen. If your keyboard has accented +accented @Index { accented characters } +characters on it, you can type them directly too; if not, you need to +use the @Code "@Char" symbol, in which case you will probably need +braces as well: +@ID @Code "gar{@Char ccedilla}on" +to distinguish the @Code "@Char" symbol and the character name from +adjacent letters. +@PP +Next we have the Adobe Systems Symbol font, a treasure trove of +symbol. @Index { Symbol font } +sym. @Index { @Code "@Sym" symbol } +exotic characters obtained with the @Code "@Sym" symbol: +@ID @OneRow -3p @Font @Tab + hmargin { 0.1c } + vmargin { 0.4vo } + @Fmta { @Col @CC @Sym A ! @Col @Code { "@Sym" A } ! @Col ! + @Col @CC @Sym B ! @Col @Code { "@Sym" B } ! @Col ! + @Col @CC @Sym C ! @Col @Code { "@Sym" C } ! @Col ! + @Col @CC @Sym D ! @Col @Code { "@Sym" D } } +{ +@Rowa A { space } B { exclam } C { universal } D { numbersign } +@Rowa A { existential } B { percent } C { ampersand } D { suchthat } +@Rowa A { parenleft } B { parenright } C { asteriskmath } D { plus } +@Rowa A { comma } B { minus } C { period } D { slash } +@Rowa A { zero } B { one } C { two } D { three } +@Rowa A { four } B { five } C { six } D { seven } +@Rowa A { eight } B { nine } C { colon } D { semicolon } +@Rowa A { less } B { equal } C { greater } D { question } +@Rowa A { congruent } B { Alpha } C { Beta } D { Chi } +@Rowa A { Delta } B { Epsilon } C { Phi } D { Gamma } +@Rowa A { Eta } B { Iota } C { theta1 } D { Kappa } +@Rowa A { Lambda } B { Mu } C { Nu } D { Omicron } +@Rowa A { Pi } B { Theta } C { Rho } D { Sigma } +@Rowa A { Tau } B { Upsilon } C { sigma1 } D { Omega } +@Rowa A { Xi } B { Psi } C { Zeta } D { bracketleft } +@Rowa A { therefore } B { bracketright } C { perpendicular } D { underscore } +@Rowa A { radicalex } B { alpha } C { beta } D { chi } +@Rowa A { delta } B { epsilon } C { phi } D { gamma } +@Rowa A { eta } B { iota } C { phi1 } D { kappa } +@Rowa A { lambda } B { mu } C { nu } D { omicron } +@Rowa A { pi } B { theta } C { rho } D { sigma } +@Rowa A { tau } B { upsilon } C { omega1 } D { omega } +@Rowa A { xi } B { psi } C { zeta } D { braceleft } +@Rowa A { bar } B { braceright } C { similar } D { Upsilon1 } +@Rowa A { minute } B { lessequal } C { fraction } D { infinity } +@Rowa A { florin } B { club } C { diamond } D { heart } +@Rowa A { spade } B { arrowboth } C { arrowleft } D { arrowup } +@Rowa A { arrowright } B { arrowdown } C { degree } D { plusminus } +@Rowa A { second } B { greaterequal } C { multiply } D { proportional } +@Rowa A { partialdiff } B { bullet } C { divide } D { notequal } +@Rowa A { equivalence } B { approxequal } C { ellipsis } D { arrowvertex } +@Rowa A { arrowhorizex } B { carriagereturn } C { aleph } D { Ifraktur } +@Rowa A { Rfraktur } B { weierstrass } C { circlemultiply } D { circleplus } +@Rowa A { emptyset } B { intersection } C { union } D { propersuperset } +@Rowa A { reflexsuperset } B { notsubset } C {propersubset} D {reflexsubset} +@Rowa A { element } B { notelement } C { angle } D { gradient } +@Rowa A { registerserif } B { copyrightserif } C {trademarkserif} D {product} +@Rowa A { radical } B { dotmath } C { logicalnot } D { logicaland } +@Rowa A { logicalor } B { arrowdblboth } C { arrowdblleft } D { arrowdblup } +@Rowa A { arrowdblright } B { arrowdbldown } C { lozenge } D { angleleft } +@Rowa A { registersans } B { copyrightsans } C {trademarksans} D {summation} +@Rowa A { parenlefttp } B { parenleftex } C { parenleftbt } D {bracketlefttp} + vmargin { 0.5vx } +@Rowa A { bracketleftex } B { bracketleftbt } C {bracelefttp} D {braceleftmid} + vmargin { 0.5vx } +@Rowa A { braceleftbt } B { braceex } C { angleright } D { integral } + vmargin { 0.5vx } +@Rowa A { integraltp } B { integralex } C { integralbt } D { parenrighttp } + vmargin { 0.5vx } +@Rowa A {parenrightex} B {parenrightbt} C {bracketrighttp} D {bracketrightex} + vmargin { 0.5vx } +@Rowa A { bracketrightbt } B {bracerighttp} C {bracerightmid} D {bracerightbt} + vmargin { 0.5vx } +} +There is only one Symbol font; it does not come in bold or italic faces +like the other fonts. Typing @Code "@B @Sym alpha" is therefore useless, +and anyway there is no bold @Sym alpha character in any font distributed +with Lout (except see Section {@NumberOf teq}). +@PP +Finally we have a few more characters that you get with the @Code "@Char" +symbol, although they aren't ISO-LATIN-1 characters. +@ID @OneRow -3p @Font @Tab + hmargin { 0.1c } + vmargin { 0.4vo } + @Fmta { @Col @CC @Char A ! @Col @Code { "@Char" A } ! @Col ! + @Col @CC @Char B ! @Col @Code { "@Char" B } ! @Col ! + @Col @CC @Char C ! @Col @Code { "@Char" C } ! @Col ! + @Col @CC @Char D ! @Col @Code { "@Char" D } } + @Fmtb { @Col @CC @Char A ! @Col @Code { "@Char" A } ! @Col ! + @Col ! @Col ! @Col ! @Col ! @Col ! @Col ! @Col ! @Col } +{ +@Rowa A { quotesinglbase } B { quotedblbase } C { ellipsis } D { OE } +@Rowa A { oe } B { quotedblleft } C { quotedblright } D { fi } +@Rowa A { fl } B { endash } C { emdash } D { bullet } +@Rowa A { dagger } B { daggerdbl } C { florin } D { fraction } +} +Most of these characters are also in the list of `characters important +enough to deserve their own symbols' given above. +@End @Section diff --git a/doc/user/bas_conv b/doc/user/bas_conv new file mode 100644 index 0000000..cd971b0 --- /dev/null +++ b/doc/user/bas_conv @@ -0,0 +1,75 @@ +@Section + @Title { Alternative conventions for white space } + @Tag { white } +@Begin +@PP +As Section {@NumberOf spaces} explains, when two objects are separated +by one or more white space characters (spaces, tabs, and newlines), this +same amount of white space will separate the two objects in the output. +@PP +Two other conventions for interpreting these white spaces have been +used in other document formatting systems. Roughly, they are: +@ID @Tab + @Fmta { @Col A ! @Col B } +{ +@Rowa + A { troff } + B { Like Lout, except that at every point where a sentence ends at +the end of an input line, add one extra space in the output. } +@Rowa + A { @TeX } + B { Replace all sequences of two or more white spaces by one. Then, +at every point where a sentence ends, whether or not it is at the end +of a line, add one extra space in the output. } +} +Lout offers these two alternative conventions by means of the +initialspace. @Index { @Code "@InitialSpace" option } +@Code "@InitialSpace" option. This is similar to the +@Code "@InitialFont" option described at the end of Section +{@NumberOf fonts}, in that you can set it at the beginning of your +document, like this: +@ID @Code { +"@SysInclude { doc }" +"@Document" +" @InitialSpace { lout }" +"//" +"@Text @Begin" +"..." +"@End @Text" +} +or you can set it in the setup file. The above example shows the +default value, {@Code lout}, which produces Lout's usual spacing; +lout.space @Index { @Code lout spacing } +troff.space @Index { @Code troff spacing } +tex.space @Index { @Code tex (@LaTeX) spacing } +the alternative values are @Code "troff" and {@Code "tex"}. +@PP +How to tell whether a sentence has ended is a vexed question. For +the @Code "troff" method, Lout looks for a word at the end of a line +ending in one of `.', `:', `?', or `!' optionally followed by either +a right quote character or a right parenthesis. Actually, this depends +on the current language (Section {@NumberOf languages}); the rule just +given is for English, and other languages may differ. +@PP +The @Code "tex" rule for where a sentence ends is slightly more +complicated. Lout looks for a word, not necessarily at the end +of an input line, which ends as described for @Code "troff" but +in addition has a lower-case letter preceding that. +@PP +In all cases you must use a paragraph symbol, such as @Code "@PP" or +{@Code "@LP"}, to separate your paragraphs. The common convention of +other systems, that a blank line marks a paragraph, is never true of Lout. +@PP +Whatever rule is adopted, there are occasional exceptions where you +will have to indicate explicitly whether you want an ordinary space +or a between-sentences space. For this there are two symbols, +@Code "~" (ordinary space) and {@Code "~~"} (between-sentences +space). For example, +@ID @Code "Dr.~Kingston" +will produce an ordinary space between the two words, even with +@Code "tex" which would otherwise consider that spot to be the end +of a sentence. Spaces adjacent to these two symbols have no effect on +the result. Please note however that @Code "~" produces an +unbreakable space (that is, one that will never be replaced by the end of +a line) in contrast to just leaving a space, which is breakable. +@End @Section diff --git a/doc/user/bas_date b/doc/user/bas_date new file mode 100644 index 0000000..16ee433 --- /dev/null +++ b/doc/user/bas_date @@ -0,0 +1,84 @@ +@Section + @Title { The current date and time } + @Tag { date } +@Begin +@PP +The @Code "@Date" and @Code "@Time" symbols produce the current date +date. @Index @Code "@Date" +time. @Index @Code "@Time" +and time: +@ID @Code "It is now @Time on @Date." +produces something like +@ID { It is now @Time on @Date. } +The result depends on the current language. +@PP +Both symbols have a @Code "@Format" option that changes the format of +the result: +@ID @Code "@Date @Format { @DayNum\"/\"@MonthNum\"/\"@ShortYear }" +The result is the @Code "@Format" option with the symbols replaced by +the appropriate values: +@ID { @Date @Format { @DayNum"/"@MonthNum"/"@ShortYear } } +The @Code "/" characters have been enclosed in double quotes for the +usual reason (Section {@NumberOf characters}). +@PP +Here is the full list of symbols that you can use within both +@Code "@Format" options: +@ID @OneRow @Tab + @Fmta { @Col @Code A ! @Col B } + vmargin { 0.5vx } +{ +@Rowa + A { "@Year" } + B { The year, e.g. @Code "1994" } +@Rowa + A { "@ShortYear" } + B { The last two digits of the year, e.g. @Code "94" } +@Rowa + A { "@Month" } + B { The month, e.g. @Code "December" } +@Rowa + A { "@ShortMonth" } + B { The month abbreviated, e.g. @Code "Dec" } +@Rowa + A { "@MonthNum" } + B { The number of the month, between @Code "1" and @Code "12" } +@Rowa + A { "@Day" } + B { The day of the week, e.g. @Code "Saturday" } +@Rowa + A { "@ShortDay" } + B { The day abbreviated, e.g. @Code "Sat" } +@Rowa + A { "@DayNum" } + B { The day of the month, between @Code "1" and @Code "31" } +@Rowa + A { "@MeriDiem" } + B { @Code "a.m." or @Code "p.m." } +@Rowa + A { "@ShortMeriDiem" } + B { @Code "am" or @Code "pm" } +@Rowa + A { "@Hour" } + B { The hour, between @Code "00" and @Code "23" } +@Rowa + A { "@ShortHour" } + B { The hour, between @Code "0" and @Code "23" } +@Rowa + A { "@TwelveHour" } + B { The hour, between @Code "1" and @Code "12" } +@Rowa + A { "@Minute" } + B { The minute, between @Code "00" and @Code "59" } +@Rowa + A { "@Second" } + B { The second, almost always between @Code "00" and @Code "59" } +} +The default format for @Code "@Date" in English is +@ID @Code "@Date @Format { @DayNum @Month, @Year }" +and the default format for @Code "@Time" in English is +@ID @Code "@Time @Format { @TwelveHour.@Minute @MeriDiem }" +Both default formats depend on the current language, and +so do {@Code "@Month"}, {@Code "@ShortMonth"}, +{@Code "@Day"}, and {@Code "@ShortDay"},{@Code "@MeriDiem" } +and {@Code "@ShortMeriDiem" }. +@End @Section diff --git a/doc/user/bas_drop b/doc/user/bas_drop new file mode 100644 index 0000000..0978123 --- /dev/null +++ b/doc/user/bas_drop @@ -0,0 +1,44 @@ +@Section + @Title { Drop capitals } + @Tag { dropcaps } +@Begin +@PP +There are two symbols for producing drop capitals, {@Code "@DropCapTwo"} +drop.cap.two.sym @Index @Code "@DropCapTwo" +drop.cap.three.sym @Index @Code "@DropCapThree" +and {@Code "@DropCapThree"}. Place the capital to be dropped just +before the symbol, and the rest of the paragraph after it: +@ID @OneRow @Code { +"I @DropCapTwo {" +"t is a truth universally acknowledged, that a single man" +"in possession of a good fortune, must be in want of a wife." +"}" +} +produces the object +@ID 3i @Wide { +I @DropCapTwo { +t is a truth universally acknowledged, that a single man +in possession of a good fortune, must be in want of a wife. +} +} +@Code "@DropCapThree" is the same except that the capital is larger +and spreads over three lines. +@PP +Because Lout occasionally gets the height of the enlarged capital +slightly wrong, there is a @Code "height" option which allows you +to change the height if you need to: +@ID @OneRow @Code { +"H @DropCapTwo height { 1.5v }" +"{" +" ..." +"}" +} +This shows the default value for the height of the capital in +{@Code "@DropCapTwo"}: 1.5 times the current inter-line +spacing. The default height in @Code "@DropCapThree" is {@Code "2.5v"}. +@PP +These symbols produce an object which may appear anywhere in the +usual way. A paragraph symbol will be needed after the paragraph. The +paragraph breaking style of the body of the paragraph will be +{@Code "adjust nohyphen"}; this cannot be changed at present. +@End @Section diff --git a/doc/user/bas_empt b/doc/user/bas_empt new file mode 100644 index 0000000..c9f615d --- /dev/null +++ b/doc/user/bas_empt @@ -0,0 +1,26 @@ +@Section + @Title { The empty object } + @Tag { empty } +@Begin +@PP +It is possible to produce examples in which an object is clearly +empty. @Index { empty object } +missing: +@ID @Code "{ @I }" +The @Code "@I" symbol is supposed to italicize the following object, +but in this example there isn't one. A more plausible example is +@ID @OneRow @Code { +"@PP" +"@PP" +} +There are supposed to be paragraph objects between paragraph symbols, +but here there aren't. +@PP +Wherever an object is clearly missing, Lout inserts an @I { empty object }, +which is a rectangle of size zero by zero that prints as nothing. Here +are two other ways to get an empty object: +@ID @Code "{} \"\"" +Braces always enclose an object, so Lout is obliged to insert an empty +object between them; the two double quotes make a word with no characters +in it, which is taken to be an empty object. +@End @Section diff --git a/doc/user/bas_font b/doc/user/bas_font new file mode 100644 index 0000000..65d711e --- /dev/null +++ b/doc/user/bas_font @@ -0,0 +1,629 @@ +@Section + @Title { Fonts and font sizes } + @Tag { fonts } +@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 } +{ @Char exclam } +{ @Char quotedbl } +{ @Char numbersign } +{ @Char dollar } +{ @Char percent } +{ @Char ampersand } +{ @Char quoteright } +{ @Char parenleft } +{ @Char parenright } +{ @Char asterisk } +{ @Char plus } +{ @Char comma } +{ @Char hyphen } +{ @Char period } +{ @Char slash } +{ @Char zero } +{ @Char one } +{ @Char two } +{ @Char three } +{ @Char four } +{ @Char five } +{ @Char six } +{ @Char seven } +{ @Char eight } +{ @Char nine } +{ @Char colon } +{ @Char semicolon } +{ @Char less } +{ @Char equal } +{ @Char greater } +{ @Char question } +{ @Char at } +{ @Char bracketleft } +{ @Char backslash } +{ @Char bracketright } +{ @Char asciicircum } +{ @Char underscore } +{ @Char quoteleft } +//1vx +{ @Char A } +{ @Char B } +{ @Char C } +{ @Char D } +{ @Char E } +{ @Char F } +{ @Char G } +{ @Char H } +{ @Char I } +{ @Char J } +{ @Char K } +{ @Char L } +{ @Char M } +{ @Char N } +{ @Char O } +{ @Char P } +{ @Char Q } +{ @Char R } +{ @Char S } +{ @Char T } +{ @Char U } +{ @Char V } +{ @Char W } +{ @Char X } +{ @Char Y } +{ @Char Z } +//1vx +{ @Char a } +{ @Char b } +{ @Char c } +{ @Char d } +{ @Char e } +{ @Char f } +{ @Char g } +{ @Char h } +{ @Char i } +{ @Char j } +{ @Char k } +{ @Char l } +{ @Char m } +{ @Char n } +{ @Char o } +{ @Char p } +{ @Char q } +{ @Char r } +{ @Char s } +{ @Char t } +{ @Char u } +{ @Char v } +{ @Char w } +{ @Char x } +{ @Char y } +{ @Char z } +//1vx +{ @Char braceleft } +{ @Char bar } +{ @Char braceright } +{ @Char asciitilde } +{ @Char dotlessi } +{ @Char grave } +{ @Char acute } +{ @Char circumflex } +{ @Char tilde } +{ @Char macron } +{ @Char breve } +{ @Char dotaccent } +{ @Char dieresis } +{ @Char ring } +{ @Char cedilla } +{ @Char hungarumlaut } +{ @Char ogonek } +{ @Char caron } +{ @Char space } +{ @Char exclamdown } +{ @Char cent } +{ @Char sterling } +{ @Char currency } +{ @Char yen } +{ @Char brokenbar } +{ @Char section } +{ @Char dieresis } +{ @Char copyright } +{ @Char ordfeminine } +{ @Char guillemotleft } +{ @Char logicalnot } +{ @Char hyphen } +{ @Char registered } +{ @Char macron } +{ @Char degree } +{ @Char plusminus } +{ @Char twosuperior } +{ @Char threesuperior } +{ @Char acute } +{ @Char mu } +{ @Char paragraph } +{ @Char periodcentered } +{ @Char cedilla } +{ @Char onesuperior } +{ @Char ordmasculine } +{ @Char guillemotright } +{ @Char onequarter } +{ @Char onehalf } +{ @Char threequarters } +{ @Char questiondown } +//1vx +{ @Char Agrave } +{ @Char Aacute } +{ @Char Acircumflex } +{ @Char Atilde } +{ @Char Adieresis } +{ @Char Aring } +{ @Char AE } +{ @Char Ccedilla } +{ @Char Egrave } +{ @Char Eacute } +{ @Char Ecircumflex } +{ @Char Edieresis } +{ @Char Igrave } +{ @Char Iacute } +{ @Char Icircumflex } +{ @Char Idieresis } +{ @Char Eth } +{ @Char Ntilde } +{ @Char Ograve } +{ @Char Oacute } +{ @Char Ocircumflex } +{ @Char Otilde } +{ @Char Odieresis } +{ @Char multiply } +{ @Char Oslash } +{ @Char Ugrave } +{ @Char Uacute } +{ @Char Ucircumflex } +{ @Char Udieresis } +{ @Char Yacute } +{ @Char Thorn } +//1vx +{ @Char germandbls } +{ @Char agrave } +{ @Char aacute } +{ @Char acircumflex } +{ @Char atilde } +{ @Char adieresis } +{ @Char aring } +{ @Char ae } +{ @Char ccedilla } +{ @Char egrave } +{ @Char eacute } +{ @Char ecircumflex } +{ @Char edieresis } +{ @Char igrave } +{ @Char iacute } +{ @Char icircumflex } +{ @Char idieresis } +{ @Char eth } +{ @Char ntilde } +{ @Char ograve } +{ @Char oacute } +{ @Char ocircumflex } +{ @Char otilde } +{ @Char odieresis } +{ @Char divide } +{ @Char oslash } +{ @Char ugrave } +{ @Char uacute } +{ @Char ucircumflex } +{ @Char udieresis } +{ @Char yacute } +{ @Char thorn } +{ @Char ydieresis } +} +and here is the Times Italic font: +@ID @OneRow { Times Slope } @Font 0.05c @Space { +{ @Char space } +{ @Char exclam } +{ @Char quotedbl } +{ @Char numbersign } +{ @Char dollar } +{ @Char percent } +{ @Char ampersand } +{ @Char quoteright } +{ @Char parenleft } +{ @Char parenright } +{ @Char asterisk } +{ @Char plus } +{ @Char comma } +{ @Char hyphen } +{ @Char period } +{ @Char slash } +{ @Char zero } +{ @Char one } +{ @Char two } +{ @Char three } +{ @Char four } +{ @Char five } +{ @Char six } +{ @Char seven } +{ @Char eight } +{ @Char nine } +{ @Char colon } +{ @Char semicolon } +{ @Char less } +{ @Char equal } +{ @Char greater } +{ @Char question } +{ @Char at } +{ @Char bracketleft } +{ @Char backslash } +{ @Char bracketright } +{ @Char asciicircum } +{ @Char underscore } +{ @Char quoteleft } +//1vx +{ @Char A } +{ @Char B } +{ @Char C } +{ @Char D } +{ @Char E } +{ @Char F } +{ @Char G } +{ @Char H } +{ @Char I } +{ @Char J } +{ @Char K } +{ @Char L } +{ @Char M } +{ @Char N } +{ @Char O } +{ @Char P } +{ @Char Q } +{ @Char R } +{ @Char S } +{ @Char T } +{ @Char U } +{ @Char V } +{ @Char W } +{ @Char X } +{ @Char Y } +{ @Char Z } +//1vx +{ @Char a } +{ @Char b } +{ @Char c } +{ @Char d } +{ @Char e } +{ @Char f } +{ @Char g } +{ @Char h } +{ @Char i } +{ @Char j } +{ @Char k } +{ @Char l } +{ @Char m } +{ @Char n } +{ @Char o } +{ @Char p } +{ @Char q } +{ @Char r } +{ @Char s } +{ @Char t } +{ @Char u } +{ @Char v } +{ @Char w } +{ @Char x } +{ @Char y } +{ @Char z } +//1vx +{ @Char braceleft } +{ @Char bar } +{ @Char braceright } +{ @Char asciitilde } +{ @Char dotlessi } +{ @Char grave } +{ @Char acute } +{ @Char circumflex } +{ @Char tilde } +{ @Char macron } +{ @Char breve } +{ @Char dotaccent } +{ @Char dieresis } +{ @Char ring } +{ @Char cedilla } +{ @Char hungarumlaut } +{ @Char ogonek } +{ @Char caron } +{ @Char space } +{ @Char exclamdown } +{ @Char cent } +{ @Char sterling } +{ @Char currency } +{ @Char yen } +{ @Char brokenbar } +{ @Char section } +{ @Char dieresis } +{ @Char copyright } +{ @Char ordfeminine } +{ @Char guillemotleft } +{ @Char logicalnot } +{ @Char hyphen } +{ @Char registered } +{ @Char macron } +{ @Char degree } +{ @Char plusminus } +{ @Char twosuperior } +{ @Char threesuperior } +{ @Char acute } +{ @Char mu } +{ @Char paragraph } +{ @Char periodcentered } +{ @Char cedilla } +{ @Char onesuperior } +{ @Char ordmasculine } +{ @Char guillemotright } +{ @Char onequarter } +{ @Char onehalf } +{ @Char threequarters } +{ @Char questiondown } +//1vx +{ @Char Agrave } +{ @Char Aacute } +{ @Char Acircumflex } +{ @Char Atilde } +{ @Char Adieresis } +{ @Char Aring } +{ @Char AE } +{ @Char Ccedilla } +{ @Char Egrave } +{ @Char Eacute } +{ @Char Ecircumflex } +{ @Char Edieresis } +{ @Char Igrave } +{ @Char Iacute } +{ @Char Icircumflex } +{ @Char Idieresis } +{ @Char Eth } +{ @Char Ntilde } +{ @Char Ograve } +{ @Char Oacute } +{ @Char Ocircumflex } +{ @Char Otilde } +{ @Char Odieresis } +{ @Char multiply } +{ @Char Oslash } +{ @Char Ugrave } +{ @Char Uacute } +{ @Char Ucircumflex } +{ @Char Udieresis } +{ @Char Yacute } +{ @Char Thorn } +//1vx +{ @Char germandbls } +{ @Char agrave } +{ @Char aacute } +{ @Char acircumflex } +{ @Char atilde } +{ @Char adieresis } +{ @Char aring } +{ @Char ae } +{ @Char ccedilla } +{ @Char egrave } +{ @Char eacute } +{ @Char ecircumflex } +{ @Char edieresis } +{ @Char igrave } +{ @Char iacute } +{ @Char icircumflex } +{ @Char idieresis } +{ @Char eth } +{ @Char ntilde } +{ @Char ograve } +{ @Char oacute } +{ @Char ocircumflex } +{ @Char otilde } +{ @Char odieresis } +{ @Char divide } +{ @Char oslash } +{ @Char ugrave } +{ @Char uacute } +{ @Char ucircumflex } +{ @Char udieresis } +{ @Char yacute } +{ @Char thorn } +{ @Char ydieresis } +} +As their names imply, these two fonts belong to the @I { Times family }, +a collection of fonts designed to go well together. Every font has a +@I { family name }, such as Times, Helvetica, or Courier, and a +family.name @Index { family name of font } +face.name @Index { face name of font } +@I { face name }, such as Roman or Italic. To find out how to +get the unusual characters, see Section {@NumberOf characters}. +@PP +Documents look best when they use just one font family, so the most +common need is to change to a different face within the current +family. We have already seen {@Code "@I"}, which changes to the Italic +face of the current family; there are six such symbols: +b. @Index @Code "@B" +i. @Index @Code "@I" +bi. @Index @Code "@BI" +ii. @Index @Code "@II" +s. @Index @Code "@S" +r. @Index @Code "@R" +@ID @OneRow @Tab + @Fmta { @Col @Code A ! @Col B } +{ +@Rowa + A { "@B { Hello World }" } + B { @B { Hello World } } +@Rowa + A { "@I { Hello World }" } + B { @I { Hello World } } +@Rowa + A { "@BI { Hello World }" } + B { @BI { Hello World } } +@Rowa + A { "@II { Hello World }" } + B { @II { Hello World } } +@Rowa + A { "@S { Hello World }" } + B { @S { Hello World } } +@Rowa + A { "@R { Hello World }" } + B { @R { Hello World } } +} +The symbols' names stand for Bold, Italic, Bold-Italic, Italic-Italic +(see below), Small capitals, and Roman. It is conventional to use Bold +for headings; Italic for emphasis, terms being defined, and subsidiary +headings; and Roman for the rest. Small capitals are not really a +different font; they are +small.caps @Index { small capitals } +made on demand from the current font. So you can write, for example, +@ID @Code "@I @S { Hello World }" +and get @I @S { Hello World }. +@PP +The @Code "@R" symbol is almost unnecessary, since the document as a +whole is set in a Roman face; but it is occasionally useful: +@ID @Code "@I { An Italic sentence with one @R Roman word }" +produces +@ID @I { An Italic sentence with one @R Roman word } +This illustrates the general principle that the effect of a font symbol +on the following object is subject to font symbols within that object. +@PP +When part of a title is to be set in italic font, neither @Code "@I" +nor @Code "@BI" is suitable because the part should appear in bold +italics in the title itself, but in ordinary italics in running headers +and the table of contents. The @Code "@II" symbol is the one for this +situation: it produces bold italics when the current font is bold, +and ordinary italics otherwise. +@PP +Changing families is a little more complicated. Here is the complete +list of font families and their faces available with Basser Lout Version 3: +@ID @OneRow @Tab + @Fmta { @Col @Code A ! @Col { ragged nohyphen } @Break @Code B } +{ +@Rowa + A { AvantGarde } + B { Base Slope Bold BoldSlope BoldObl Book BookOblique +CondBold CondBook CondDemi CondMedium Demi DemiOblique +ExtraLight ExtraLightObl Medium MediumObl } +@Rowa + A { Bookman } + B { Base Slope Bold BoldSlope BoldItalic Demi DemiItalic +Light LightItalic Medium MediumItalic } +@Rowa + A { Chancery } + B { Base Slope Bold BoldSlope +Roman Bold Italic Light Demi LightItalic MediumItalic +} +@Rowa + A { Courier } + B { Base Slope Bold BoldSlope BoldOblique Oblique } +@Rowa + A { Helvetica } + B { Base Slope Bold BoldSlope Black BlackOblique +BoldOblique Compressed Cond CondBlack CondBlackObl +CondBold CondBoldObl CondLight CondLightObl +CondOblique ExtraCompressed +Light LightOblique Narrow NarrowBold NarrowBoldObl +NarrowObl Oblique UltraCompressed } +@Rowa + A { Schoolbook } + B { Base Slope Bold BoldSlope BoldItalic Italic Roman } +@Rowa + A { Palatino } + B { Base Slope Bold BoldSlope BoldItalic +BoldItalicOsF BoldOsF Italic ItalicOsF Roman SC } +@Rowa + A { Symbol } + B { Base Slope Bold BoldSlope } +@Rowa + A { Times } + B { Base Slope Bold BoldSlope BoldItalic +BoldItalicOsF BoldSC ExtraBold Italic ItalicOsF +Roman RomanSC Semibold SemiboldItalic } +@Rowa + A { Dingbats } + B { Base Slope Bold BoldSlope } +} +Lout understands all these fonts, but your printing device may not. Times, +Helvetica, Courier, and Symbol at least seem to be ubiquitous, although +not in every face. These fonts work only with languages that use the +Latin1 character set; consult Section {@NumberOf languages} for more +information about this. It is not difficult for a Lout expert to extend this +list @Cite { $kingston1995lout.expert }. +@PP +It is a convention in Lout that every font family should at least +base. @Index { @Code Base font } +slope. @Index { @Code Slope font } +bold. @Index { @Code Bold font } +boldslope. @Index { @Code BoldSlope font } +contain faces called @Code { Base }, @Code { Slope }, @Code { Bold }, +and @Code { BoldSlope }, and these faces are what the @Code { "@R" }, +@Code { "@I" }, @Code { "@B" }, and @Code { "@BI" } symbols give you. But +this convention is something of a fiction for two reasons. First, +some font families don't have faces that could reasonably be described as +bold or whatever. In particular, the @Code Symbol family contains just +one face, and all four conventional face names produce that face. Second, +the four conventional face names are not names that typographers actually +use, @Code { Bold } excepted. @Code { Slope } produces an italic face +in some families and an oblique one in others. As the table shows, the +true names are available if you want to use them, but it is very convenient +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" +example, +@ID @Code "{ Helvetica Slope } @Font { Hello World }" +produces +@ID { Helvetica Slope } @Font { Hello World } +When changing to a different family, a face name must follow the family +name; but when changing face within a family, just the face name is +sufficient. +@PP +To make the characters larger or smaller, you need to change the +font.size @Index { font size } +@I { font size }, which can also be done with the @Code "@Font" +symbol. Font sizes are traditionally measured in {@I points}: there +are 72 points to one inch, and the most common font sizes are 12 point +and 10 point. However, as Section {@NumberOf objects} explains in +detail, any length including fractional lengths is acceptable: +@ID @Code "24p @Font { Hello World }" +changes to 24 point size, producing +@ID 24p @Font { Hello World } +It is also possible to specify a font size relative to the current +size: @Code "+2p" means two points larger, @Code "-2p" means two +points smaller, and @Code "1.5f" means 1.5 times the current font +size. +@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: +@ID @Code "@F { Hello world }" +produces +@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 +large appearance of the Courier font. +@PP +The document as a whole will be set in @Code { Times Base 12p }. To +change this you need to change the @Code "@InitialFont" option, for +initialfont. @Index @Code "@InitialFont" +example to +@ID @Code "@InitialFont { Helvetica Base 10p }" +to get Helvetica 10 point. You must give all three parts in +{@Code "@InitialFont"}: family, face, size. If you are using your own +setup file, as explained in Section {@NumberOf setup}, you can find the +@Code "@InitialFont" option there. If not, you can set it at the +beginning of your document as explained in Section {@NumberOf ordinary}. +@PP +There are two features that make fonts look better on the +page. @I Ligatures are pairs of letters run together; the most +ligatures. @Index { ligatures } +common ligatures are `fi' and `fl.' @I Kerning is moving adjacent +kerning. @Index { kerning } +letters closer together, for example in `VA.' Lout considers +ligatures and kerning to be integral parts of each font; you can prevent +them from happening only by enclosing one of the letters in a +@Code "@OneCol" symbol, as in {@Code "@OneCol { V }A" }. +@End @Section diff --git a/doc/user/bas_head b/doc/user/bas_head new file mode 100644 index 0000000..4410c08 --- /dev/null +++ b/doc/user/bas_head @@ -0,0 +1,32 @@ +@Section + @Title { Headings } + @Tag { headings } +@Begin +@PP +The @Code "@Heading" symbol makes the following object into a +heading. @Index @Code "@Heading" +heading. Actually, all it does is change the font, so if you want a +centred heading you have to display it as well: +@ID @OneRow @Code { +"@Display @Heading { A Centred Heading }" +"Following text" +} +If you want a left-justified heading, use @Code "@LeftDisplay" instead +of @Code {"@Display"}. Alternatively, you can use no display symbol at +all, but then you will need paragraph symbols before and after: +@ID @OneRow @Code { +"@DP" +"@Heading { A Left-Justified Heading }" +"@PP" +"Following text" +} +The font used is @Code Bold in the current family, although you can +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. +@End @Section diff --git a/doc/user/bas_hyph b/doc/user/bas_hyph new file mode 100644 index 0000000..6997f41 --- /dev/null +++ b/doc/user/bas_hyph @@ -0,0 +1,37 @@ +@Section + @Title { Hyphenation } + @Tag { hyph } +@Begin +@PP +The @Code "@Break" symbol also controls hyphenation: @Code "hyphen" +hyphenation. @Index hyphenation +@Code "@Break" turns it on, @Code "nohyphen" @Code "@Break" turns it +off. For example, ragged breaking is often done without hyphenation: +@ID @OneRow @Code { +"@IndentedDisplay { ragged nohyphen } @Break {" +"This little paragraph will appear with" +"ragged ends to its lines." +"}" +} +Lout's method of choosing hyphenation points is copied from the @TeX +tex.hyph @SubIndex { hyphenation } +system, except that Lout will never place a hyphen within a sequence +of characters that form a ligature (fl and +ligatures.hyph @SubIndex { and hyphenation } +fi are the most common ligatures). +@PP +Hyphenation usually works well by itself; you should never need to +interfere with its ideas of what to do. However, if you do want +to tell Lout where you think a hyphen could be inserted, you can +use the @Code "&-" symbol: +@IndentedDisplay @Code { +"after&-math" +} +If @Code "&-" occurs directly after a hyphen character, hyphenation +will be permitted but no extra hyphen will be inserted. To prevent +hyphenation of a word, enclose the word in a @Code "@OneCol" symbol. +@PP +To turn hyphenation off throughout the document, you need to set the +@Code "@InitialBreak" option to {@Code "nohyphen"}, as described at the +end of Section {@NumberOf linespace}. +@End @Section diff --git a/doc/user/bas_lang b/doc/user/bas_lang new file mode 100644 index 0000000..3b32a94 --- /dev/null +++ b/doc/user/bas_lang @@ -0,0 +1,85 @@ +@Section + @Title { Languages other than English } + @Tag { languages } +@Begin +@PP +When part of a document is written in a language other than English, +languages. @Index { languages other than English } +Lout should be informed of this using the @Code "@Language" symbol: +language. @Index @Code "@Language" +@ID @OneRow @Code { +"... the garter, he said: French @Language { `Honi soit qui mal y" +"pense' }, and this saying ..." +} +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 { +Czech Cesky Cestina +Danish Dansk +Dutch Nederlands +English +EnglishUK +Finnish Suomi +French Francais Fran{@Char ccedilla}ais +German Deutsch +Hungarian Magyar +Italian Italiano +Norwegian Norsk +Polish Polski +Russian +Slovenian Slovenia Slovenija +Spanish Espa{@Char ntilde}ol +Swedish Svenska +} +As shown, most languages have alternative 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. Hungarian does not yet allow +hyphenation. +@PP +If your entire document is in a language other than English, you need +to change the @Code "@InitialLanguage" option: +initiallanguage. @Index @Code "@InitialLanguage" +@ID @Code "@InitialLanguage { Deutsch }" +If you are using your own setup file (Section {@NumberOf setup}), you +can change it there. If not, you can change it at the start of your +document, as explained in Section {@NumberOf ordinary}. +@PP +Czech, Polish, and Slovenian use the ISO-LATIN-2 character set, and +users of these languages have to place +@ID @Code "@SysInclude { latin2 }" +at the very start of their documents in order to get access to the +ISO-LATIN-2 versions of the fonts. These have family names such as +TimesCE, CourierCE, HelveticaCE, and so on, to distinguish them +from the same fonts encoded in ISO-LATIN-1. The face names are +unchanged. Consult file @Code "latin2.fd" in the standard include +directory for a complete list of these fonts. +@PP +Russian uses Cyrillic characters. In principle, users of Russian +have to place +@ID @Code "@SysInclude { russian }" +at the very start of their documents in order to get access to +Cyrillic fonts. However no such fonts are distributed +with the current version of Lout, so this line does nothing at +present. Other left-to-right languages are easily added, so +consult the author if your language is not listed. +@End @Section diff --git a/doc/user/bas_line b/doc/user/bas_line new file mode 100644 index 0000000..3210cdc --- /dev/null +++ b/doc/user/bas_line @@ -0,0 +1,43 @@ +@Section + @Title { Line spacing } + @Tag { linespace } +@Begin +@PP +The @Code "@Break" symbol also controls the amount of space placed +line.spacing @Index { line spacing } +between the lines of paragraphs. This distance is best given using the +@Code "v" unit of measurement: @Code "1v" is the current line +separation (see Section {@NumberOf objects} for a description of +lengths in general). For example, +@ID @Code "2vx @Break ..." +produces double spacing in the paragraphs of the following object, and +double.spacing @Index { double spacing } +@ID @Code "0.9vx @Break ..." +produces cramped spacing, which can be useful in large tables that don't +quite fit on one page. The @Code "x" following the @Code "v" is required, +but its meaning is beyond our scope @Cite { $kingston1995lout.expert }. +@PP +To set the entire document in a different line spacing from the +initialbreak @Index @Code "@InitialBreak" +default, you need to change the @Code "@InitialBreak" option. If you +are using your own setup file (Section {@NumberOf setup}), +change it there. If not, you can change it at the beginning of your +document, as described in Section {@NumberOf ordinary}. +@PP +The default value of the @Code "@InitialBreak" option produces the +@Code "adjust" paragraph breaking style with a line spacing of 1.20 +times the current (that is, the initial) font size, and hyphenation +on: +@ID @Code "@InitialBreak { adjust 1.20fx hyphen }" +To get double spacing, change it to +@ID @Code "@InitialBreak { adjust 2.40fx hyphen }" +To get ragged paragraphs with hyphenation off, change it to +@ID @Code "@InitialBreak { ragged 1.20fx nohyphen }" +and so on. It is a good idea to define the initial line spacing using +the @Code "f" unit, since then if you change the initial font size the +line spacing will change with it. However, any length (Section +{@NumberOf objects}) with an @Code "x" appended will do: @Code "14px" +for 14 point, @Code "0.5cx" for 0.5 centimetres, etc. Don't use the +@Code "v" unit though, because it refers to some @I previous line +spacing, whereas here we are defining the line spacing for the first time. +@End @Section diff --git a/doc/user/bas_objs b/doc/user/bas_objs new file mode 100644 index 0000000..f6a2f78 --- /dev/null +++ b/doc/user/bas_objs @@ -0,0 +1,141 @@ +@Section + @Title { Objects, symbols, options, and lengths } + @Tag { objects } +@Begin +@PP +Lout is not concerned with the exact shapes of individual characters, +only with the rectangular areas they occupy: +@ID { +@Box margin { 0c } B & +@Box margin { 0c } i & +@Box margin { 0c } o & +@Box margin { 0c } l & +@Box margin { 0c } o & +@Box margin { 0c } g & +@Box margin { 0c } y +} +When letters join together into a word, the result is a larger rectangle +enclosing them all: +@ID @Box margin { 0c } Biology +When words join into lines we get even larger rectangles: +@ID @Box margin { 0c } { Biology is the study of living things. } +and so on up through paragraphs and columns to the largest rectangles, +which are pages. We call any such rectangle, whether made up of one +character, one word, one line, one paragraph, one page, or anything +object. @Index { object } +else, an @I { object }. +@PP +We also often say, for example, `the object +{@Code "@I { Hello world }"},' referring to a piece of Lout's input as +an object. This makes sense because we are anticipating the result +produced, in this case the object @I { Hello world }. It's true that if +a line break happens to fall between @I Hello and @I { world }, the +result of @Code "@I { Hello world }" is not a single rectangle. We +answer this by thinking of objects as existing before paragraph breaking +rearranges them. +@PP +Not everything is an object, however. @Code "@I" alone is not an object, +merely a symbol with the potential of producing an object when given an +object to work on. To understand this, ask yourself what rectangle +@Code "@I" alone could possibly represent: there is no such rectangle. +@PP +It helps to imagine the assembly of objects taking place before your +eyes. Look at @Code Hello and imagine the objects H, e, l, l, o being +assembled into the larger object Hello; look at @Code "Hello world" +and imagine Hello and world being assembled into Hello world. When +looking at +@ID @Code "@I { Hello world }" +you need to imagine the @Code "@I" symbol consuming the following object, +Hello world, and replacing it with the object @I { Hello world }. Here +is another example: +@ID @Code "@CurveBox { Hello world }" +The @Code "@CurveBox" symbol (Section {@NumberOf boxes}) consumes +Hello world and replaces it with the object +@ID @CurveBox { Hello world } +This brings us to a basic principle of Lout: @I { Where you can put +one object, you can put any object }. A few examples will show the +vast range of possibilities opened up by this: +@ID @Code "@CurveBox { @I Hello world }" +produces +@ID @CurveBox { @I Hello world } +It doesn't bother @Code "@CurveBox" if one of the words inside +it is in italics. Next: +@ID @Code "@I @CurveBox { Hello world }" +produces +@ID @I @CurveBox { Hello world } +The object following @Code "@I" cannot be just @Code {"@CurveBox"}, +since that is not an object by itself (it needs to be applied to some +object first). So the object following @Code "@I" is +@Code {"@CurveBox { Hello world }"}, and it is this that is consumed by +@Code "@I" and modified. The @Code "@I" symbol is happy to hunt +through the object looking for words to italicize. We could go on +indefinitely in this way, producing +@ID @CurveBox { @CurveBox Hello @CurveBox world } +for example by {@Code "@CurveBox { @CurveBox Hello @CurveBox world }"}. +@PP +Symbols like @Code "@CurveBox" often have @I { options }, which are +option. @Index { option } +subsidiary symbols that modify the result. For example, @Code "@CurveBox" +has @Code "margin" and @Code "paint" options: +@ID @OneRow @Code { +"@CurveBox" +" margin { 0.5c }" +" paint { lightgrey }" +"{ Hello world }" +} +Options come immediately after the main symbol, before any following +object. Each consists of the option name followed by the value we want +the option to have, always enclosed in braces. Setting out options on +separate lines as we have done above makes them easy to see but is not +compulsory (end of line and space are the same to Lout). The result, +naturally enough, is a curved box with a 0.5 centimetre margin around +its contents, painted light grey: +@ID @CurveBox + margin { 0.5c } + paint { lightgrey } +{ Hello world } +Options are optional: if you leave out an option, Lout supplies a +sensible @I default value for it. Options may be given in any +order. They are a very useful way of adding flexibility to symbols +without cluttering things up when they aren't needed. They also help +with learning: you can learn the basic symbol first and worry about +the options later. +@PP +Whenever a length is required, as in the @Code margin option above, it +length. @Index { length } +centimetres. @Index { centimetres } +inches. @Index { inches } +point.unit @Index { point (unit of measurement) } +em.unit @Index { em (unit of measurement) } +f.unit @Index { @Code f unit of measurement } +s.unit @Index { @Code s unit of measurement } +v.unit @Index { @Code v unit of measurement } +units.of @Index { units of measurement } +may be given using any one of the following seven units of measurement: +@ID @OneRow @Tab + @Fmta { @Col @Code A ! @Col B } + vmargin { 0.5vx } +{ +@Rowa A { c } B { Centimetres } +@Rowa A { i } B { Inches ({@Code "1i"} = {@Code "2.54c"}) } +@Rowa A { p } B { Points ({@Code "72p"} = {@Code "1i"}) } +@Rowa A { m } B { Ems ({@Code "12m"} = {@Code "1i"}) } +@Rowa A { f } B { @Code "1f" is the current font size } +@Rowa A { s } B { @Code "1s" is the current width of a space character } +@Rowa A { v } B { @Code "1v" is the current inter-line spacing } +} +The first four all define absolute distances and are strictly +interchangeable. It is traditional to measure font sizes in points; typical +sizes are @Code "12p" and {@Code "10p"}, but fractional sizes are allowed. +@PP +If you use the @Code "f" unit, the length will depend on the current +font size. This can be very useful. For example, the default value of +the @Code "margin" option of @Code "@CurveBox" is @Code "0.3f" (0.3 +times the current font size). If you use a large font, for example in +an overhead transparency, you get a correspondingly large margin without +having to ask for it. +@PP +The @Code "s" and @Code "v" units are less useful. The @Code "v" unit +is used within paragraph symbols (Section {@NumberOf paragraphs}) to +ensure that the space between paragraphs widens with the inter-line spacing. +@End @Section diff --git a/doc/user/bas_par1 b/doc/user/bas_par1 new file mode 100644 index 0000000..de3da37 --- /dev/null +++ b/doc/user/bas_par1 @@ -0,0 +1,105 @@ +@Section + @Title { Starting a new line, paragraph, or page } + @Tag { paragraphs } +@Begin +@PP +The usual way to start a new paragraph is with the @Code "@PP" `plain +pp. @Index @Code "@PP" +paragraphs. @Index { paragraph symbols } +paragraph' symbol. It produces a small vertical space and indents the +first line of the new paragraph. Some document formatting systems +interpret a blank line as a request to start a new paragraph. This is +not the case with Lout: a blank line is two line-endings, equivalent to +two spaces. +@PP +The @Code "@LP" `left paragraph' symbol produces the same +lp. @Index @Code "@LP" +vertical space as {@Code "@PP"}, but omits the indent. The @Code "@LLP" +`left line paragraph' symbol starts a new paragraph using +llp. @Index @Code "@LLP" +the usual inter-line spacing and no indent, or in other words it starts a +new line. If you are using it to create single lines, you need the +@Code "lines" paragraph breaking style instead (Section {@NumberOf paras}). +@PP +The @Code "@DP" `display paragraph' symbol produces a somewhat larger +dp. @Index @Code "@DP" +vertical space, equal to the amount used before and after displays +(Section {@NumberOf displays}), with no indent. To get even larger +vertical spaces, use @Code "@DP" repeatedly. Another symbol, +{@Code "@LOP"}, leaves a paragraph break the size of the gap left +lop. @Index @Code "@LOP" +outside (that is, before and after) lists (Section {@NumberOf lists}). This +is usually equal to {@Code "@DP"}. +@PP +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" +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. +@PP +To make each section begin on a new page you must set the @Code "@SectionGap" +sectiongap. @Index @Code "@SectionGap" +setup file option (Section {@NumberOf largescale}). To make one particular +section start on a new page or column, place @Code "@NP" within the previous +section, at the end. Placing @Code "@NP" between sections will not work. +@PP +Occasionally Lout will start a new page or column directly after a heading, +which looks very poor. The obvious answer is to place an @Code "@NP" +just before the heading, but when the document is later revised and the +heading no longer falls near the page or column ending, this @Code "@NP" +will have to be taken away again. +A better answer is to precede the heading with a @Code "@CNP" `conditional +cnp. @Index @Code "@CNP" +new page' symbol, which checks whether enough space remains in the page or +column for a heading and at least two lines of text. If so, @Code "@CNP" +does nothing; if not, @Code "@CNP" causes a new page or column to be begun, +like {@Code "@NP"}. The recommended arrangement is +@ID @OneRow @Code { +"end of previous part." +"@DP" +"@CNP" +"@Heading { A Heading }" +"@PP" +"First paragraph of next part ..." +} +The @Code "@CNP" symbol should be preceded by either @Code "@DP" or +@Code "@LP", preferably {@Code "@DP"}, and this determines the amount of +space when the @Code "@NP" action does not occur. +@PP +The ultimate answer to the conditional new page problem is to recognise +that the heading is the beginning of a new section of the document, and +to use a large-scale structure symbol like @Code "@Section" (Section +{@NumberOf largescale}). Conditional new page is just one of many +services provided automatically by these symbols. +@PP +Some people do not like to see the first line of a paragraph alone at +the bottom of a page, or the last line of a paragraph alone at the +top (these blemishes are sometimes called widows and orphans). You +can instruct Lout not to allow these; see the next section for details. +@PP +You can modify the effect of the paragraph symbols by changing options +in the setup file. For general information about setup files and their +options, consult Section {@NumberOf setup}; here we just explain how +the relevant options work. The options and their default values are +paragap @Index @Code "@ParaGap" +paraindent @Index @Code "@ParaIndent" +@ID @OneRow @Code { +"@ParaGap { 1.30vx }" +"@ParaIndent { 2.00f }" +"@DisplayGap { 1.00v }" +} +The values are lengths (Section {@NumberOf objects}), except that +for reasons beyond our scope @Code "@ParaGap" must be a length with +an @Code "x" appended, as shown. The @Code "@ParaGap" option determines +how much vertical space will be +inserted by @Code "@PP" and {@Code "@LP"}. The default value, +{@Code "1.30vx"}, is 30% more than the normal inter-line spacing; +to get no extra spacing, change it to {@Code "1.00vx"}. The +@Code "@ParaIndent" option determines the width of the indent produced +by {@Code "@PP"}, and its default value is twice the current font +size. The @Code "@DisplayGap" option determines the amount of vertical +space inserted by {@Code "@DP"}, as well as the vertical space before +and after displays. +@End @Section diff --git a/doc/user/bas_par2 b/doc/user/bas_par2 new file mode 100644 index 0000000..51f674c --- /dev/null +++ b/doc/user/bas_par2 @@ -0,0 +1,261 @@ +@Section + @Title { Paragraph breaking } + @Tag { paras } +@Begin +@PP +@I { Paragraph breaking } is the process of +paragraph.breaking @Index { paragraph breaking } +inserting line breaks into praragraphs 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 +tex.paragraph @SubIndex { paragraph breaking } +system. It offers nine styles of paragraph breaking, +which we will explore with the aid of this example: +@ID @OneRow @Code { +It is a truth universally +acknowledged, that a single man +in possession of a good fortune, +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" +@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. +@PP +The first two of the nine styles perform @I { line adjustment }, which +line.adjustment @Index { line adjustment } +means that they enlarge the spaces between the objects making up each +line so as to fill the lines completely: +@IndentedList +@LI @Tab + @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B } +{ +@Rowa + A { "adjust @Break ..." } + B { adjust @Break { +It is a truth universally +acknowledged, that a single man +in possession of a good fortune, +must be in want of a wife. +}} +} +@LI @Tab + @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B } +{ +@Rowa + A { "outdent @Break ..." } + B { outdent @Break { +It is a truth universally +acknowledged, that a single man +in possession of a good fortune, +must be in want of a wife. +}} +} +@EndList +The @Code adjust style is frequently used, so it has been chosen as the +default style. Outdenting adds a small space at the start of each line +outdent. @Index { outdented paragraphs } +except the first, and is much less common. +@PP +The next four styles do not adjust lines, leaving the paragraph +ragged. @Index { @Code ragged paragraph breaking style } +cragged. @Index { @Code cragged paragraph breaking style } +rragged. @Index { @Code rragged paragraph breaking style } +oragged. @Index { @Code oragged paragraph breaking style } +{@I ragged}: +@IndentedList +@LI @Tab + @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B } +{ +@Rowa + A { "ragged @Break ..." } + B { ragged @Break { +It is a truth universally +acknowledged, that a single man +in possession of a good fortune, +must be in want of a wife. +}} +} +@LI @Tab + @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B } +{ +@Rowa + A { "cragged @Break ..." } + B { cragged @Break { +It is a truth universally +acknowledged, that a single man +in possession of a good fortune, +must be in want of a wife. +}} +} +@LI @Tab + @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B } +{ +@Rowa + A { "rragged @Break ..." } + B { rragged @Break { +It is a truth universally +acknowledged, that a single man +in possession of a good fortune, +must be in want of a wife. +}} +} +@LI @Tab + @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B } +{ +@Rowa + A { "oragged @Break ..." } + B { oragged @Break { +It is a truth universally +acknowledged, that a single man +in possession of a good fortune, +must be in want of a wife. +}} +} +@EndList +The paragraph is broken in the same places as @Code adjust breaks it, +but the resulting lines are left-justified, centred, or right-justified +with respect to each other, rather than adjusted; @Code "oragged" +is like @Code "outdent" except the resulting lines are not adjusted. +@PP +If you have a few words that must be kept together on one line, the +preventing. @Index { preventing line breaks } +keeping. @Index { keeping things on one line } +recommended way is to separate them by an @Code "~" symbol: +@ID @Code "According to Prof.~Jones, the effect of ..." +It's best not to bother about this until you actually get a bad line +break, since chances are good that the words will fall on one line anyway. +@PP +The last three styles differ from the first five in breaking the +paragraph at the points where it is broken in the original input: +lines. @Index { @Code lines paragraph breaking style } +clines. @Index { @Code clines paragraph breaking style } +rlines. @Index { @Code rlines paragraph breaking style } +@IndentedList +@LI @Tab + @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B } +{ +@Rowa + A { "lines @Break ..." } + B { lines @Break { +It is a truth universally +acknowledged, that a single man +in possession of a good fortune, +must be in want of a wife. +}} +} +@LI @Tab + @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B } +{ +@Rowa + A { "clines @Break ..." } + B { clines @Break { +It @PageMark clines is a truth universally +acknowledged, that a single man +in possession of a good fortune, +must be in want of a wife. +}} +} +@LI @Tab + @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B } +{ +@Rowa + A { "rlines @Break ..." } + B { rlines @Break { +It is a truth universally +acknowledged, that a single man +in possession of a good fortune, +must be in want of a wife. +}} +} +@EndList +The lines are left-justified, centred, or right-justified with respect +to each other in the same way as for the ragged styles. +@PP +When using the @Code lines style, there are some fine points concerning +the proper use of white space. Consider this example: +@ID @OneRow @Code { +"@IndentedDisplay lines @Break @I {" +"Teach me to hear Mermaides singing," +"Or to keep off envies stinging," +" And finde" +" What winde" +"Serves to'advance an honest minde." +"}" +} +The result is the indented display +@IndentedDisplay lines @Break @I { +Teach me to hear Mermaides singing, +Or to keep off envies stinging, + And finde + What winde +Serves to'advance an honest minde. +} +This style is the only one for which it is useful to indent individual +lines in the input; as the result shows, such indents will be +respected, as will blank lines. However, Lout's rule that only white +space separating objects affects the result (Section {@NumberOf spaces}) +still holds, which means that indenting the first line is not +effective: +@ID @OneRow @Code { +"@IndentedDisplay lines @Break @I {" +" And finde" +" What winde" +"Serves to'advance an honest minde." +"}" +} +produces +@IndentedDisplay lines @Break @I { + And finde + What winde +Serves to'advance an honest minde. +} +This may seem awkward at first, but actually it is extremely convenient +because you don't have to worry about whether the first line of the +paragraph should appear on a new line as above, or immediately after +the opening brace: space at that point does not separate two objects, +so it has no effect. The indent can be obtained by +starting the first line with an empty object (Section {@NumberOf empty}): +@ID @OneRow @Code { +"@IndentedDisplay lines @Break @I {" +"{} And finde" +" What winde" +"Serves to'advance an honest minde." +"}" +} +The result is +@IndentedDisplay lines @Break @I { +{} And finde + What winde +Serves to'advance an honest minde. +} +as desired. To set the entire document in a paragraph breaking style other +than {@Code "adjust"}, you need to change the @Code "@InitialBreak" option, +as explained at the end of Section {@NumberOf linespace}. +@PP +Some people don't like to see the first line of a paragraph alone at the +widows @Index { widow lines } +orphans @Index { orphan lines } +unbreakablefirst. @Index { @Code unbreakablefirst } +unbreakablelast. @Index { @Code unbreakablelast } +foot of a page or column (the rest appearing on the next page). You can +instruct Lout not to allow this with +@ID @Code "unbreakablefirst @Break ..." +meaning that the first line cannot be broken off from the rest of the +paragraph. Similarly, +@ID @Code "unbreakablelast @Break ..." +instructs Lout to prevent the last line of a paragraph from appearing +alone at the top of a page or column. These features would probably be +invoked in the @Code "@InitialBreak" option, like this: +@ID +@Code "@InitialBreak { unbreakablefirst unbreakablelast hyphen adjust 1.2fx }" +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. +@End @Section diff --git a/doc/user/bas_spac b/doc/user/bas_spac new file mode 100644 index 0000000..b7546c2 --- /dev/null +++ b/doc/user/bas_spac @@ -0,0 +1,103 @@ +@Section + @Title { Spaces and braces } + @Tag { spaces } +@Begin +@PP +Every symbol in Lout either consists entirely of letters ({@Code "@"} +symbols. @Index { symbols, makeup of } +is considered to be a letter) or entirely of punctuation characters. Here +are some examples of each type: +@ID @OneRow @Tab + @Fmta { @Col @I @CC A ! @Col @I @CC B } + @Fmtb { @Col @Code @CC A ! @Col @Code @CC B } +{ +@Rowa A { From letters } B { From punctuation } +@Rowb A { "@PP" } B { "{" } +@Rowb A { "margin" } B { "}" } +} +Now if two symbols made from letters are run together like this: +@ID { +@Code "@CurveBox@I Hello" &8ct @I (wrong!) +} +Lout will take this to mean one word or symbol called {@Code "@CurveBox@I"}, +which is wrong. In the same way, a letter-type symbol cannot be run +together with a word. However, punctuation-type symbols can be run together +with anything. For example, in +@ID @Code "@CurveBox{ Hello @I { world }}." +Lout understands that @Code "@CurveBox" and @Code "{" +# } +are separate, and it also sorts out +# {{ +@Code "}}." into two right brace symbols and a full stop. It might +seem strange to treat punctuation and letters so differently, +but computer programming languages have done it like this for +many years, and it works well. This is the first use for +spaces. @Index { spaces, significance of } +spaces: to separate letter-type symbols from each other and from words. +@PP +To see the second use for spaces, consider two words side by side: +@ID @Code "Hello world" +We want this to produce Hello world, so a space between two words in +the input must mean a space between them in the result. Apply the +golden rule (where you can put one object, you can put any object) and +you get this: @I { a space between two objects in the input produces +a space between them in the result }. For example, +@ID @Code "@CurveBox Hello @CurveBox world" +produces +@ID { @CurveBox Hello @CurveBox world } +The space between the two objects @Code "@CurveBox Hello" and +@Code "@CurveBox world" appears between them in the result; the other +two spaces do not separate objects so do not appear in the result. +@PP +Two objects may be separated by a number of spaces other than one. If +they are separated by no spaces, they will appear immediately adjacent +in the result; if separated by two spaces, they will appear two spaces +apart; and so on. In English it is correct to leave two spaces between +the end of one sentence and the beginning of the next, for example. See +Section {@NumberOf white} for two alternative ways to interpret white +space in Lout. +@PP +Occasionally the two uses for spaces conflict. For example, to produce +@ID { { @CurveBox Hello }{ @CurveBox world } } +we need to have no spaces between the two objects, but then @Code "Hello" +and the following @Code "@CurveBox" would be run together, which will +not work. The solution is to use braces: +@ID @Code "{ @CurveBox Hello }{ @CurveBox world }" +None of the six spaces in this example lie between two objects. +@PP +However, the main use of braces is to inform Lout that the object +within them is to be kept together, so that any nearby symbols are to +apply to all of it. For example, leaving the braces out of +@Code "@I { Hello world }" would mean that @Code "@I" applies only to +{@Code "Hello"}. +@PP +When an object-consuming symbol like @Code "@I" is followed by an +braces. @Index { braces, effect of } +object enclosed in braces, that is the object consumed. For example, +@ID @Code "This is @I { absolutely necessary }, since otherwise ..." +produces +@ID { This is @I { absolutely necessary }, since otherwise ... } +with the object @Code "absolutely necessary" italicized, but not the +following comma. If there are no braces, the object consumed is +everything up to the next object-separating space: +@ID @Code "This is @I necessary, since otherwise ..." +produces +@ID { This is @I necessary, since otherwise ... } +with an undesirable italic comma. In practice, this means you can +avoid braces only when italicizing a single word with no punctuation +attached. +@PP +One common pitfall is to use unnecessary braces, like this: +@ID { +@Code "@I { @CurveBox { Hello world } }" &8ct @I (bad!) +} +Another is to think that all spaces produce space in the result, and so +write +@ID { +@Code "@I{@CurveBox{Hello world}}" &8ct @I (worse!) +} +Use braces only when necessary, and add extra spaces where they do not +separate objects, and your documents will be far easier to read while +you are working on them. Don't be fooled by the argument that says it +doesn't matter because it doesn't affect the final printed result. +@End @Section diff --git a/doc/user/bas_star b/doc/user/bas_star new file mode 100644 index 0000000..ef65eb6 --- /dev/null +++ b/doc/user/bas_star @@ -0,0 +1,129 @@ +@Section + @Title { Getting started } + @Tag { start } +@Begin +@PP +Suppose you want to produce the following little document: +@CD @Box margin { 1.3c } 7.0c @Wide 9c @High { +@Display @Heading { Introduction by W. J. Harvey } +harvey.w.j @Index { Harvey, W. J. } +For Virginia Woolf, @I Middlemarch was `the magnificent book +which for all its imperfections is one of the few English novels +written for grown-up people.' +@PP +She was, no doubt, thinking of George Eliot's unblinking but +eliot.g @Index { Eliot, George } +compassionate delineation of her characters, of the subtlety of +psychological analysis and the maturity of moral comment which +underlie this complex and varied novel of English provincial +life in the early nineteenth century. +} +Unlike word processing and desktop publishing systems, with Lout you +cannot see and edit your document on the screen in this finished +form. Instead, you edit an ordinary text file, in which your text is +augmented with symbols that mark out the headings, paragraphs, and so +on. Although it would be nice to be able to see and edit the finished +form, working with a text file and symbols does have some compensating +advantages. +@PP +The first step in producing your introduction to @I Middlemarch is to +use the text editor of your choice to construct this text file: +@ID @OneRow @Code { +"@SysInclude { doc }" +"@Doc @Text @Begin" +"@Display @Heading { Introduction by W. J. Harvey }" +"For Virginia Woolf, @I Middlemarch was `the magnificent book which for all its" +"imperfections is one of the few English novels written for grown-up people.'" +"@PP" +"She was, no doubt, thinking of George Eliot's unblinking but compassionate" +"delineation of her characters, of the subtlety of psychological analysis and" +"the maturity of moral comment which underlie this complex and varied novel" +"of English provincial life in the early nineteenth century." +"@End @Text" +} +Comparing this with the finished form, it's easy to guess that +@Code "@I" is a symbol that causes the following thing to be printed +in italics, and that @Code "@PP" starts a new paragraph. The other +symbols are not much harder. +@PP +@Code "@SysInclude { doc }" instructs Lout to read a @I { setup file } +called {@Code "doc"}, in which the symbols are defined. Setup files +are the subject of Chapter {@NumberOf changes}, but you can go a long +way without worrying about them. @Code "@Doc @Text @Begin" and +@Code "@End @Text" have no visible effect, but they must bracket the +document as a whole. Again, you don't have to know what they are for. +@PP +That explains everything except the part that produces the heading. It's +an interesting glimpse of the way that Lout's symbols cooperate with +each other: +@ID @Code "@Display @Heading { Introduction by W. J. Harvey }" +The @Code "@Display" symbol does the centring and leaves space above +and below, while @Code "@Heading" switches to a bold font. The braces +group the words of the heading together so that these symbols apply to +all of it; without them they would apply to just the first word. All +this is explained in detail in Sections {@NumberOf objects} +and {@NumberOf spaces}. +@PP +Once the file is ready, the next step is to get it processed by the +Basser Lout interpreter. If the file's name is {@Code "intro"}, +the command for this on the Unix +@FootNote { Unix is a trademark. } +operating system is +@ID @Code "lout intro > intro.ps" +The output is the PostScript +@FootNote { PostScript is a trademark of Adobe Systems, Inc. } +file {@Code "intro.ps"}, which is suitable for printing on many laser +printers and other devices. There are programs that show you the +result on your screen as well, although you won't be able to edit it +there. You can also get plain text output (Section {@NumberOf plain}) +and PDF output. +@PP +There are a few points that often confuse people as they begin, so we'll +treat them briefly now with pointers to later sections where they are +done properly. +@PP +Some characters are symbols that produce special effects -- for +example, @Code "{" and @Code "}" produce grouping -- and to turn off +these effects the characters must be enclosed in double quotes: @Code +"\"{\"" produces "{". The complete set of these special characters is +@ID @Code "/ | & { } # @ ^ ~ \\ \"" +Section {@NumberOf characters} treats unusual characters in full detail. +@PP +Symbols like @Code "@Doc" and @Code "@Text" must be separated from +each other by one or more spaces, otherwise Lout will think they are part +of one symbol. See Section {@NumberOf spaces} for the details. +@PP +People familiar with other systems might expect that leaving a blank line would +cause Lout to start a new paragraph; but this is not so, you must use a +paragraph symbol. Lout will ordinarily take notice of how many spaces you type +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 beginning with +error.messages @Index { error messages } +`unresolved cross reference' -- 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 again to finish off +the complicated things (Section {@NumberOf cross}), and they will gradually +go away. Of course, if you see error messages about missing braces, unknown +symbols, and so on, you need to revise your file. Lout will tell you the +line number of the problem, and how far along the line it is. +@PP +@BI { WARNING: } Lout allows documents to cause arbitrary system commands +to be executed. These typically do useful things such as format computer +programs and uncompress graphics files, but it is possible for a +malicious person to send you a document which includes a command to delete +all your files, send abusive mail to the President of the United States in +your name, etc. You can protect yourself against this possibility by using +the `safe execution' flag: +@ID @Code "lout -S suspect.document > out.ps" +Then no system commands will be executed; instead, Lout will print them so +that you can confirm for yourself that they are safe before running again +without the flag. These system commands are Lout's only potentially unsafe +features, but you also need to worry about whether the resulting PostScript +file contains malicious code, since the document may direct Lout to include +arbitrary PostScript code in the output. The safe execution of PostScript +programs is a matter for PostScript interpreters, not for Lout. For example, +the popular Ghostview program has a @Code "-safer" command line option, +which is rumoured to disable unsafe PostScript features. +@End @Section diff --git a/doc/user/bas_supe b/doc/user/bas_supe new file mode 100644 index 0000000..40faf92 --- /dev/null +++ b/doc/user/bas_supe @@ -0,0 +1,17 @@ +@Section + @Title { Superscripts and subscripts } + @Tag { super } +@Begin +@PP +There are @Code "@Sup" and @Code "@Sub" symbols for producing +superscripts and subscripts: +@ID @Code "2 @Sup nd" +produces +@ID { 2 @Sup nd } +and the @Code "@Sub" symbol works in a similar way. These symbols +are probably never required in English language text, since the +only uses for them are in footnotes, which produce the superscript +automatically, and equations, which have their own versions of these +symbols. Both symbols have a @Code "gap" option which determines the +vertical spacing. +@End @Section diff --git a/doc/user/bas_unde b/doc/user/bas_unde new file mode 100644 index 0000000..9f7ea94 --- /dev/null +++ b/doc/user/bas_unde @@ -0,0 +1,27 @@ +@Section + @Title { Underlining } + @Tag { underlining } +@Begin +@PP +The @Code "@Underline" symbol underlines the following object: +underline.sym @Index @Code "@Underline" +@ID @OneRow @Code { +"This little paragraph of text will have" +"@Underline { three underlined words } in it." +} +produces +@ID @OneRow 1.6i @Wide { +This little paragraph of text will have +@Underline { three underlined words } in it. +} +The underlining is continuous unless a line break intervenes. You +can't use this symbol to underline an arbitrary object: it is carefully +designed to produce high-quality underlining of single words and +parts of paragraphs, and it works only for those objects. +@PP +Each font contains information about how words in that font should be +underlined: how far below the baseline the line should be drawn, and how +thick. The @Code "@Underline" symbol uses this information; the font +it bases its underlining on is the font of the first object underlined +if it is a word, or else the font of the enclosing paragraph. +@End @Section diff --git a/doc/user/bas_verb b/doc/user/bas_verb new file mode 100644 index 0000000..6da835a --- /dev/null +++ b/doc/user/bas_verb @@ -0,0 +1,49 @@ +@Section + @Title { Verbatim text } + @Tag { verbatim } +@Begin +@PP +The @Code "@Verbatim" symbol +@FootNote { Prior to Version 3.13 the @Code "@Verbatim" symbol was +implemented in a way that restricted its availability to Unix +systems only. This restriction no longer applies. } +prints the following object exactly as +verbatim.sym @Index @Code "@Verbatim" +it appears in the input file. All special meanings for characters, +symbols, etc. are turned off; there is one result line for +each input line. For example, +@ID @Code @Verbatim { +@IndentedDisplay @Verbatim { +A line of "verbatim" text +Another line, with a \ character +} +} +has result +@IndentedDisplay @Verbatim { +A line of "verbatim" text +Another line, with a \ character +} +Use @Code "@F @Verbatim { ... }" to get the result in a fixed-width font. +@PP +If the verbatim text contains @Code "{" or @Code "}" characters, then +they should either be balanced or else you need to use the alternative +form +@ID @Code { +"@Verbatim @Begin" +"..." +"@End @Verbatim" +} +so that there is no doubt about where the verbatim text ends. Although +we have said that there are no special meanings, there is one exception +to this rule: @Code "@Include" and @Code "@SysInclude" commands are +recognized, allowing all or part of the verbatim text to come from some +other file. +@PP +Occasionally the first line of some verbatim text begins with some +spaces that have to be preserved. This is a problem for @Code "@Verbatim" +because it ignores all white spaces following the opening brace and +all white spaces preceding the closing brace. However, the alternative +@Code "@RawVerbatim" symbol stops ignoring white spaces at the opening +as soon as a newline character is reached; in other words, it will +preserve all white spaces following the first newline. +@End @Section diff --git a/doc/user/bgr b/doc/user/bgr new file mode 100644 index 0000000..9452ff0 --- /dev/null +++ b/doc/user/bgr @@ -0,0 +1,17 @@ +@Chapter + @Title { Basic Graphics } + @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. +@BeginSections +@Include { bgr_colo } +@Include { bgr_boxs } +@Include { bgr_rota } +@Include { bgr_scal } +@Include { bgr_incl } +@EndSections +@End @Chapter diff --git a/doc/user/bgr_boxs b/doc/user/bgr_boxs new file mode 100644 index 0000000..39c6460 --- /dev/null +++ b/doc/user/bgr_boxs @@ -0,0 +1,121 @@ +@Section + @Title { Boxes and rules } + @Tag { boxes } +@Begin +@PP +The @Code "@Box" symbol causes the following object to be enclosed in a +box. @Index @Code "@Box" +box: +@ID @OneRow @Code { +"@QuotedDisplay @Box {" +"@CentredDisplay @Heading Cheating" +"The Department uses assignments ... of that student alone." +"}" +} +The result of this is +@QuotedDisplay @Box { +@CentredDisplay @Heading Cheating +The Department uses assignments both as a teaching device and as a +major component of its assessment of each student. It therefore +requires that all programs, exercises etc. handed in bearing an +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 +margin between the box and what it encloses. For example, +@ID @OneRow @Code { +"@Box" +" margin { 0.1c }" +"{}" +} +requests a box with a 0.1 centimetre margin enclosing an empty object, +so the result is a square whose width and height are 0.2 centimetres: +@ID @Box margin { 0.1c } {} +If the @Code "margin" option is omitted, it is assigned the default +value {@Code "0.3f"}, which means 0.3 times the current font size. It +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 +(thickness) of the line drawn around the boundary of the box: +@ID @OneRow @Code { +"@Box" +" linewidth { 0.1c }" +"{ Hello world }" +} +produces +@ID @Code { +@Box + linewidth { 0.1c } +{ Hello world } +} +Lout does not take the line width into account when working out how +large everything is: as far as Lout is concerned, the line always +has width zero. If you draw really thick lines you might need a larger +margin and more space near the box. The default value of @Code linewidth +is empty, which means to use whatever width the PostScript interpreter +in your output device thinks is a good default value. +@PP +There is also a @Code "paint" option which paints a background of the +nominated colour: +@ID @Code "@Box paint { grey } WARNING!" +has result +@ID @Box paint { grey } WARNING! +This is quite different from {@Code "grey @Colour @Box WARNING!"}, +which produces +@ID grey @Colour @Box WARNING! +The @Code "paint" option may be given any colour from the list in +Section {@NumberOf colour}; its default value is {@Code "none"}, which +is a special value (not a colour) which means no painting. White paint +comes into its own inside painted boxes: +@ID @Code "@Box paint { nochange } white @Colour { Hello world }" +produces a box painted in whatever colour we happen to be using at +the moment, with white text inside: +@ID @Box paint { nochange } white @Colour { Hello world } +This works because the box is painted before the object it encloses +is drawn on the page. +@PP +There are @Code "@CurveBox" and @Code "@ShadowBox" symbols that +curvebox. @Index @Code "@CurveBox" +shadowbox. @Index @Code "@ShadowBox" +produce other kinds of boxes: +@CD @Tab + @Fmta { @Col A ! @Col ! @Col B } +{ +@Rowa + 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"}). +@PP +Boxes are quite at home inside paragraphs, as @Box { a box }, +@CurveBox { a curve box }, and @ShadowBox { a shadow box } +show. Simply proceed as usual: +@ID @Code "... paragraphs, as @Box { a box }, @CurveBox { a curve box }, ..." +Boxes within paragraphs are never broken across two lines. +@PP +There are two symbols for producing horizontal rules. @Code "@FullWidthRule" +fullwidthrule. @Index @Code "@FullWidthRule" +rules. @Index rules +produces a rule which occupies the full page (or column) width: +@DP @FullWidthRule @DP +More precisely, the rule occupies as much horizontal space as it +legally can. @Code "@FullWidthRule" produces an object in the usual +way, so you will need paragraph or display symbols to separate it from +preceding and following things. +@PP +A variant called @Code "@LocalWidthRule" is more timid about zooming +localwidthrule. @Index @Code "@LocalWidthRule" +across the whole page: +@ID @Code { +"@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. +@End @Section diff --git a/doc/user/bgr_colo b/doc/user/bgr_colo new file mode 100644 index 0000000..4a48fb9 --- /dev/null +++ b/doc/user/bgr_colo @@ -0,0 +1,48 @@ +@Section + @Title { Colour } + @Tag { colour } +@Begin +@PP +Colour is obtained in much the same way that fonts and language changes +colour. @Index @Code "@Colour" +color. @Index @Code "@Color" +are, using the @Code "@Colour" (or equivalently {@Code "@Color"}) symbol: +@ID @Code "grey @Colour { Hello, world }" +produces +@ID grey @Colour { Hello, world } +The @Code "@Colour" symbol will accept any of the following colours: +@QD @HAdjust @Tab + vmargin { 0.7vx } + hmargin { 0.2c } + @Fmta { @Col A @Colour @FilledBox ! @Col @Code A ! @Col ! + @Col B @Colour @FilledBox ! @Col @Code B ! @Col ! + @Col C @Colour @FilledBox ! @Col @Code C } + @Fmtb { @Col A @Colour @FilledBox ! @Col @Code A ! @Col ! + @Col B @Colour @FilledBox ! @Col @Code B ! @Col ! + @Col ! @Col } +{ +@Rowa A { darkred } B { red } C { lightred } +@Rowa A { darkgreen } B { green } C { lightgreen } +@Rowa A { darkblue } B { blue } C { lightblue } +@Rowa A { darkcyan } B { cyan } C { lightcyan } +@Rowa A { darkmagenta } B { magenta } C { lightmagenta } +@Rowa A { darkyellow } B { yellow } C { lightyellow } +@Rowa A { darkgrey } B { grey } C { lightgrey } +@Rowa A { darkgray } B { gray } C { lightgray } +@Rowb A { black } B { white } +} +Monochrome output devices will render them as shades of grey. Colouring +something @Code white makes it invisible, which is sometimes useful. +@PP +In addition to the list of colours given above, there is a special +colour called {@Code nochange} which produces the colour you already +happen to be using. +@PP +Whether or not 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. The +standard Lout @Code "@SetColour" symbol can provide many more colours +setcolour. @Index @Code "@SetColour" +@Cite { $kingston1995lout.expert}, although they must be specified +using numbers rather than names. +@End @Section diff --git a/doc/user/bgr_incl b/doc/user/bgr_incl new file mode 100644 index 0000000..57ac4a1 --- /dev/null +++ b/doc/user/bgr_incl @@ -0,0 +1,47 @@ +@Section + @Title { Including an illustration } + @Tag { include } +@Begin +@PP +The @Code "@IncludeGraphic" symbol incorporates into a Lout document an +include.graphic @Index @Code "@IncludeGraphic" +include.illus @Index { including an illustration } +illustration (that is, an encapsulated PostScript or EPS file) +produced by other means. For the opposite process, using Lout to produce +an illustration for inclusion in some other document, see +Section {@NumberOf illustrations}. +@PP +For example, suppose the encapsulated PostScript file @Code "su_crest.eps" +contains the University of Sydney crest. Then +@ID @Code "@IncludeGraphic su_crest.eps" +produces +@ID @IncludeGraphic su_crest.eps +In general, the result produced by @Code "@IncludeGraphic" is an object +that may be scaled, rotated, made into a display or placed within a +paragraph, just like any other object. Accolades for this remarkable +flexibility should go to the PostScript page description language, +whose extraordinary power makes the provision of this feature in Lout +almost trivial. +@PP +The @Code "@IncludeGraphic" command understands that files ending +with any of the suffixes {@Code ".gz"}, {@Code "-gz"}, {@Code ".z"}, +{@Code "-z"}, {@Code "_z"}, and {@Code ".Z"} are compressed files, +and it will uncompress such files using the @Code "gunzip" command +before including them. The uncompressed version is stored in a file +called @Code "lout.eps" in the current directory, and removed after +being copied into the output file. +@PP +If you place an included illustration in a line of text, or anywhere +where you care about its alignment with things on either side of it, +it will be positioned with its centre at the same height as the +centre of the letter x. If this is not where you want it, use the +@Code "@VShift" symbol: +vshift. @Index @Code "@VShift" +@ID @Code "... +0.5f @VShift @IncludeGraphic ..." +prints the illustration half of the current font size higher on the +page than would otherwise have been the case, and +@ID @Code "... -0.5f @VShift @IncludeGraphic ..." +prints it half the current font size lower. Any length (Section +{@NumberOf objects}) is allowed, and the object following @Code "@VShift" +may in fact be arbitrary as usual. +@End @Section diff --git a/doc/user/bgr_rota b/doc/user/bgr_rota new file mode 100644 index 0000000..e4bcc72 --- /dev/null +++ b/doc/user/bgr_rota @@ -0,0 +1,35 @@ +@Section + @Title { Rotation } + @Tag { rotation } +@Begin +@PP +The @Code "@Rotate" symbol rotates the following object by any positive +rotate. @Index @Code "@Rotate" +or negative angle, measured in degrees: +@ID @Code "45d @Rotate @Box WARNING!" +has result +@ID { 45d @Rotate @Box WARNING! } +As usual, the object to be rotated may be arbitrary. However, it is +difficult for Lout to choose appropriate column widths for paragraphs +inside rotated objects, so if a rotated object contains paragraphs that +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" +"}" +} +The result here is +@ID { +-90d @Rotate 4.5c @Wide { +Papal initiatives and influence from the crowning of +Charlemagne to the First Crusade +} +} +The @Code "@Wide" symbol fixes the width of the following object, in +this example to the length 4.5 centimetres, which is all Lout needs to +decide the column widths of any paragraphs within it. +@End @Section diff --git a/doc/user/bgr_scal b/doc/user/bgr_scal new file mode 100644 index 0000000..ad73f4c --- /dev/null +++ b/doc/user/bgr_scal @@ -0,0 +1,53 @@ +@Section + @Title { Scaling } + @Tag { scaling } +@Begin +@PP +The @Code "@Scale" symbol performs a geometrical scaling of the +scale. @Index @Code "@Scale" +following object: +@ID @Code { +"0.5 @Scale @Box WARNING!" +} +produces +@ID { +0.5 @Scale @Box WARNING! +} +A scale factor of 0.5 means half the original size, 2.0 means double size, +and so on. No unit of measurement appears in the scale factor, because +it makes no sense to have one. As usual, the object to be scaled may be +arbitrary. +@PP +It is also possible to supply two scale factors, in which case the +first is applied horizontally and the second vertically: +@ID @Code "{0.5 2.0} @Scale @Box WARNING!" +has result +@ID {0.5 2.0} @Scale @Box WARNING! +Practical uses for this kind of scaling are rare. +@PP +If an empty object is given instead of a scale factor, like this: +@ID @Code "{} @Scale @Box WARNING!" +the @Code "@Scale" symbol will choose the largest scale factor that +does not overrun the available horizontal space. It is often possible +to omit the {@Code "{}"}, since Lout inserts an empty object +automatically whenever an object is clearly missing (see Section +{@NumberOf objects}). For example, +@ID @Code "@QuotedDisplay @Scale @Box WARNING!" +produces +@QuotedDisplay @Scale @Box WARNING! +@Code "@QuotedDisplay" and @Code "@LeftDisplay" go well with this form +of {@Code "@Scale"}. However, some care is needed because Lout foolishly +takes no account of the available @I vertical space when choosing the +scale factor. The chosen scale factor could enlarge the vertical size so +much that the object no longer fits on the page, with disastrous results. +@PP +By using a @Code "@Wide" symbol to restrict the available horizontal +space, this form of scaling can also be used to scale to a nominated +width. For example, +wide @RawIndex { @Code "@Wide" } +wide.scale @SubIndex { with @Code "@Scale" } +@ID @Code "5c @Wide @Scale @Box WARNING!" +produces +@ID { 5c @Wide @Scale @Box WARNING! } +which is 5 centimetres wide. +@End @Section diff --git a/doc/user/cpp b/doc/user/cpp new file mode 100644 index 0000000..9b413ed --- /dev/null +++ b/doc/user/cpp @@ -0,0 +1,27 @@ +@Chapter + @Title { C and C++ Programs } + @Tag { cprint } +@Begin +@LP +This chapter describes how to typeset C and C++ program text using the +cp. @Index @Code "@CP" +c. @Index { C++ } +@Code "@CP" symbol in conjunction with the @Code c2lout filter. The +@Code "@CP" symbol looks after printing keywords in bold, variables +in italic, and so on, depending on a style you choose. It does not lay +out programs in the sense of choosing indenting, it preserves the layout +you give to the program. From now on, `C' means `C or C++' wherever +it occurs. +@PP +It is possible to simply print out one or more C files; we call this +@I { stand-alone mode }. Alternatively, the C program text may be printed +as part of a larger Lout document; we call this @I { embedded mode }. +@BeginSections +@Include { cpp_lone } +@Include { cpp_embe } +@Include { cpp_chan } +@Include { cpp_comm } +@Include { cpp_tabs } +@Include { cpp_eiff } +@EndSections +@End @Chapter diff --git a/doc/user/cpp_chan b/doc/user/cpp_chan new file mode 100644 index 0000000..ddedd51 --- /dev/null +++ b/doc/user/cpp_chan @@ -0,0 +1,83 @@ +@Section + @Title { Changing the default values } + @Tag { cpsetup } +@Begin +@PP +We have just seen that the @Code "@CP" symbol has many options for +changing the appearance of the C text. However, most people would +not want to have a different style for every C text in their document; +they want to define the style once at the start, and have all their +C texts come out in that style without laboriously setting options +on every @Code "@CP" symbol. This is done by copying the setup file +and changing it. +@PP +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 "@CPSetup" @Code "@Use" clause near the end of +cprint. @Index @Code "@CPSetup" +the @Code "cpsetup." setup file: +@ID @Code @Tab + vmargin { 0.5vx } + @Fmta { @Col A ! @Col B ! @Col C} + @Fmtb { @Col { " #" A } ! @Col { "{" B } ! @Col "}" } +{ +@Rowa A { "@Use { @CPSetup" } +@Rowb A { "style" } B { fixed } + +@Rowa +@Rowb A { "fixedfont" } B { Courier } +@Rowb A { "fixedstrings" } B { Base } +@Rowb A { "fixedidentifiers" } B { Base } +@Rowb A { "fixedcomments" } B { Base } +@Rowb A { "fixedkeywords" } B { Base } +@Rowb A { "fixednumbers" } B { Base } +@Rowb A { "fixedoperators" } B { Base } +@Rowb A { "fixedsize" } B { -1.0p } +@Rowb A { "fixedline" } B { 1.0vx } +@Rowb A { "fixedtabin" } B { 8 } +@Rowb A { "fixedtabout" } B { 8s } + +@Rowa +@Rowb A { "varyingfont" } B { } +@Rowb A { "varyingstrings" } B { Slope } +@Rowb A { "varyingidentifiers" } B { Slope } +@Rowb A { "varyingcomments" } B { Base } +@Rowb A { "varyingkeywords" } B { Bold } +@Rowb A { "varyingnumbers" } B { Base } +@Rowb A { "varyingoperators" } B { Base } +@Rowb A { "varyingsize" } B { 1.0f } +@Rowb A { "varyingline" } B { 1.0vx } +@Rowb A { "varyingtabin" } B { 8 } +@Rowb A { "varyingtabout" } B { 3f } + +@Rowa +@Rowb A { "symbolfont" } B { } +@Rowb A { "symbolstrings" } B { Slope } +@Rowb A { "symbolidentifiers" } B { Slope } +@Rowb A { "symbolcomments" } B { Base } +@Rowb A { "symbolkeywords" } B { Bold } +@Rowb A { "symbolnumbers" } B { Base } +@Rowb A { "symboloperators" } B { Base } +@Rowb A { "symbolsize" } B { 1.0f } +@Rowb A { "symbolline" } B { 1.0vx } +@Rowb A { "symboltabin" } B { 8 } +@Rowb A { "symboltabout" } B { 3f } + +@Rowa A { "}" } +} +These show the default font families, font faces, font sizes, line +spacings, and tab settings in force for the three styles, and also that +the default style is {@Code "fixed"}. Notice that the font family name +for @Code "fixed" style is {@Code "Courier"}, but for the other styles is +empty. This causes the @Code "fixed" style to always switch to Courier, +and the other styles to use the same font family as in the surrounding +document. +@PP +To change a default value, delete the preceding @Code "#" and change the +part between braces. For example, suppose you are happy with @Code "fixed" +except that you want bold keywords. Then one line needs to be changed, to +@ID @Code "fixedkeywords { Bold }" +Or suppose you like @Code "varying" as it stands, but would like it to be +the default style rather than {@Code "fixed"}. Again, only one line needs +to be changed, to {@Code "style { varying }"}. +@End @Section diff --git a/doc/user/cpp_comm b/doc/user/cpp_comm new file mode 100644 index 0000000..f877c06 --- /dev/null +++ b/doc/user/cpp_comm @@ -0,0 +1,20 @@ +@Section + @Title { Lout inside C comments } + @Tag { cpcomm } +@Begin +@PP +It is possible to embed Lout text inside C and C++ comments, by +starting off the comment with an @Code "@" character. The entire +comment after the @Code "@" character should be Lout text. For +example, to force Lout to start a new page at some point within a C +program, place +@ID @Code "/*@ @NP */" +at that point. Or you could make a heading like this: +@ID @Code "/*@ @Display @Heading { treeprint() } */" +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, since +that would require a C comment inside a C comment. +@End @Section diff --git a/doc/user/cpp_eiff b/doc/user/cpp_eiff new file mode 100644 index 0000000..d0ec6df --- /dev/null +++ b/doc/user/cpp_eiff @@ -0,0 +1,42 @@ +@Section + @Title { Eiffel program printing } + @Tag { eiffel } +@Begin +@PP +There is an @Code "@Eiffel" symbol for typesetting Eiffel programs +in conjuction with a filter called {@Code "eif2lout"}. Apart from +the change of language, everything is identical to C printing. The +file and symbol names are different, of course: +@ID @OneRow @Tab + vmargin { 0.5vx } + @Fmta { @Col A ! @Col B } +{ +@Rowa + A { @Code cprint } + B { @Code eiffel } +@Rowa + A { @Code c2lout } + B { @Code eif2lout } +@Rowa + A { @Code "@CP" } + B { @Code "@Eiffel" } +@Rowa + A { @Code "@CPSetup" } + B { @Code "@EiffelSetup" } +} +but everything works in an exactly analogous way: you place +@ID @Code "@SysInclude { eiffel }" +at the top of your document, enclose Eiffel program texts in +@Code "@Eiffel { ... }", embed Lout into Eiffel using comments +beginning with {@Code "--@"}, and so on. The default style has been +changed to {@Code varying}, so as to conform to the style guidelines +in the standard Eiffel reference @Cite { $meyer1992eiffel }. Some care +has gone into making this conformance strict; in particular, if you +enclose identifiers within comments in ` and ', as the style guidelines +say you should, they will come out in italics; in fact, arbitrary text +between ` and ' within comments will be set as Eiffel code. +@PP +The files needed for Eiffel printing are distributed separately from +Basser Lout. You can get them from the author's @Code ftp directory +(see the preface of this guide). +@End @Section diff --git a/doc/user/cpp_embe b/doc/user/cpp_embe new file mode 100644 index 0000000..8ca2dfc --- /dev/null +++ b/doc/user/cpp_embe @@ -0,0 +1,152 @@ +@Section + @Title { Embedded mode } + @Tag { embedded } +@Begin +@PP +When the C program texts are to be embedded in a larger Lout document, +the procedure is somewhat different. You need to include the +@Code "cprint" setup file, like this: +@ID @OneRow @Code { +"@SysInclude { cprint }" +"@SysInclude { doc }" +"@Doc @Text @Begin" +"..." +"@End @Text" +} +This file includes everything needed to set up for C program formatting. +@PP +The C parts of the document are enclosed in @Code "@CP { ... }" like this: +@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);" +" }" +"}" +"}" +} +Although C programs violate the rules of legal Lout input in many ways, +these rules are suspended by the @Code "@CP" symbol, allowing the C +text to be incorporated with absolutely no modifications. The result is +@ID @OneRow @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); + } +} +} +We have chosen to use the @Code "@IndentedDisplay" symbol from Section +{@NumberOf displays} to obtain an indented display, but in fact +@Code "@CP" may appear anywhere at all. When including a C text within +a paragraph, use @Code "@OneCol @CP { ... }" to prevent it being broken +across two lines, if desired. +@PP +In cases where the C text has unbalanced braces, it is necessary to +use the alternative form @Code "@CP @Begin ... @End @CP" so that +Lout does not confuse C braces with Lout braces. +@PP +The @Code "@CP" symbol has a @Code "style" option for changing the +printing style. The default value of @Code "style" is {@Code "fixed"}, +which produces the style shown above. To obtain a varying-width font +style, use @Code "style { varying }" 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);" +" }" +"}" +"}" +} +The result in this case will be +@ID @OneRow @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); + } +} +} +There is also a third style called @Code "style { symbol }" which is +similar to @Code "varying" except that it uses characters from the +Adobe Symbol font to produce a more mathematical-looking result: +@ID @OneRow @CP style { symbol } +{ +#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 @Code "@CP" symbol has additional options which allow a finer +control over the style. Here they all are, with their default values: +@ID @OneRow @Code { +"@CP" +" style { fixed }" +" font { Courier }" +" strings { Base }" +" identifiers { Base }" +" comments { Base }" +" keywords { Base }" +" numbers { Base }" +" operators { Base }" +" size { -1.0p }" +" line { 1.0vx }" +" tabin { 8 }" +" tabout { 8s }" +"{" +" ..." +"}" +} +We are already familiar with {@Code "style"}. After that comes +{@Code "font"}, which determines the font family to use, followed +by six options giving the particular faces within that family in which to +print C strings, identifiers, comments, keywords, numbers, and +operators. {@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 shown are correct +for @Code "style { fixed }" only; the other styles have other defaults +(Section {@NumberOf cpsetup}). +@PP +The @Code "size" option is the font size to use, and @Code "line" is the +inter-line spacing. The default values specify that @Code "size" is +to be one point smaller than in the surrounding document; this was done +to compensate for Courier's relatively large appearance compared +to other fonts of the same nominal size. Again, these defaults are +different for different values of {@Code "style"}. +@PP +The @Code "tabin" and @Code "tabout" options are the subject of +Section {@NumberOf tabs}. +@End @Section diff --git a/doc/user/cpp_lone b/doc/user/cpp_lone new file mode 100644 index 0000000..8d8e367 --- /dev/null +++ b/doc/user/cpp_lone @@ -0,0 +1,36 @@ +@Section + @Title { Stand-alone mode } + @Tag { alone } +@Begin +@PP +Printing of C files in stand-alone mode is accomplished by the following +c2lout @Index { @Code "c2lout" filter } +Unix pipeline: +@ID @Code "c2lout options C-files | lout -s > out.ps" +As usual with Lout, the output will be a PostScript file. Each input +file will begin on a new page of the output, starting with its name +in bold type. The options provide control over the final appearance, +as follows: +@WideTaggedList +@TI { {@Code-p}{@I style} } { +Select a printing style. Your choices are {@Code -pfixed}, +{@Code -pvarying}, and {@Code -psymbol}, with the default being +{@Code -pfixed}. Consult Section {@NumberOf embedded} for examples +of these styles. +} +@TI { @Code -n } { +Do not print file names. +} +@TI { {@Code -f}{@I font} } { +Select a Lout font family. The default is @Code "-fCourier" for +{@Code -pfixed}, and @Code "-fTimes" for @Code -pvarying and {@Code -psymbol}. +} +@TI { {@Code -v}{@I vsize} } { +Select an inter-line spacing size in Lout units. The default is +@Code -v1.1fx meaning 1.1 times the font size measured from baseline +to baseline. +} +@EndList +There are also {@Code -t} and {@Code -T} options for dealing with tab +characters (Section {@NumberOf tabs}). +@End @Section diff --git a/doc/user/cpp_tabs b/doc/user/cpp_tabs new file mode 100644 index 0000000..1157a51 --- /dev/null +++ b/doc/user/cpp_tabs @@ -0,0 +1,62 @@ +@Section + @Title { Tab characters } + @Tag { tabs } +@Begin +@PP +Tab characters provide a convenient way to indent and align parts of C +tab.c @Index { tab characters in C programs } +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 input file is by default taken +to be 8 characters, which is standard for Unix. This can be changed with +the @Code "tabin" option. For example, +@ID @Code "@CP tabin { 4 }" +informs Lout that tab stops occur every 4 characters in the input file. +@PP +The distance between two tab stops in the output file (on the printed +page) is quite a different thing, and it is determined by the value of +the @Code "tabout" option, which 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 +words, a distance of one tab stop in the input will be equivalent to a +distance of half an inch in the output. For example, +@ID @Code "@CP style { varying } tabout { 3f }" +might produce the following, where tab characters in the input file +have been used for indenting and also to align the comments: +@ID @OneRow @CP style { varying } tabout { 3f } { +struct tnode { /* the basic node */ + char *word; /* points to the text */ + int count; /* number of occurrences */ + struct tnode *left; /* left child */ + struct tnode *right; /* right child */ +}; +} +The value {@Code "3f"} means three times the current font size, and +it is the default value of @Code "tabout" for the @Code { varying } +and @Code { symbol } styles (Section {@NumberOf cpsetup}). In a +12 point font this is 36 points, or half an inch. +@PP +If @Code "tabout" is made too small, there is a danger that the +alignment might fail. For example, +@ID @Code "@CP style { varying } tabout { 0.2i }" +produces +@ID @OneRow @CP style { varying } tabout { 0.2i } { +struct tnode { /* the basic node */ + char *word; /* points to the text */ + int count; /* number of occurrences */ + struct tnode *left; /* left child */ + struct tnode *right; /* right child */ +}; +} +given the same C text as the previous example. The problem here is that +we are asking for @CP { /* } to appear four tab stops or 0.8 inches +from the left edge, and yet the material to its left on the line is +wider than this. This causes @CP { /* } to be shifted further to the +right than expected, and the alignment is lost. The only solution is +to increase {@Code "tabout"}. +@PP +In stand-alone mode there are @Code "-t" and @Code "-T" options +equivalent to @Code "tabin" and @Code "tabout" respectively. For +example, @Code "-T0.5i" produces a half-inch tab width. +@End @Section diff --git a/doc/user/dia b/doc/user/dia new file mode 100644 index 0000000..4029cec --- /dev/null +++ b/doc/user/dia @@ -0,0 +1,46 @@ +@Chapter + @Title { Diagrams } + @Tag { diagrams } +@Begin +@LP +This chapter describes how to use the @@Diag symbol +diag. @Index { @@Diag } +@FootNote { +Prior to Version 3.09 of Lout, this chapter described a symbol called +fig. @Index @Code "@Fig" +{@Code "@Fig"} which was similar to but more primitive than +{@Code "@Diag"}. For backward compatibility the @Code "@Fig" symbol +is still available and still works exactly as described in the old +documentation, but there is no reason to use it in new documents. +} +to make diagrams like this one: +diag. @Index @Code "@Diag" +@CD @Diag + margin { 0.2c } +{ +-2p @Font +{ A:: @Ellipse { 25, 39 } +/0.3c |0.2c B:: @Ellipse { 43 } |0.1c |0.8c E:: @Box outlinestyle {noline} {Problem node} +/0.3c C:: @Ellipse { 40, 41 } | | D:: @Ellipse paint { lightgrey } {44, 45, 46} +} +// @Link from { A } to { B } +// @Link from { B } to { C } +// @Link from { B } to { D } +// @Arrow from { E } to { D } +} +@@Diag offers nodes and links, arrows, labels, positioning using coordinates, +and tree diagrams. +@BeginSections +@Include { dia_intr } +@Include { dia_node } +@Include { dia_link } +@Include { dia_tags } +@Include { dia_labe } +@Include { dia_posi } +@Include { dia_tree } +@Include { dia_erro } +@Include { dia_defi } +@Include { dia_geom } +@Include { dia_summ } +@EndSections +@End @Chapter diff --git a/doc/user/dia_cons b/doc/user/dia_cons new file mode 100644 index 0000000..569b756 --- /dev/null +++ b/doc/user/dia_cons @@ -0,0 +1,7 @@ +@Section + @Tag { dia_cons } + @Title { Consistency within and between diagrams } +@Begin +@PP +@I { still to do } +@End @Section diff --git a/doc/user/dia_defi b/doc/user/dia_defi new file mode 100644 index 0000000..ed27887 --- /dev/null +++ b/doc/user/dia_defi @@ -0,0 +1,361 @@ +@Section + @Tag { dia_defi } + @Title { Expert usage: defining new shapes } +@Begin +@PP +@@Diag permits you to create your own node outlines and link paths, by +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 +symbols that @@Diag offers for helping you create complex shapes. +@PP +As explained earlier, a node outline is drawn over its {@I base}, which +is a rectangle containing the following object plus margins. The base +defines a coordinate system with the point (0, 0) at the bottom left +corner, and @Eq { (xsize, ysize) } at the top right: +@CD @OneRow @Diag { +@Box + nodelabelmargin { 0.3f } + blabel { @Eq { ysize } } + blabelprox { E } + clabel { @Eq { 0 } } + clabelprox { E } + dlabel { @Eq { xsize } } + dlabelprox { N } + alabel { @Eq { 0 } } + alabelpos { SW } + alabelprox { N } + paint { lightgrey } + outlinestyle { noline } + margin { 0c } +{ 3c @Wide 2c @High } +//0.5c +} +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" +" }" +} +||7ct +@Diag { +@Box + margin { 0c } + outlinestyle { noline } + paint { lightgrey } +@Node + outline { + 0 0 + xsize 0 + 0 ysize + 0 0 + } + margin { 0c } +{ 3c @Wide 2c @High } +} +} +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: +@ID { +@Code { +"@Node" +" outline {" +" 0 0" +" xsize 0" +" 0 ysize" +" 0 0" +" }" +" paint { lightgrey }" +" outlinestyle { solid dashed }" +} +||7ct +@Diag { +@Node + outline { + 0 0 + xsize 0 + 0 ysize + 0 0 + } + paint { lightgrey } + outlinestyle { solid dashed } + margin { 0c } +{ 3c @Wide 2c @High } +} +} +Each line in the outline is one segment for {@Code outlinestyle}. +@PP +If two points in an outline are separated by {@Code "[]"}, no line is +drawn between them, and the outline is treated as two separate, +disconnected regions when painting. +@PP +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" +" }" +} +||7ct +@Diag { +@Box + margin { 0c } + outlinestyle { noline } + paint { lightgrey } +@Node + outline { + 0 0 + ysize 0 + [ 0 0 ] + 0 ysize + 0 0 + } + margin { 0c } +{ 3c @Wide 2c @High } +} +} +The arc will be circular if possible, otherwise it will be part of +elliptical. @Index { elliptical arcs } +an ellipse whose axes are oriented horizontally and vertically. The +arc goes anticlockwise; to get a clockwise arc, use +{@Code "["}{@I point}{@Code " clockwise]"}. +@PP +Two points may be separated by +@Eq { [x sub 1 ``` y sub 1 ``` x sub 2 ``` y sub 2 & ] }, which requests +that a Bezier curve be drawn between them with control points +bezier.curve @Index { Bezier curve } +@Eq { (x sub 1 & , y sub 1 & ) } and +@Eq { (x sub 2 & , y sub 2 & ) }: +@CD @Diag { +@Node + outline { + A:: { xsize*0.2 ysize*0.5 } + B:: { xsize*0.4 ysize*0.9 } + C:: { xsize*0.9 ysize*0.4 } + D:: { xsize*0.3 ysize*0.1 } + A B C D A + } + alabelpos { A } + blabelpos { B } + clabelpos { C } + dlabelpos { D } + alabelprox { SE } + blabelprox { SW } + clabelprox { SW } + dlabelprox { NW } + outlinestyle { cdashed cdashed cdashed noline } + alabel { @Eq { ( x sub 0 , y sub 0 ) } } + blabel { @Eq { ( x sub 1 , y sub 1 ) } } + clabel { @Eq { ( x sub 2 , y sub 2 ) } } + dlabel { @Eq { ( x sub 3 , y sub 3 ) } } +{ 6c @Wide 2c @High } +// +@Link + path { A [B C] D } +} +The curve is attracted toward the control points, without reaching +them; it is tangent to the straight line from the start point to the +first control point, and from the second control point to the finishing +point, and it lies wholly inside the quadrilateral formed by the four +points. Owing to the author's laziness, dashes and dots do not fit as +neatly onto Bezier curves as they do onto lines and arcs. +@PP +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" +" }" +} +||7ct +@Diag { +//0.5f +@ShowTags @Node + outline { + LR:: { xsize 0 } + UL:: { 0 ysize } + 0 0 LR UL 0 0 + } + { 2c @High 3c @Wide } +} +} +The tagged point does not have to lie on the outline, and it +is not automatically added to the outline. Once defined, a +tag stands for a point in the usual way; it may be used later in the +outline, as was done above, relabelled, and so on, exactly like the tags +of the standard nodes. +@PP +Once a point has been tagged, a @I direction may be associated +with it, to inform @@Diag which way the outline or +link path is going at that point. The standard outlines have directions: +@ID { +@Code { +"@Ellipse { 3c @Wide 1c @High }" +} +||7ct +@Diag { +//0.5f +@ShowTags @ShowDirections @Ellipse { 3c @Wide 1c @High } +} +} +@Code CTR has no direction. If available, direction information +is used when placing labels, in the proximity step (by {@Code above}, for +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" +" }" +} +||7ct +@Diag { +//0.5f +@ShowTags @ShowDirections @Node + outline { + LR:: { xsize 0 } + LR:< 0d + UL:: { 0 ysize } + UL:< 270d + 0 0 LR UL 0 0 + } + { 2c @High 3c @Wide } +} +} +It is often helpful when creating outlines to check where the tagged +points and directions really are, by printing them out as is done +above. For this there is a @Code "@ShowTags" symbol whose result is +the following (arbitrary) object with its tagged points visible, and +a @Code "@ShowDirections" symbol which works similarly and shows the +directions. The diagram above was printed using +{@Code "@ShowTags @ShowDirections @Node ..."}. There is also a +@Code "@ShowPoints" symbol which is like @Code "@ShowTags" except +that it omits the tags, just placing circles on the points. +@PP +Link paths are similar to node outlines, created +using the @Code path option of @Code "@Link" instead of the +@Code outline option of {@Code "@Node"}. The major difference is that +links have no base, so @Code xsize and @Code ysize cannot be +used. Indeed, even @Code "0 0" does not have any useful +meaning inside a link path. +@PP +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" +" }" +} +||7ct +{ +//1.0c +@VContract @Diag { +3c @Wide 1c @High +// +@ShowTags @Link + path { + FROM:: from + TO:: to + FROM TO + } + from { 0,1 } + to { 1,0 } +} +} +} +This simple example creates two tagged points and joins them with +a straight line. If you want a link that can carry arrowheads, it is +best to ensure that it creates @Code FROM and @Code TO tags, with +directions pointing along the link from @Code FROM to @Code TO at +both points, since then the default values of the various arrow +options will do the rest. Similarly, if you want labels you need to +define {@Code LFROM}, {@Code LMID}, and {@Code LTO} labels, ideally +also with directions. +@PP +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" +" }" +"}" +} +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" +" }" +"}" +} +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, +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 }" +"}" +} +Such definitions are very useful if the combinations occur +frequently. Any options not mentioned have their usual default values, +and may be set in the usual way: +@ID @Code "@BigOctagon outlinestyle { dashed } ..." +Attempts to reset an already set option will elicit a warning message. +@End @Section diff --git a/doc/user/dia_erro b/doc/user/dia_erro new file mode 100644 index 0000000..2ad02d5 --- /dev/null +++ b/doc/user/dia_erro @@ -0,0 +1,45 @@ +@Section + @Tag { dia_erro } + @Title { Errors } +@Begin +@PP +Lout normally produces an output file that will print without mishap on +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 +is printed. +@PP +The most likely errors are {@I syntax @I errors}, as in +@Code "outline { 0 0 [ 0 xsize }" for example, in which a @Code "]" is +missing; @I { type errors }, as in @Code "SE:: 45d" where the +following object should have been a point; and @I { undefined errors }, +arising from labels misspelt or used before being defined. Less commonly, +the options may all be correct but the figure is too large in some way: too +many labels, too deeply nested, and so on. +@PP +When an error is detected, @@Diag arranges for the offending page to +be printed up to the point where the error occurred, with a message nearby +describing the error. Printing of the document is then aborted. It is +often quite easy to find the problem, because it lies in whatever should +have been printed next. +@PP +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 +@ID @Code { +"@Diag" +" save { yes }" +"..." +} +This causes the memory used by @@Diag to be reclaimed as soon +as the diagram is printed, rather than at the end of the current page +as is usual. However, if the diagram is nested inside some other +major Lout package, such as {@Code "@Graph"}, use of this option may +cause other PostScript errors. +@PP +If you see @Code "dictfull" in an error message, it means that you are +dictfull. @Index { @Code dictfull PostScript error } +using an old version of PostScript. Increasing the @Code "maxlabels" +option of @@Diag (Section {@NumberOf dia_summ}) might fix the problem. +@End @Section diff --git a/doc/user/dia_geom b/doc/user/dia_geom new file mode 100644 index 0000000..bfc9c02 --- /dev/null +++ b/doc/user/dia_geom @@ -0,0 +1,208 @@ +@Section + @Tag { dia_geom } + @Title { Expert usage: numbers, lengths, angles, and points } +@Begin +@PP +@@Diag has many options whose values contain lengths, angles, and +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 +arbitrarily complex algebraic expressions may be used to specify the +values. +@PP +The usual mathematical operations may be applied to numbers, angles, and +lengths: +@ID @Code "2.0f + 3.0f * sin { 30d }" +is a valid length. Since this is just ordinary algebra on real numbers, +the unsurprising details are deferred to the summary +(Section {@NumberOf dia_summ}). Grouping is always done with braces, +never parentheses. +@PP +More interesting are the geometrical symbols that @@Diag provides. The +most fundamental is not a symbol at all: two lengths side by side define +a point. For example, +@ID @Code "xsize ysize * 0.5" +within an outline is the point at the far right of the base, halfway +up. +@PP +There are @Code "++" and @Code "--" symbols for vector addition and +subtraction of two points, and @Code "**" for multiplication by a +scalar. For example, +@ID @Code "A@CTR ++ { 1.0f 0 }" +is the point @Code 1f to the right of {@Code "A@CTR"}. It is a good idea +to distinguish between @I { absolute points }, like {@Code "A@CTR"} +and @Code "0.5,1", which denote fixed positions on the page, and +@I { relative points }, like {@Code "1.0f 0"}, which serve as offsets +from absolute points. The difference of two absolute points is a relative +point; adding two absolute points gives an unpredictable result because +it depends on the origin of the coordinate system. However, the expression +@ID @Code "P1 ** x ++ P2 ** {1 - x}" +is safe for any two absolute points {@Code P1} and {@Code P2} and any +number {@Code x}; it produces a point on the line through the two +points. +@PP +These remarks on safety do not apply within the @Code outline option of +{@Code "@Node"}, because there the coordinate system is clearly +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 }" +} +||7ct +@Diag { +@ShowTags @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 } +} +} +But absolute sums like @Code "SB ++ HB" are not safe +in link paths and stray options like {@Code "alabelpos"}. +@PP +Sometimes it is useful to define tags +which are not wanted afterwards and are better forgotten. For +this there is the @Code ":=" symbol, which works in much the same +way as @Code "::" except that the tag is forgotten after the outline +or path option ends. The value assigned does not have to be a point, it +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" +in the outline above would produce {@Code 90d}. The @Code atangle symbol +finds the point at a given length and angle from the origin. For example, +@ID @Code "1.4142f atangle 45d" +is the point {@Code "1f 1f"}, and +@ID @Code "B@NE ++ 2f atangle 115d" +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" +" }" +} +||7ct +@Diag { ||2.5c +@Node + outline { + 0 0 + { 2c atangle 30d } + prev ++ { 2c atangle 90d } + prev ++ { 2c atangle 150d } + prev ++ { 2c atangle 210d } + prev ++ { 2c atangle 270d } + 0 0 + } +{ 4c @Wide 4c @High } +} +} +This example is rather naughty because the outline does not grow and +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}" +} +is the point at the top left-hand corner of the smallest rectangle +containing points {@Code P1} and {@Code P2}. And there is a +@Code distance symbol which produces the (non-negative) distance between +two points: +@ID @Code "CTR ++ { CTR distance NW } atangle { CTR angleto NW }" +equals {@Code NW}. +@PP +The rest of this section is concerned with how the `special virtue' +of the @Code from and @Code to options, their ability to accept a node +tag as well as a point, is implemented behind the scenes. A good +user-defined link should also have this virtue, because it is extremely +useful. +@PP +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" +} +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 +the node whose tag is given, at the given angle from the centre. +@PP +There is a second symbol with a similar adaptive ability, called +{@Code "??"}, which is defined to be @Code "@" whenever that would +make sense, and otherwise to produce the preceding object for its +result. For example, @Code "A??CTR" will equal @Code "A@CTR" if there +is such a thing; but +@ID @Code "{ xsize ysize*0.5 }??CTR" +will have result {@Code "{ xsize ysize*0.5 }"} since replacing +@Code "??" by @Code "@" does not produce anything sensible. +@PP +Now suppose we want a link path that connects @Code "from" and +@Code "to" by a straight line, where @Code "from" and @Code "to" may be +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" +"}" +} +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; +otherwise @Code "FROM" is just the point {@Code from}. The second +line defines point @Code TO similarly, and then the last two lines +join these two points. The @Code line standard link type is exactly +this plus a few additional tags and directions. +@End @Section diff --git a/doc/user/dia_intr b/doc/user/dia_intr new file mode 100644 index 0000000..52a9d49 --- /dev/null +++ b/doc/user/dia_intr @@ -0,0 +1,108 @@ +@Section + @Tag { dia_intr } + @Title { Introduction } +@Begin +@PP +To use the @@Diag symbol you first need to include its setup file. For +example, suppose you have an ordinary document with tables: +@ID @OneRow @Code { +"@SysInclude { tbl }" +"@SysInclude { doc }" +"@Doc @Text @Begin" +"..." +"@End @Text" +} +Change this to +@ID @OneRow @Code { +"@SysInclude { tbl }" +"@SysInclude { diag }" +"@SysInclude { doc }" +"@Doc @Text @Begin" +"..." +"@End @Text" +} +This provides everything you need for making diagrams. +@PP +The result of the @@Diag symbol is an object in the usual way. A diagram +is commonly made into a centred display, like this: +@ID @OneRow @Code { +"@CentredDisplay @Diag {" +" ..." +"}" +} +or into a floating figure, like this: +@ID @OneRow @Code { +"@Figure" +" @Caption { ... }" +"@Diag {" +" ..." +"}" +} +but it could be an entry in a table, a word in a paragraph, or anything +else. +@PP +Most uses of @@Diag contain a @I { nodes part } and a @I { links part }: +@ID @OneRow lines @Break { +@Code "@Diag {" + @I { nodes part } + @Code "//" + @I { links part } +@Code "}" +} +This reflects @@Diag's view of the world as consisting of {@I nodes} +(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 +simply serves to divide the two parts. +@PP +For example, here is a nodes part containing two nodes separated by +a @Code "@DP" symbol that (as usual) leaves some vertical space +between them: +@ID @OneRow @Tab + @Fmta { @Col 7c @Wide A ! @Col B } +{ +@Rowa + A { @Code { +"@Ellipse { Hello, world }" +"@DP" +"@Square @I x" +} } + B { @Diag { +@Ellipse { Hello, world } +@DP +@Square @I x +} } +} +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: +@ID @OneRow @Code { +"A:: @Ellipse { Hello, world }" +"@DP" +"B:: @Square @I x" +} +Then a link from @Code A to @Code B may be added to the links part: +@ID @OneRow @Tab + @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 }" +"}" +} } + B { @Diag { +A:: @Ellipse { Hello, world } +@DP +B:: @Square @I x +// +@Link from { A } to { B } +} } +} +Subsequent examples will often omit the enclosing {@Code "@Diag { }"}. +@End @Section diff --git a/doc/user/dia_labe b/doc/user/dia_labe new file mode 100644 index 0000000..c449367 --- /dev/null +++ b/doc/user/dia_labe @@ -0,0 +1,433 @@ +@Section + @Tag { dia_labe } + @Title { Labels } +@Begin +@PP +Diagrams often contain small @I labels adjacent to their nodes and links: +@CD @Diag + nodelabelformat { @I @Body } +{ +@Tab + @Fmta { @Col A ! @Col ! @Col ! @Col B ! @Col ! @Col ! @Col C } +{ +@Rowa + B { B:: @Circle alabel { b } } +@Rowa + A { A:: @Circle alabel { a } } +@Rowa + C { C:: @Circle dlabel { c } } +} +// +@Arrow from { A } to { B } ylabel { 10 } +@Arrow from { A } to { C } ylabel { 15 } +@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" } +{@Code clabel}, and {@Code dlabel}: +@ID { +@Code { +"@Ellipse" +" alabel { a }" +" blabel { b }" +" clabel { c }" +" dlabel { d }" +"{ Hello, world }" +} +||7ct +@VContract @Diag { +@Ellipse + alabel { a } + blabel { b } + clabel { c } + dlabel { d } +{ Hello, world } +} +} +Links also have labels, five in fact: +@ID { +@Code { +"@Link" +" fromlabel { f }" +" xlabel { x }" +" ylabel { y }" +" zlabel { z }" +" tolabel { t }" +} +||7ct +@VContract @Diag { +3c @Wide 1c @High +// +@Link + from { 0 0 } + to { 1,1 } + fromlabel { f } + xlabel { x } + ylabel { y } + zlabel { z } + tolabel { t } +} +} +The {@Code fromlabel} and {@Code tolabel} options are positioned directly +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 }" +} +||7ct +@VContract @Diag { +3c @Wide 1c @High +// +@Link + from { 0 0 } + to { 1,1 } + tolabel { @SolidArrowHead } +} +} +@Code "@SolidArrowHead" is a symbol available for use anywhere whose value +is an object in the shape of a small solid arrowhead. The arrowhead +options of Section {@NumberOf dia_link} work by setting {@Code fromlabel} +and {@Code tolabel} in exactly this way. Usually it is best to forget +about {@Code fromlabel} and {@Code tolabel}, and think of links as having +three labels: {@Code xlabel} near the start, {@Code ylabel} in the +middle, and {@Code zlabel} near the end. +@PP +Adding a label will not change the size of the diagram or the position +of any node, link, or other label. Although a label may be an arbitrary +object, it is treated as having zero size and will overstrike anything +that happens to be where it wants to go. +@PP +There are options for controlling the appearance and position of +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 +font and paragraph breaking style of the label: +@ID { +@Code { +"@Ellipse" +" alabel { a }" +" alabelfont { -2p }" +" alabelbreak { ragged nohyphen }" +"{ Hello, world }" +} +||7ct +@VContract @Diag { +@Ellipse + alabel { a } + alabelfont { -2p } + alabelbreak { ragged nohyphen } +{ Hello, world } +} +} +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 +for more radical changes in appearance: +@ID { +@Code { +"@Ellipse" +" alabel { a }" +" alabelformat { @Box @I @Body }" +"{ Hello, world }" +} +||7ct +@Diag { +//0.5c +@Ellipse + alabel { a } + alabelformat { @Box @I @Body } +{ Hello, world } +} +} +The value attached to the ellipse will be the value of {@Code alabelformat}, +with any @Code "@Body" symbol within it replaced by the value of the +{@Code alabel} option. This example produces boxed italic labels. +@PP +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 }" +} +||7ct +@Diag { +//0.5c +@Ellipse + nodelabelformat { @Box @I @Body } + alabel { a } + blabel { b } +{ Hello, world } +} +} +Links similarly have {@Code linklabelfont}, {@Code linklabelbreak}, and +{@Code linklabelformat} options which affect all the link labels +(except {@Code fromlabel} and {@Code tolabel}, since that would produce +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 }" +"}" +} +||7ct +@VContract @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 } +} +} +These settings specify that every node label will be set in italics, +two points smaller than the surrounding text, and that every link label +will appear between two @Code "/" characters, also two points smaller +because the default value of @Code "linklabelfont" still applies. Of +course, it remains open to any node or link to override these settings +by supplying its own label options. +@PP +The remaining five label options, {@Code alabelpos}, {@Code alabelangle}, +{@Code alabelprox}, {@Code alabelmargin}, {@Code alabelctr}, and +{@Code alabeladjust}, +affect the position of the label. Don't be daunted by the number of +options. As previous examples have shown, they all have sensible +default values and thus need to be set only rarely. +@PP +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 +are the default values for all nine labels: +@IL +@LI { +@Code { +"@Node" +" alabelpos { NE }" +" blabelpos { NW }" +" clabelpos { SW }" +" dlabelpos { SE }" +} +||7ct +@VContract @Diag { +//0.5f +@ShowTags @Ellipse { 3c @Wide 2c @High } +} +} +@LI { +@Code { +"@Link" +" fromlabelpos { FROM }" +" xlabelpos { LFROM }" +" ylabelpos { LMID }" +" zlabelpos { LTO }" +" tolabelpos { TO }" +} +||7ct +@VContract @Diag { +//1.0f +2c @Wide 2.2c @High +// +@ShowTags @Link + from { 0,0.7 } + to { 1,0 } + # tolabel { @SolidArrowHead } +} +} +@EL +Thus, by changing @Code clabelpos to @Code S you can move the position +of the @Code clabel label to beneath the node. You can do this for every +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 +far from the start of the link the @Code "LFROM" tag, and hence the +{@Code xlabel}, will appear. A similar option, @Code { zindent }, determines +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 }" +} +||7ct +@VContract @Diag { +//1f +2c @Wide 1.2c @High +// +@ShowTags @Link + xindent { 1f } + zindent { 2f } + from { 0,0.7 } + to { 1,0 } +} +} +Both options have default value {@Code 0.8f}. +@PP +The @Code alabelangle option determines the angle at which the label is +printed: +@ID @Tab + @Fmta { @Col @Code A ! @Col B } +{ +@Rowa + A { "alabelangle { horizontal }" } + B { Horizontal (the default) } +@Rowa + A { "alabelangle { aligned }" } + B { Aligned with the node outline or link path } +@Rowa + A { "alabelangle { perpendicular }" } + B { Perpendicular to the outline or link path } +} +The @Code "alabelprox" option determines where in the proximity of +@Code alabelpos the label is printed: +@ID @Tab + @Fmta { @Col @Code A ! @Col B } +{ +@Rowa + A { "alabelprox { above }" } + B { Above the node outline or link path (the default for link labels) } +@Rowa + A { "alabelprox { below }" } + B { Below the node outline or link path } +@Rowa + A { "alabelprox { left }" } + B { To the left of the node outline or link path } +@Rowa + A { "alabelprox { right }" } + B { To the right of the node outline or link path } +@Rowa + A { "alabelprox { inside }" } + B { Inside the node outline or on the left of the link path +going from @Code from to @Code to } +@Rowa + A { "alabelprox { outside }" } + B { Outside the node outline or on the right of the link path +going from @Code from to @Code to (the default for node labels) } +} +The {@Code alabelmargin} option adds a margin around all four sides of +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 }" +} +||7ct +@VContract @Diag { +@Ellipse + alabel { a } + alabelmargin { 0f } +{ Hello, world } +} +} +The default value is {@Code 0.2f}, and so there is scope for some +reduction as well as increase. +@PP +@@Diag takes careful account of the @Code alabelangle option, the +@Code alabelprox option, the direction that the node outline or link +path is heading, and which label it is, and places the label in a way +that looks good nearly always. When it doesn't, the remainder of this +section should help. +@PP +The @Code alabelangle option may be given an arbitrary angle, and then +the label will be printed at that angle. There are also the special +values @Code parallel and {@Code antiparallel}, which give the direction +that the node outline or link path is going at that point and its +opposite. These are the default values for @Code tolabelangle and +@Code fromlabelangle respectively, which explains why arrowheads point the +right way. The @Code aligned value above is one of these two angles, +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}: +@CD @Diag { +//1f +@ShowTags @Box margin { 0.5c } { 24p @Font grey @Colour @I label } +} +meaning that the indicated point of the label will coincide with +{@Code alabelpos}. These points lie on the outside of the margins +added by {@Code alabelmargin}. +@PP +The six values of @Code alabelprox given earlier (@Code { above }, +@Code { below }, etc.) all produce one of {@Code N}, {@Code S} etc. for +their ultimate result; which one they produce depends on the direction +the outline or link is going at that point. For example, @Code { above } +produces @Code { SE } when the outline or link is going from northeast +to southwest or vice versa, @Code { SW } when the outline or link is +going from northwest to southeast and vice versa, and @Code { S } when +it happens to be exactly horizontal. There is also a dependence +on which label it is: for example, if it is @Code "xlabel" and the +direction happens to be vertical, the result is {@Code "NW"}. +@PP +The preceding discussion is all under the assumption that the +@Code "alabelctr" option is {@Code no}. When it is {@Code "yes"}, +a small adjustment is made to the position of the label. The selected +corner or side midpoint of the label will no longer coincide with +{@Code alabelpos}, although it will still lie on the straight line passing +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 +@Code y label often looks better centred when this adjustment is made, +particularly on lines with shallow but non-zero slope: +@CD @Tab + @Fmta { @Col @CC A ! @Col ! @Col @CC B } +{ +@Rowa + A { @Code "ylabelctr { no }" } + B { @Code "ylabelctr { yes }" } +@Rowa +@Rowa +@Rowa + A { @Diag ylabelctr { no } { + A:: @Square //0.5c &3c B:: @Square + // + @Link from { A } to { B } ylabel { @I { ylabel } } + } } + B { @Diag ylabelctr { yes } { + A:: @Square //0.5c &3c B:: @Square + // + @Link from { A } to { B } ylabel { @I { ylabel } } + } } +} +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 +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 +above the point where it otherwise would have done. +@End @Section diff --git a/doc/user/dia_link b/doc/user/dia_link new file mode 100644 index 0000000..b71f9d5 --- /dev/null +++ b/doc/user/dia_link @@ -0,0 +1,261 @@ +@Section + @Tag { dia_link } + @Title { Links } +@Begin +@PP +@Code "@Diag" has one basic symbol for creating links, called +link. @Index { @Code "@Link" symbol from @Code "@Diag" } +{@Code "@Link"}. It draws a link between two points or nodes +given by {@Code from} and {@Code to} options, along a path +given by a {@Code path} option: +@ID @Code { +"@Link" +" path { ... }" +" from { ... }" +" to { ... }" +} +Unlike {@Code "@Node"}, {@Code "@Link"} has no following object. +@PP +The @Code "path" option may be used to produce a link of any shape, as +Section {@NumberOf dia_defi} explains. There are also values +that produce standard paths. These are listed in full in the summary +(Section {@NumberOf dia_summ}); here is a sample: +@ID @Tab + @Fmta { @Col @Code { path "{" A "}" } ! @Col ! @Col B } +{ + +@Rowa + A { line } + B { +@Diag { +A:: @Circle //1c ||2c B:: @Circle +// @Link from { A } to { B } path { line } arrow { yes } +} +} + +@Rowa + A { acurve } + B { +@Diag { +A:: @Circle //1c ||2c B:: @Circle +// @Link from { A } to { B } path { acurve } arrow { yes } +} +} + +@Rowa + A { ccurve } + B { +@Diag { +A:: @Circle //1c ||2c B:: @Circle +// @Link from { A } to { B } path { ccurve } arrow { yes } +} +} + +@Rowa + A { rvlcurve } + B { +@Diag { +A:: @Circle //1c ||2c B:: @Circle +// @Link from { A } to { B } path { rvlcurve } arrow { yes } +} +} + +} +The name of the last one is a reminder that it goes right, then vertically, +then left, with curved corners. The @Code acurve and @Code ccurve values +produce circular arcs, anticlockwise and clockwise respectively, lying on +the circle passing through the endpoints, or through the centres of the +endpoints when they are tags denoting nodes. There is also @Code "curve" +which is an abbreviation for {@Code "acurve"}. All these standard paths +are defined in a way that makes sense no matter where the two nodes are +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 +used to fine-tune the path. The @Code "bias" option determines the +maximum distance that a curve is permitted to stray: +@CD @Tab + @Fmta { @Col A ! @Col ! @Col B } +{ + +@Rowa + + A { @Diag vstrut { no } margin { 0.5c } { +A:: @Circle //1.5c ||2c B:: @Circle +// +LA:: @Line pathstyle { cdashed } from { A } to { B } +LB:: @Curve from { A } to { B } +@Line arrow { both } from { LA@LMID } to { LB@LMID } + ylabel { @I bias } # ylabeladjust { 0.15c 0 } +} } + + B { @Diag vstrut { no } margin { 0.5c } { +A:: @Circle //1.5c ||2c B:: @Circle +// +LA:: @RVLCurve from { A } to { B } +LB:: @Line pathstyle { cdashed } from { B@E } to { B@E ++ {0 2.5c} } +@Line arrow { both } from { LB@LMID } to { LA@LMID } + ylabel { @I bias } ylabeladjust { 0 0.05c } +} } + +} +The @Code radius option does @I not apply to @Code acurve and +{@Code ccurve}; rather, it determines the radius of the arcs at +the corners of @Code rvlcurve and its kin. A very large radius will be +reduced to the largest reasonable value, which provides a way to get +a semicircle at the right in an {@Code rvlcurve}. +@PP +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 }" +} +||7ct +@Diag vstrut { no } { +A:: @Circle &3c B:: @Circle +// +@Link path { ccurve } bias { 2c } from { A } to { B } +} +} +In such cases you have to arrange for the extra space yourself, by adding +an extra paragraph symbol, blank row or column in a table, or whatever. +@PP +As with the options of {@Code "@Node"}, the options of {@Code "@Link"} +may all be given to {@Code "@Diag"} as well, where they apply to every +link in the diagram, unless overridden in the usual way. They also appear +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} +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} +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 +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 } +arrowhead to the end of the link: +@ID { +@Code { +"@Link" +" arrow { yes }" +} +||7ct +@Diag { +1c @High 3c @Wide +// +@Link + from { 0,0 } + to { 1,1 } + arrow { yes } +} +} +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 }" +} +||7ct +@Diag { +1c @High 3c @Wide +// +@Link + from { 0,0 } + to { 1,1 } + arrow { both } +} +} +@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 +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 }" +"{" +" ..." +"}" +} +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" +and @Code "arrowlength" options may be any length; it may be necessary to +decrease @Code "arrowwidth" when many arrows enter one node. The full list +of possible values for @Code "arrowstyle" is +@ID @Tab + @Fmta { @Col @Code { "arrowstyle {" A "}" } ! @Col B } + vmargin { 1.0vx } +{ +@Rowa + A { solid } + B { @Diag vstrut { no } { A:: @Circle |2c B:: @Circle + // @Link from { A } to { B } arrow { yes } arrowstyle { solid } } } +@Rowa + A { halfopen } + B { @Diag vstrut { no } { A:: @Circle |2c B:: @Circle + // @Link from { A } to { B } arrow { yes } arrowstyle { halfopen } } } +@Rowa + A { open } + B { @Diag vstrut { no } { A:: @Circle |2c B:: @Circle + // @Link from { A } to { B } arrow { yes } arrowstyle { open } } } +@Rowa + A { curvedsolid } + B { @Diag vstrut { no } { A:: @Circle |2c B:: @Circle + // @Link from { A } to { B } arrow { yes } arrowstyle { curvedsolid } } } +@Rowa + A { curvedhalfopen } + B { @Diag vstrut { no } { A:: @Circle |2c B:: @Circle + // @Link from { A } to { B } arrow { yes } arrowstyle { curvedhalfopen } } } +@Rowa + A { curvedopen } + B { @Diag vstrut { no } { A:: @Circle |2c B:: @Circle + // @Link from { A } to { B } arrow { yes } arrowstyle { curvedopen } } } +@Rowa + A { circle } + B { @Diag vstrut { no } { A:: @Circle |2c B:: @Circle + // @Link from { A } to { B } arrow { yes } arrowstyle { circle } } } +@Rowa + A { box } + B { @Diag vstrut { no } { A:: @Circle |2c B:: @Circle + // @Link from { A } to { B } arrow { yes } arrowstyle { box } } } +} +The reader is invited to admire the beautifully sharp points on these +arrowheads. +@FootNote { +The outlines of all nodes and arrowheads are drawn on the inside of the +geometrical curve defining them, not centred over the curve as is common in +PostScript documents. Hence, the arrowheads and node outlines intersect at +a true geometrical point; they do not overlap by one line width. Furthermore, +the standard link paths terminate at the base of the arrowhead, not at +the point; the arrowhead itself is responsible for continuing the link +path, at the appropriate width (although never dashed or dotted), from its +base to its point, and hence can and does ensure that the link path does +not overstrike and thicken the point of the arrow. +} +@PP +It is 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"}, +{@Code "@RVLCurve"}, and so on. There are also symbols in which +the @Code "arrow" option is set to @Code yes in addition: {@Code "@Arrow"}, +{@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 +to get backward arrows and double-ended arrows. +@End @Section diff --git a/doc/user/dia_node b/doc/user/dia_node new file mode 100644 index 0000000..b72c6e2 --- /dev/null +++ b/doc/user/dia_node @@ -0,0 +1,512 @@ +@Section + @Tag { dia_node } + @Title { Nodes } +@Begin +@PP +@Code "@Diag" has one basic symbol for creating nodes. It is called +node. @Index { @Code "@Node" } +{@Code "@Node"}, and it takes the following object and encloses it in an +outline whose shape is determined by the {@Code "outline"} option: +@ID { +@Code { +"@Node" +" outline { curvebox }" +"{ Hello, world }" +} +||7ct +@Diag { +@Node + outline { curvebox } +{ Hello, world } +} +} +As Section {@NumberOf dia_defi} explains, the @Code outline option may be +used to produce an outline of any shape. There are also nine values that +produce standard shapes: {@Code box}, {@Code curvebox}, {@Code shadowbox}, +{@Code square}, {@Code diamond}, {@Code polygon}, {@Code isosceles}, +{@Code ellipse}, and {@Code circle}. +@PP +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 +example, this is how a circle is positioned over its base (shown in +grey): +@ID @OneRow { +@Code { +"@Node" +" outline { circle }" +"{ Hello, world }" +} +||7ct +@Diag { +@Box paint { lightgrey } outlinestyle { noline } margin { 0c } +@Node + outline { circle } +{ Hello, world } +} +} +Lout works only with the base, having no idea where the outline is, which +explains why this circle is too high for the space allowed +it. Section {@NumberOf dia_summ} shows how each of the standard +outlines is positioned over its base. +@PP +The @Code "@Node" symbol has many options, but all of them without +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" +"}" +} +||7ct +@Diag + outline { circle } +{ + @Node @I a + @DP + @Node @I b +} +} +These options also appear in the setup file ({@Code diag}); +if set there, they apply to every node in every diagram of the +document. As the number of nodes increases, it becomes very tedious and +error-prone to duplicate options at all the nodes. Giving each option +just once, at the @Code "@Diag" symbol or in the setup file, saves time +and makes it easy to change all the nodes into squares or any other shape +later on. Any setup file option may be overridden in a diagram by +giving the option to its @Code "@Diag" symbol; any @Code "@Diag" option +or setup file option may be overridden at any node by giving the option +again there. +@PP +To save time in simple cases, @Code "@Diag" provides nine other +node symbols called +{@Code "@Box"}, +box.fig @Index { @Code "@Box" in @Code "@Diag" } +{@Code "@CurveBox"}, +curvebox.fig @Index { @Code "@CurveBox" in @Code "@Diag" } +{@Code "@ShadowBox"}, +shadowbox.fig @Index { @Code "@ShadowBox" in @Code "@Diag" } +{@Code "@Square"}, +square. @Index @Code "@Square" +{@Code "@Diamond"}, +diamond. @Index @Code "@Diamond" +{@Code "@Polygon"}, +{@Code "@Isosceles"}, +isosceles. @Index @Code "@Isosceles" +{@Code "@Ellipse"}, +ellipse. @Index @Code "@Ellipse" +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 +in shadow boxes: +@ID { +@Code { +"@Node" +" outline { shadowbox }" +" shadow { 0.4f }" +"{ WARNING }" +} +||7ct +@Diag { +@Node + outline { shadowbox } + shadow { 0.4f } +{ WARNING } +} +} +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" +of sides, and an @Code angle option for rotating the outline: +@IL +@LI { +@Code { +"@Polygon" +" sides { 5 }" +} +||7ct +@Diag { +@Polygon + sides { 5 } +{ 1c @High 1c @Wide } +} +} + +@LI { +@Code { +"@Polygon" +" sides { 5 }" +" angle { 0d }" +} +||7ct +@Diag { +@Polygon + sides { 5 } + angle { 0d } +{ 1c @High 1c @Wide } +} +} +@EL +Setting @Code angle to @Code 0d causes the first vertex to be placed +directly underneath the centre, and as the angle increases, the +position of the first vertex rotates anticlockwise. The defaults are +3 sides and the angle that gives the polygon a +horizontal base (i.e. 180 degrees divided by the number of sides). Thus +the two cases with symmetry about a vertical axis are obtained by the +default angle and @Code "0d" respectively, which is convenient. The +{@Code "shadow"}, {@Code "sides"}, and {@Code "angle"} options may be +given to any node, and also to {@Code "@Diag"} and in the setup file, +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} +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 }" +} +||7ct +@Diag { +@CurveBox + outlinestyle { solid } + outlinedashlength { 0.2f } + outlinewidth { thin } +{ Hello, world } +} +} +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 } +{@Code cdashed}, {@Code dotted}, or {@Code noline}: +@ID @OneRow { +@Code { +"@CurveBox" +" outlinestyle { cdashed }" +"{ Hello, world }" +} +||7ct +@Diag { +@CurveBox + outlinestyle { cdashed } +{ Hello, world } +} +} +The @Code dashed option makes all dashes the same length, whereas +@Code cdashed halves the length of the first and last dash on each segment, +which usually looks better. The length of dashes is {@Code outlinedashlength}, +and the distance between dashes or dots is at most {@Code outlinedashlength}, +reduced to make the dashes or dots fit evenly. The @Code outlinewidth +option determines the width of the line, dashes, or dots, and may be +{@Code thin}, {@Code medium}, {@Code thick}, or any length. The values +used for {@Code thin}, {@Code medium}, and {@Code thick} are +{@Code 0.04f}, {@Code 0.08f}, and {@Code 0.12f}. +@PP +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 }" +} +||7ct +@Diag { +@CurveBox + outlinestyle { solid cdashed } +{ Hello, world } +} +} +If there are more segments than values, {@Code outlinestyle} cycles back +to the first value again; this is why a single value is applied to all +segments. Section {@NumberOf dia_summ} shows how each of the +standard shapes is divided into segments. +@PP +Nodes may be painted any of the colours listed in Section +{@NumberOf colour}, using the @Code "paint" option: +@ID @OneRow { +@Code { +"@Box" +" paint { grey }" +"@Diamond" +" outlinestyle { noline }" +" paint { white }" +"{ Hello, world }" +} +||7ct +@Diag { +@Box + paint { grey } +@Diamond + outlinestyle { noline } + paint { white } +{ Hello, world } +} +} +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. +@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 +boundaries, and finally the following object. +@PP +Each node symbol has +@Code "font" and @Code "break" options which may be used to +set the font and paragraph breaking style of the following object: +@ID @OneRow { +@Code { +"@Box" +" font { Helvetica Base }" +" break { clines }" +"{" +"WARNING" +"DANGEROUS" +"PENGUINS" +"}" +} +||7ct +@Diag { +@Box + font { Helvetica Base } + break { clines } +{ +WARNING +DANGEROUS +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 +radical changes to the appearance of the following object: +@ID @OneRow { +@Code { +"@Box" +" format {" +" {0.8 1.5} @Scale @S @Body" +" }" +"{" +"Dangerous Penguins" +"}" +} +||7ct +@Diag { +@Box + format { { 0.8 1.5 } @Scale @S @Body } +{ +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 }" +"{" +" ..." +"}" +} +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 +the following object: +@ID @OneRow { +@Code { +"@Box" +" margin { 0c }" +"{ Hello, world }" +} +||7ct +@Diag { +@Box + margin { 0c } +{ Hello, world } +} +} +These margins are included in the node's base (described above), so a +larger margin enlarges the base and hence the outline as well. The +default value of @Code margin is {@Code 0.6f} (six-tenths of the current +font size), and so the margin will automatically increase when the font size +does, for example in overhead transparencies. +@PP +The @Code margin option adds the same margin to all four sides. For +finer control, the @Code hmargin option determines the horizontal (left +and right) margins only, overriding {@Code margin}. Similarly, the +@Code vmargin option determines the vertical (top and foot) margins. There +are also {@Code leftmargin}, {@Code rightmargin}, +{@Code topmargin}, and {@Code footmargin} options which override +{@Code margin}, {@Code hmargin}, and {@Code vmargin}. +@PP +When nodes appear side by side, the {@Code valign} option is +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" +"}" +} +||7ct +@Diag + valign { foot } +{ +@Box font { 24p } Big +@Box font { 8p } Small +} +} +causes the feet of the boxes to be aligned. In this example it is +applied to all nodes at once, but of course it can be applied +to individual nodes as well. The value of {@Code valign} can be a +length, which means that the point of alignment is +to be that far down from the top of the base (including margins); or +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 +height for a node (not including margins): +@ID @OneRow { +@Code { +"@Diag" +" vsize { 2f }" +"{" +"@Box font { 24p } Big" +"@Box font { 8p } Small" +"}" +} +||7ct +@Diag + vsize { 2f } +{ +@Box font { 24p } Big +@Box font { 8p } Small +} +} +The font size used when calculating @Code vsize is not affected by +the value of any @Code font option. If the following object is too +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 +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" +"}" +} +||7ct +@Diag + vsize { 3f } + vindent { ctr } +{ +@Box vindent { top } Top +@Box Centre +@Box vindent { foot } Foot +} +} +The value may be {@Code top} for at the top, {@Code ctr} (the default +value) for in the centre, {@Code foot} for at the foot, or a length, +meaning that distance down from the top. These values are the same as +for the @Code valign option. +@PP +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" +"}" +} +||7ct +@Diag +{ +@Box Hole @Box in +@Box my @Box pocket +} +} +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" +"}" +} +||7ct +@Diag + vsize { 1f } +{ +@Box Hole @Box in +@Box my @Box pocket +} +} +The size @Code "1f" is a good choice because most fonts are designed to +be @Code "1f" high from the top of the tallest character to the foot of the +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: +@ID @OneRow { +@Code { +"@Diag" +" vstrut { yes }" +"{" +"@Box Hole @Box in" +"@Box my @Box pocket" +"}" +} +||7ct +@Diag + vstrut { yes } +{ +@Box Hole @Box in +@Box my @Box pocket +} +} +The @Code vstrut option may be {@Code yes}, {@Code no} (the default value), or +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} +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 +{@Code top} and {@Code foot}. The best way to fix horizontal size +discrepancies is with {@Code hsize}, not {@Code hstrut}. +@End @Section diff --git a/doc/user/dia_posi b/doc/user/dia_posi new file mode 100644 index 0000000..727d3be --- /dev/null +++ b/doc/user/dia_posi @@ -0,0 +1,224 @@ +@Section + @Tag { dia_posi } + @Title { Positioning } +@Begin +@PP +Once the nodes of the diagram are in place, @@Diag can be trusted to look +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 +the nodes. This is partly because `what pleases the eye' is the +positioning rule in many diagrams, and an interactive system is really +needed in such cases; and partly because, even when the rule is more formal +(for example, when the nodes are to be laid out in a grid), @@Diag does not +have symbols to produce it anyway. +@PP +Previous examples have used @Code "@DP" for getting nodes one under +another, and white space between nodes for getting them side by side, but +this is very primitive. This section suggests three better ways: using +{@Code "@Tbl"}, using {@Code "@Graph"}, and using coordinates; and the +following section adds a fourth, using @@Diag's tree-drawing symbols. It's +a bit of a jumble. +@PP +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 }" +"}" +} +||9ct +@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 } +} +} +The table occupies the nodes part. Tags may have the same name +as columns; the two can never conflict. +@PP +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 }" +"}" +} +||8.5ct +@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 } +} +} +Once again the @Code "@Graph" symbol occupies the nodes part. You can +get rid of the axes by setting the @Code "style" option of @Code "@Graph" +to {@Code none}, and then it won't look like a graph at all. +@PP +@@Diag has a system of node positioning based on coordinates which is +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" +" //" +" ..." +"}" +} +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 +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 +@Code "0.5,0.5" denotes the centre of the base. Coordinates should +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 +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 }" +"}" +} +||9ct +@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 } +} +} +A box with margin zero has been drawn around the empty space to +show its extent. The value of @Code "translate" should always +be {@I point} @Code to {@I point}; the first point lies within +the node, the second lies within the nodes part, and the translation +makes these two points coincide. +@PP +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 }" +"}" +} +||9ct +@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 } +} +} +This uses the tags of a phantom polygon to position the +real nodes. It would be a rare interactive system that could +position nodes with this precision; @@Diag shines whenever there +is a formal positioning rule to follow. +@End @Section diff --git a/doc/user/dia_summ b/doc/user/dia_summ new file mode 100644 index 0000000..b9dc9e9 --- /dev/null +++ b/doc/user/dia_summ @@ -0,0 +1,1680 @@ +@Section + @Tag { dia_summ } + @Title { Summary } +@Begin +@PP +Here is the complete list of standard node outlines that may be given +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 }"}), +tags, and directions (shown as a thick arrowhead wherever defined): +@IndentedList gap { 3v } + +@LI { +@Code { +"@Node" +" outline { box }" +} +||7ct +@Diag { +//0.5f +@Box paint { lightgrey } outlinestyle { noline } margin { 0c } +@ShowTags @ShowDirections @Node + outline { box } + outlinestyle { solid dashed } + outlinewidth { 0.03f } + vsize { 1.0c } hsize { 2.0c } +} +} + +@LI { +@Code { +"@Node" +" outline { curvebox }" +} +||7ct +@Diag { +@Box paint { lightgrey } outlinestyle { noline } margin { 0c } +@ShowTags @ShowDirections @Node + outline { curvebox } + outlinestyle { solid dashed } + outlinewidth { 0.03f } + vsize { 1.0c } hsize { 2.0c } +} +} + +@LI { +@Code { +"@Node" +" outline { shadowbox }" +" shadow { 0.4f }" +} +||7ct +@Diag { +@Box paint { lightgrey } outlinestyle { noline } margin { 0c } +@ShowTags @ShowDirections @Node + outline { shadowbox } + outlinestyle { solid dashed } + outlinewidth { 0.03f } + vsize { 1.0c } hsize { 2.0c } +} +} + +@LI { +@Code { +"@Node" +" outline { square }" +} +||7ct +@Diag { +//1.5f +@Box paint { lightgrey } outlinestyle { noline } margin { 0c } +@ShowTags @ShowDirections @Node + outline { square } + outlinestyle { solid dashed } + outlinewidth { 0.03f } + vsize { 1.0c } hsize { 2.0c } +} +} + +@LI { +@Code { +"@Node" +" outline { diamond }" +} +||7ct +@Diag { +@Box paint { lightgrey } outlinestyle { noline } margin { 0c } +@ShowTags @ShowDirections @Node + outline { diamond } + outlinestyle { solid dashed } + outlinewidth { 0.03f } + vsize { 1.0c } hsize { 2.0c } +} +} + +@LI { +@Code { +"@Node" +" outline { polygon }" +" sides { 3 }" +" angle { 180d / sides }" +} +||7ct +@Diag { +//0.5f +@Box paint { lightgrey } outlinestyle { noline } margin { 0c } +@ShowTags @ShowDirections @Node + outline { polygon } + outlinestyle { solid dashed } + outlinewidth { 0.03f } + vsize { 1.0c } hsize { 2.0c } +&0.5c ... &0.5c +@Box paint { lightgrey } outlinestyle { noline } margin { 0c } +@ShowTags @ShowDirections @Node + outline { polygon } + sides { 10 } + outlinestyle { solid dashed } + outlinewidth { 0.03f } + vsize { 1.0c } hsize { 2.0c } +&0.5c ... +} +} + +@LI { +@Code { +"@Node" +" outline { isosceles }" +} +||7ct +@Diag { +@Box paint { lightgrey } outlinestyle { noline } margin { 0c } +@ShowTags @ShowDirections @Node + outline { isosceles } + outlinestyle { solid dashed } + outlinewidth { 0.03f } + vsize { 1.0c } hsize { 2.0c } +} +} + +@LI { +@Code { +"@Node" +" outline { ellipse }" +} +||7ct +@Diag { +@Box paint { lightgrey } outlinestyle { noline } margin { 0c } +@ShowTags @ShowDirections @Node + outline { ellipse } + outlinestyle { solid dashed } + outlinewidth { 0.03f } + vsize { 1.0c } hsize { 2.0c } +} +} + +@LI { +@Code { +"@Node" +" outline { circle }" +} +||7ct +@Diag { +@Box paint { lightgrey } outlinestyle { noline } margin { 0c } +@ShowTags @ShowDirections @Node + outline { circle } + outlinestyle { solid dashed } + outlinewidth { 0.03f } + vsize { 1.0c } hsize { 2.0c } +} +} + +@EndList +@DP +Here are the abbreviations for the standard shapes: +@ID @Tab + vmargin { 0.5vx } + @Fmta { @Col @Code { outline "{" A "}" } ! @Col @Code { "@"B } } +{ +@Rowa + A { box } + B { Box } +@Rowa + A { curvebox } + B { CurveBox } +@Rowa + A { shadowbox } + B { ShadowBox } +@Rowa + A { square } + B { Square } +@Rowa + A { diamond } + B { Diamond } +@Rowa + A { polygon } + B { Polygon } +@Rowa + A { isosceles } + B { Isosceles } +@Rowa + A { ellipse } + B { Ellipse } +@Rowa + A { circle } + B { Circle } +} +Here are all the options to the @Code "@Node" symbol, their default +values, and their ranges of allowed values. Definitions of {@I number}, +{@I length}, {@I angle}, and {@I point} appear later in this summary. The +options related to {@Code alabel}, {@Code blabel}, {@Code clabel}, and +{@Code dlabel} have mostly been omitted since they are the same as +the {@Code nodelabel} options except for {@Code nodelabelpos}. +@DP +1fx @Break @Tab + hmargin { 1s } + # vmargin { 0.6vx } + @Fmth { @Col @Code A ! @Col @Code " " ! @Col @Code B ! @Col @Code " " ! + @Col 1.0c @Wide ! @Col C } + @Fmta { @Col @Code A ! @Col @Code "{" ! @Col @Code B ! @Col @Code "}" ! + @Col 1.0c @Wide ! @Col C } +{ +@FirstRowh + A { "@Node" } +@Rowa + A { " outline" } + B { box } + C { {@Code box}, {@Code curvebox}, {@Code shadowbox}, {@Code square}, +{@Code diamond}, {@Code polygon}, {@Code ellipse}, {@Code circle}, or +any outline } +@Rowa + A { " margin" } + B { 0.6f } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " shadow" } + B { 0.4f } + C { any @I length } +@Rowa + A { " sides" } + B { 3 } + C { any @I number (it will be rounded to the nearest integer) } +@Rowa + A { " angle" } + B { 180d "/" sides } + C { any @I angle } +@Rowa + A { " translate" } + B { } + C { empty, or @I point @Code to @I point } +@Rowa + A { " outlinestyle" } + B { solid } + C { {@Code solid}, {@Code dashed}, {@Code cdashed}, {@Code dotted}, +{@Code noline}, or any sequence of one or more of these values } +@Rowa + A { " outlinedashlength"} + B { 0.2f } + C { any @I length } +@Rowa + A { " outlinewidth" } + B { thin } + 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} } +@Rowa + A { " font" } + B { } + C { any value suitable for the @Code "@Font" symbol } +@Rowa + A { " break" } + B { } + C { any value suitable for the @Code "@Break" symbol } +@Rowa + A { " format" } + B { "@Body" } + C { any object, usually containing {@Code "@Body"} } +@Rowa + A { " valign"} + B { ctr } + C { {@Code "top"}, {@Code "ctr"}, {@Code "foot"}, or any length +from Section {@NumberOf objects} } +@Rowa + A { " vsize"} + B { } + C { empty, or any length from Section {@NumberOf objects} } +@Rowa + A { " vindent"} + B { ctr } + C { {@Code "top"}, {@Code "ctr"}, {@Code "mctr"}, {@Code "foot"}, or any +length from Section {@NumberOf objects} } +@Rowa + A { " vstrut"} + B { no } + C { {@Code no}, {@Code yes}, or any length from Section {@NumberOf objects} } +@Rowa + A { " vmargin" } + B { margin } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " topmargin" } + B { vmargin } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " footmargin" } + B { vmargin } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " halign"} + B { ctr } + C { {@Code "left"}, {@Code "ctr"}, {@Code "right"}, or any length from Section {@NumberOf objects} } +@Rowa + A { " hsize"} + B { } + C { empty, or any length from Section {@NumberOf objects} } +@Rowa + A { " hindent"} + B { ctr } + C { {@Code "left"}, {@Code "ctr"}, {@Code "mctr"}, {@Code "right"}, or any +length from Section {@NumberOf objects} } +@Rowa + A { " hmargin" } + B { margin } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " leftmargin" } + B { hmargin } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " rightmargin" } + 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 } +@Rowa + A { " nodelabelmargin"} + B { 0.2f } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " nodelabelfont"} + B { -2p } + C { any value suitable for the @Code "@Font" symbol } +@Rowa + A { " nodelabelbreak"} + B { ragged nohyphen } + C { any value suitable for the @Code "@Break" symbol } +@Rowa + A { " nodelabelformat"} + B { "@Body" } + C { any object, usually containing @Code "@Body" } +@Rowa + A { " nodelabelpos"} + B { } + C { any @I point } +@Rowa + A { " nodelabelangle"} + B { horizontal } + C { {@Code horizontal}, {@Code aligned}, or {@Code perpendicular}; +{@Code parallel}, {@Code antiparallel}, or any @I angle } +@Rowa + A { " nodelabelprox"} + 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} +} +@Rowa + A { " nodelabelctr"} + B { no } + C { @Code yes or @Code no } +@Rowa + A { " nodelabeladjust"} + B { 0 0 } + C { any @I point } +@Rowa + A { " alabelpos"} + B { NE } + C { any @I point } +@Rowa + A { " blabelpos"} + B { NW } + C { any @I point } +@Rowa + A { " clabelpos"} + B { SW } + C { any @I point } +@Rowa + A { " dlabelpos"} + B { SE } + C { any @I point } +} +@DP +Here is the complete list of standard link paths that may be given +to the @Code "@Link" symbol. Each entry shows the link path name, +any extra options relevant to this path, segments (shown using +{@Code "outlinestyle { solid dashed }"}, and tags. All tags +have directions pointing along the link from @Code FROM to +{@Code TO}; these have been omitted for clarity. The @Code frompt +and @Code topt options of @Code bezier are compulsory and denote the +two control points (Section {@NumberOf dia_defi}). +@IndentedList gap { 2v } + +@LI { +@Code { +"@Link" +" path { line }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { line } from { A } to { B } +} +&2.5c +#@Diag { +#|1.5c B:: @Circle /0.8c A:: @Circle +#// +#@ShowTags @Link +# pathstyle { solid dashed } +# path { line } from { A } to { B } +#} +} + +@LI { +@Code { +"@Link" +" path { doubleline }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { doubleline } from { A } to { B } +} +&2.5c +#@Diag { +#|1.5c B:: @Circle /0.8c A:: @Circle +#// +#@ShowTags @Link +# pathstyle { solid dashed } +# path { line } from { A } to { B } +#} +} + +@LI { +@Code { +"@Link" +" path { curve }" +" bias { 2.0f }" +} +||6ct +@Diag { +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { curve } from { A } to { B } +} +&2.5c +@Diag { +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { curve } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { ccurve }" +" bias { 2.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { ccurve } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { ccurve } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { bezier }" +" frompt { A@CTR ++ { 3f 0 } }" +" topt { B@CTR ++ { 3f 0 } }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { bezier } from { A } to { B } + frompt { A@CTR ++ { 3f 0 } } + topt { B@CTR ++ { 3f 0 } } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { bezier } from { A } to { B } + frompt { A@CTR ++ { 3f 0 } } + topt { B@CTR ++ { 3f 0 } } +} +} + +@LI { +@Code { +"@Link" +" path { vhline }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { vhline } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { vhline } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { hvline }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { hvline } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { hvline } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { vhcurve }" +" radius { 1.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { vhcurve } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { vhcurve } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { hvcurve }" +" radius { 1.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { hvcurve } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { hvcurve } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { lvrline }" +" bias { 2.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { lvrline } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { lvrline } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { rvlline }" +" bias { 2.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { rvlline } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { rvlline } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { lvrcurve }" +" bias { 2.0f }" +" radius { 1.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { lvrcurve } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { lvrcurve } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { rvlcurve }" +" bias { 2.0f }" +" radius { 1.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { rvlcurve } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { rvlcurve } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { dwrapline }" +" tbias { 2.0f }" +" bias { 2.0f }" +" fbias { 2.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle /2f +// +@ShowTags @Link + pathstyle { solid dashed } + path { dwrapline } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle /2f +// +@ShowTags @Link + pathstyle { solid dashed } + path { dwrapline } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { uwrapline }" +" tbias { 2.0f }" +" bias { 2.0f }" +" fbias { 2.0f }" +} +||6ct +@Diag { +//0.5f +/2f A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { uwrapline } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +/2f |1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { uwrapline } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { dwrapcurve }" +" tbias { 2.0f }" +" bias { 2.0f }" +" fbias { 2.0f }" +" radius { 1.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle /2f +// +@ShowTags @Link + pathstyle { solid dashed } + path { dwrapcurve } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle /2f +// +@ShowTags @Link + pathstyle { solid dashed } + path { dwrapcurve } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { uwrapcurve }" +" tbias { 2.0f }" +" bias { 2.0f }" +" fbias { 2.0f }" +" radius { 1.0f }" +} +||6ct +@Diag { +//0.5f +/2f A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { uwrapcurve } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +/2f |1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { uwrapcurve } from { A } to { B } +} +} + +@EndList +Here is the list of abbreviations for the standard paths (note +that @Code curve and @Code acurve are the same). Each +path also has an abbreviation which adds a forward arrow: +@ID @Tab + @Fmta { @Col @Code { path "{" A "}" } ! @Col @Code "@"B ! @Col @Code "@"C } +{ +@Rowa + A { line } + B { Line } + C { Arrow } +@Rowa + A { doubleline } + B { DoubleLine } + C { DoubleArrow } +@Rowa + A { curve } + B { Curve } + C { CurveArrow } +@Rowa + A { acurve } + B { ACurve } + C { ACurveArrow } +@Rowa + A { ccurve } + B { CCurve } + C { CCurveArrow } + +@Rowa + A { bezier } + B { Bezier } + C { BezierArrow } + +@Rowa + A { hvline } + B { HVLine } + C { HVArrow } +@Rowa + A { vhline } + B { VHLine } + C { VHArrow } +@Rowa + A { hvcurve } + B { HVCurve } + C { HVCurveArrow } +@Rowa + A { vhcurve } + B { VHCurve } + C { VHCurveArrow } + +@Rowa + A { lvrline } + B { LVRLine } + C { LVRArrow } +@Rowa + A { rvlline } + B { RVLLine } + C { RVLArrow } +@Rowa + A { lvrcurve } + B { LVRCurve } + C { LVRCurveArrow } +@Rowa + A { rvlcurve } + B { RVLCurve } + C { RVLCurveArrow } + +@Rowa + A { dwrapline } + B { DWrapLine } + C { DWrapArrow } +@Rowa + A { uwrapline } + B { UWrapLine } + C { UWrapArrow } +@Rowa + A { dwrapcurve } + B { DWrapCurve } + C { DWrapCurveArrow } +@Rowa + A { uwrapcurve } + B { UWrapCurve } + C { UWrapCurveArrow } +} +Here is the complete list of options to the @Code "@Link" symbol. The +options related to {@Code xlabel}, {@Code ylabel}, and {@Code zlabel} +have been omitted where they are the same as the {@Code linklabel} options. +@DP +1fx @Break @Tab + hmargin { 1s } + # vmargin { 0.6vx } + @Fmth { @Col @Code A ! @Col @Code " " ! @Col @Code B ! @Col @Code " " ! + @Col 1.0c @Wide ! @Col C } + @Fmta { @Col @Code A ! @Col @Code "{" ! @Col @Code B ! @Col @Code "}" ! + @Col 1.0c @Wide ! @Col C } +{ +@Rowh + A { "@Link" } +@Rowa + A { " path" } + B { line } + C { {@Code "line"}, {@Code "doubleline"}, {@Code "curve"}, {@Code "acurve"}, +{@Code "ccurve"}, {@Code "bezier"}, +{@Code "vhline"}, {@Code "hvline"}, {@Code "vhcurve"}, {@Code "hvcurve"}, +{@Code "lvrline"}, {@Code "rvlline"}, {@Code "lvrcurve"}, {@Code "rvlcurve"}, +{@Code "dwrapline"}, {@Code "uwrapline"}, {@Code "dwrapcurve"}, +{@Code "uwrapcurve"}, or any path } +@Rowa + A { " from"} + B { 0,0 } + C { any @I point or node label } +@Rowa + A { " to"} + B { 1,1 } + C { any @I point or node label } +@Rowa + A { " bias"} + B { 2.0f } + C { any @I length } +@Rowa + A { " fbias"} + B { 2.0f } + C { any @I length } +@Rowa + A { " tbias"} + B { 2.0f } + C { any @I length } +@Rowa + A { " radius"} + B { 1.0f } + C { any @I length } +@Rowa + A { " xindent"} + B { 0.8f } + C { any @I length } +@Rowa + A { " zindent"} + B { 0.8f } + C { any @I length } +@Rowa + A { " frompt"} + B { 0 0 } + C { any @I point } +@Rowa + A { " topt"} + B { 0 0 } + C { any @I point } +@Rowa + A { " pathstyle" } + B { solid } + C { {@Code solid}, {@Code dashed}, {@Code cdashed}, {@Code dotted}, +{@Code noline}, or any sequence of one or more of these values } +@Rowa + A { " pathdashlength"} + B { 0.2f } + C { any @I length } +@Rowa + A { " pathwidth" } + B { thin } + C { {@Code thin}, {@Code medium}, {@Code thick}, or any @I length } +@Rowa + A { " pathgap" } + B { thin } + C { {@Code thin}, {@Code medium}, {@Code thick}, or any @I length } +@Rowa + A { " arrow"} + B { no } + C { {@Code no}, {@Code yes}, {@Code forward}, {@Code back}, +or {@Code both} } +@Rowa + A { " arrowstyle"} + B { solid } + C { {@Code solid}, {@Code halfopen}, {@Code open}, {@Code curvedsolid}, +{@Code curvedhalfopen}, or {@Code curvedopen} } +@Rowa + A { " arrowwidth"} + B { 0.3f } + C { any @I length } +@Rowa + A { " arrowlength"} + B { 0.5f } + C { any @I length } +@Rowa + A { " linklabel"} + B { } + C { any object } +@Rowa + A { " linklabelmargin"} + B { 0.2f } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " linklabelfont"} + B { -2p } + C { any value suitable for the @Code "@Font" symbol } +@Rowa + A { " linklabelbreak"} + B { ragged nohyphen } + C { any value suitable for the @Code "@Break" symbol } +@Rowa + A { " linklabelformat"} + B { "@Body" } + C { any object, usually containing @Code "@Body" } +@Rowa + A { " linklabelpos"} + B { } + C { any @I point } +@Rowa + A { " linklabelangle"} + B { horizontal } + C { {@Code horizontal}, {@Code aligned}, or {@Code perpendicular}; +{@Code parallel}, {@Code antiparallel}, or any @I angle } +@Rowa + A { " linklabelprox"} + 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} +} +@Rowa + A { " linklabelctr"} + B { no } + C { @Code yes or @Code no } +@Rowa + A { " linklabeladjust"} + B { 0 0 } + C { any @I point } +@Rowa + A { " xlabelpos"} + B { LFROM } + C { any @I point } +@Rowa + A { " ylabelpos"} + B { LMID } + C { any @I point } +@Rowa + A { " ylabelctr"} + B { yes } + C { @Code yes or @Code no } +@Rowa + A { " zlabelpos"} + B { LTO } + C { any @I point } +@Rowa + A { " fromlabel"} + B { } + C { any object } +@Rowa + A { " fromlabelmargin"} + B { 0f } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " fromlabelfont"} + B { } + C { Any value suitable for the @Code "@Font" symbol } +@Rowa + A { " fromlabelbreak"} + B { ragged nohyphen } + C { Any value suitable for the @Code "@Break" symbol } +@Rowa + A { " fromlabelformat"} + B { "@Body" } + C { any object, usually containing @Code "@Body" } +@Rowa + A { " fromlabelpos"} + B { FROM } + C { any @I point } +@Rowa + A { " fromlabelangle"} + B { antiparallel } + C { {@Code horizontal}, {@Code aligned}, or {@Code perpendicular}; +{@Code parallel}, {@Code antiparallel}, or any @I angle } +@Rowa + A { " fromlabelprox"} + 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} +} +@Rowa + A { " fromlabelctr"} + B { no } + C { @Code yes or @Code no } +@Rowa + A { " fromlabeladjust"} + B { 0 0 } + C { any @I point } +@Rowa + A { " tolabel"} + B { } + C { any object } +@Rowa + A { " tolabelmargin"} + B { 0f } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " tolabelfont"} + B { } + C { Any value suitable for the @Code "@Font" symbol } +@Rowa + A { " tolabelbreak"} + B { ragged nohyphen } + C { Any value suitable for the @Code "@Break" symbol } +@Rowa + A { " tolabelformat"} + B { "@Body" } + C { any object, usually containing @Code "@Body" } +@Rowa + A { " tolabelpos"} + B { TO } + C { any @I point } +@Rowa + A { " tolabelangle"} + B { parallel } + C { {@Code horizontal}, {@Code aligned}, or {@Code perpendicular}; +{@Code parallel}, {@Code antiparallel}, or any @I angle } +@Rowa + A { " tolabelprox"} + 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} +} +@Rowa + A { " tolabelctr"} + B { no } + C { @Code yes or @Code no } +@Rowa + A { " tolabeladjust"} + B { 0 0 } + C { any @I point } +} +@DP +Here is the complete list of options to the @Code "@Tree" symbol: +@DP @OneRow 1fx @Break @Tab + hmargin { 1s } + # vmargin { 0.6vx } + @Fmth { @Col @Code A ! @Col @Code " " ! @Col @Code B ! @Col @Code " " ! + @Col 1.0c @Wide ! @Col C } + @Fmta { @Col @Code A ! @Col @Code "{" ! @Col @Code B ! @Col @Code "}" ! + @Col 1.0c @Wide ! @Col C } +{ +@Rowh + A { "@Tree" } +@Rowa + A { " treehindent" } + B { ctr } + C { {@Code left}, {@Code ctr}, {@Code right}, or any length from +Section {@NumberOf objects} } +} +@DP +The @Code "@HTree" option has a similar @Code "treevindent" option, +which may be {@Code "top"}, {@Code ctr}, {@Code foot}, or any length +from Section {@NumberOf objects}. +@PP +The @Code "@Diag" symbol and to the {@Code "@DiagSetup"} setup +file symbol have all of the options of {@Code "@Node"}, {@Code "@Link"}, +{@Code "@Tree"}, and {@Code "@HTree"}. They also have the following +options: +@DP +1fx @Break @Tab + hmargin { 1s } + # vmargin { 0.6vx } + @Fmth { @Col @Code A ! @Col @Code " " ! @Col @Code B ! @Col @Code " " ! + @Col 1.0c @Wide ! @Col C } + @Fmta { @Col @Code A ! @Col @Code "{" ! @Col @Code B ! @Col @Code "}" ! + @Col 1.0c @Wide ! @Col C } +{ +@Rowh + A { "@Diag" } +@Rowa + A { " maxlabels" } + B { 200 } + C { any whole number } +@Rowa + A { " save" } + B { no } + C { @Code no or @Code yes } +@Rowa + A { " treehsep" } + B { 0.5f } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " treevsep" } + B { 0.5f } + C { any length from Section {@NumberOf objects} } +} +@DP +The following lists define all the ways to specify numbers, lengths, +angles, points, and booleans. Brief explanations appear to the right, +with the symbols' precedences in parentheses. +@DP +1fx @Break @Tab + # vmargin { 0.6vx } + @Fmth { @Col { &@DisplayIndent A } ! @Col } + @Fmta { @Col { &@DisplayIndent &2s A } ! @Col B } +{ + +@Rowh A { @I number } vmargin { 0.2vx } +@Rowh +@Rowa + A { {@Sym minus}27.56 } + B { or any literal number } +@Rowa + A { @Code sqrt @I number } + B { square root (99) } +@Rowa + A { @Code abs @I number } + B { absolute value (99) } +@Rowa + A { @Code ceiling @I number } + B { least integer greater than or equal to (99) } +@Rowa + A { @Code floor @I number } + B { greatest integer less than or equal to (99) } +@Rowa + A { @Code truncate @I number } + B { delete fractional part (99) } +@Rowa + A { @Code round @I number } + B { round to nearest integer (99) } +@Rowa + A { @Code sin @I angle } + B { sine of angle measured in degrees (99) } +@Rowa + A { @Code cos @I angle } + B { cosine of angle measured in degrees (99) } +@Rowa + A { @I number @Code atan @I number } + B { arc tangent of first over second (98) } +@Rowa + A { @I number @Code exp @I number } + B { first number raised to second number (98) } +@Rowa + A { @I number @Code log @I number } + B { logarithm of second number to base first (98) } +@Rowa + A { @I number @Code rand @I number } + B { random real number in this range inclusive (98) } +@Rowa + A { @I number @Code max @I number } + B { the larger of two numbers (98) } +@Rowa + A { @I number @Code min @I number } + B { the smaller of two numbers (98) } +@Rowa + A { @I number @Code "*" @I number } + B { the product of two numbers (97) } +@Rowa + A { @I number @Code "/" @I number } + B { real-valued division (96, left associative) } +@Rowa + A { @I length @Code "/" @I length } + B { the ratio of two lengths (96, left associative) } +@Rowa + A { @I angle @Code "/" @I angle } + B { the ratio of two angles (96, left associative) } +@Rowa + A { @I number @Code idiv @I number } + B { integer division of two numbers (96, left associative) } +@Rowa + A { @I number @Code mod @I number } + B { integer remainder when first divided by second (96) } +@Rowa + A { @I number @Code "+" @I number } + B { sum of two numbers (96, left associative) } +@Rowa + A { @Code "+" @I number } + B { identity operation (96) } +@Rowa + A { @I number @Sym minus @I number } + B { difference of two numbers (96, left associative) } +@Rowa + A { @Sym minus @I number } + B { negation (96) } +@Rowa + A { @Code sides } + B { ({@Code outline} only) value of the node's @Code sides option } + +@Rowh +@Rowh +@Rowh +@Rowh +@Rowh A { @I length } vmargin { 0.2vx } +@Rowh +@Rowa + A { 0 } + B { zero } +@Rowa + A { @Code xsize } + B { ({@Code outline} only) distance to right boundary } +@Rowa + A { @Code ysize } + B { ({@Code outline} only) distance to top boundary } +@Rowa + A { @Code xmark } + B { ({@Code outline} only) distance to column mark } +@Rowa + A { @Code ymark } + B { ({@Code outline} only) distance to row mark } +@Rowa + A { @Code margin } + B { ({@Code outline} only) value of the node's @Code margin option } +@Rowa + A { @Code shadow } + B { ({@Code outline} only) value of the node's @Code shadow option } +@Rowa + A { @I number @Code i } + B { @I number inches (100) } +@Rowa + A { @I number @Code c } + B { @I number centimetres (100) } +@Rowa + A { @I number @Code p } + B { @I number points (100) } +@Rowa + A { @I number @Code m } + B { @I number ems (100) } +@Rowa + A { @I number @Code s } + B { @Code 1s is the current width of a space (100) } +@Rowa + A { @I number @Code v } + B { @Code 1v is the current inter-line space (100) } +@Rowa + A { @I number @Code f } + B { @Code 1f is the size of the current font (100) } +@Rowa + A { @Code "xcoord" @I point } + B { the @I x coordinate of the point (99) } +@Rowa + A { @Code "ycoord" @I point } + B { the @I y coordinate of the point (99) } +@Rowa + A { @Code abs @I length } + B { absolute value (99) } +@Rowa + A { @I length @Code rand @I length } + B { random real length in this range inclusive (98) } +@Rowa + A { @I length @Code max @I length } + B { the larger of two lengths (98) } +@Rowa + A { @I length @Code min @I length } + B { the smaller of two lengths (98) } +@Rowa + A { @I point @Code "distance" @I point } + B { (non-negative) distance between two points (98) } +@Rowa + A { @I length @Code "*" @I number } + B { length multiplied by number (97) } +@Rowa + A { @I number @Code "*" @I length } + B { length multiplied by number (97) } +@Rowa + A { @I length @Code "/" @I number } + B { length divided by number (96, left associative) } +@Rowa + A { @I length @Code "+" @I length } + B { sum of two lengths (96, left associative) } +@Rowa + A { @Code "+" @I length } + B { identity operation (96) } +@Rowa + A { @I length @Sym minus @I length } + B { difference of two lengths (96, left associative) } +@Rowa + A { @Sym minus @I length } + B { negation (96) } + +@Rowh +@Rowh +@Rowh +@Rowh +@Rowh A { @I angle } vmargin { 0.2vx } +@Rowh +@Rowa + A { @I number @Code d } + B { @I number degrees (100) } +@Rowa + A { @I number } + B { @I number degrees (@Code d is optional) (100) } +@Rowa + A { @Code parallel } + B { ({@Code labelangle} options only) angle parallel to curve at label point } +@Rowa + A { @Code antiparallel } + B { ({@Code labelangle} options only) angle antiparallel to curve at label point } +@Rowa + A { @Code perpendicular } + B { ({@Code labelangle} options only) angle perpendicular to curve at label point } +@Rowa + A { @Code antiperpendicular } + B { ({@Code labelangle} options only) angle antiperpendicular to curve at label point } +@Rowa + A { {@I label}{@Code "??ANGLE"} } + B { angle parallel to curve at {@I label} if known, else @Code "0d" (99) } +@Rowa + A { @Code anglefix @I angle } + B { @I angle normalized to between @Code 0d inclusive and @Code 360d exclusive (99) } +@Rowa + A { @Code abs @I angle } + B { absolute value (99) } +@Rowa + A { @I length @Code atan @I length } + B { arc tangent of first over second (98) } +@Rowa + A { @I point @Code "angleto" @I point } + B { angle from first point to second (98) } +@Rowa + A { @I angle @Code rand @I angle } + B { random angle in this range inclusive (98) } +@Rowa + A { @I angle @Code max @I angle } + B { the larger of two angles (98) } +@Rowa + A { @I angle @Code min @I angle } + B { the smaller of two angles (98) } +@Rowa + A { @I angle @Code "*" @I number } + B { angle multiplied by number (97) } +@Rowa + A { @I number @Code "*" @I angle } + B { angle multiplied by number (97) } +@Rowa + A { @I angle @Code "/" @I number } + B { division of angle by number (96, left associative) } +@Rowa + A { @I angle @Code "+" @I angle } + B { sum of two angles (96, left associative) } +@Rowa + A { @Code "+" @I angle } + B { identity operation (96) } +@Rowa + A { @I angle @Sym minus @I angle } + B { difference of two angles (96, left associative) } +@Rowa + A { @Sym minus @I angle } + B { negation (96) } +@Rowa + A { @Code angle } + B { ({@Code outline} only) value of the node's @Code angle option } + + +@Rowh +@Rowh +@Rowh +@Rowh +@Rowh A { @I point } vmargin { 0.2vx } +@Rowh +@Rowa + A { @I label } + B { a previously defined label } +@Rowa + A { {@I any}{@Code "??"}{@I label} } + B { {@I any}{@Code "@"}{@I label} if sensible, else {@I any} (99) } +@Rowa + A { @Code "prev" } + B { the previous point in a shape } +@Rowa + A { @I length @Code "atangle" @I angle } + B { point at distance and angle from origin (89) } +@Rowa + A { @I "point/tag" @Code "boundaryatangle" @I angle } + B { @I {point}, or point on boundary of @I tag at @I angle (89) } +@Rowa + A { @I point @Code "**" @I number } + B { multiplication of point by number (88) } +@Rowa + A { @I point @Code "++" @I point } + B { vector sum of two points (87) } +@Rowa + A { @I point {@Sym minus}{@Sym minus} @I point } + B { vector difference of two points (87) } +@Rowa + A { @I {number, number} } + B { @I x and @I y coordinates with respect to base (70) } +@Rowa + A { @I {length length} } + B { @I x and @I y distance from origin (5) } +@Rowa + A { @Code from } + B { ({@Code path} only) the value of the link's @Code from option } +@Rowa + A { @Code to } + B { ({@Code path} only) the value of the link's @Code to option } + +@Rowh +@Rowh +@Rowh +@Rowh +@Rowh A { @I boolean } vmargin { 0.2vx } +@Rowh +@Rowa + A { @I number @Code "=" @I number } + B { @Eq { non = }; also between lengths (79) } +@Rowa + A { @I number @Code "!=" @I number } + B { @Eq { non != }; also between lengths (79) } +@Rowa + A { @I number @Code "==" @I number } + B { @Eq { non = } between angles (79) } +@Rowa + A { @I number @Code "!==" @I number } + B { @Eq { non != } between angles (79) } +@Rowa + A { @I number @Code "<=" @I number } + B { @Eq { non <= }; also between lengths (79) } +@Rowa + A { @I number @Code "<" @I number } + B { @Eq { non < }; also between lengths (79) } +@Rowa + A { @I number @Code ">=" @I number } + B { @Eq { non >= }; also between lengths (79) } +@Rowa + A { @I number @Code ">" @I number } + B { @Eq { non > }; also between lengths (79) } +@Rowa + A { @Code "not" @I boolean } + B { Logical not (78) } +@Rowa + A { @I boolean @Code "and" @I boolean } + B { Logical and (77) } +@Rowa + A { @I boolean @Code "or" @I boolean } + B { Logical or (76) } +@Rowa + A { @I boolean @Code "xor" @I boolean } + B { Logical exclusive or (76) } + +} +@DP +A length is represented in PostScript by a single number on the operand +stack; so is an angle. Therefore all number operations can be applied +to lengths and angles as well, but the results will not always be +useful. For example, rounding a length to the nearest integer is +not a useful thing to do because the result depends on the basic unit +(what does 1 equal as a length?) which is implementation-dependent and +genuinely subject to change. Rounding the @I ratio of two lengths does +make sense. The above is an attempt to list only the useful operations; +but if you really need the logarithm of an angle, you can have it. +@PP +Angles are a little more amenable to this kind of thing because they are +always measured in degrees. However, angles suffer from the problem that +{@Code 0d} is really the same angle as {@Code 360d}. For this reason, +separate equality and inequality operators for angles are provided which +ignore multiples of {@Code 360d}, and less than and similar relations +are not defined for angles, because they inherently are not well +defined. See also the @Code anglefix symbol above. +@PP +A point is represented by two lengths (which are numbers) on the +stack. Those familiar with PostScript and willing to sacrifice portability +and increase their risk of error can therefore write, for example, +@OneCol { @I point @Code "exch" } to obtain the reflection of a point about +the main diagonal, and so on. +@PP +The following may have a result of any type, depending on +their options. The options and result may be a +sequence of things as required in shapes, including @Code "[]" and +so forth. +@IndentedList +@LI @OneRow lines @Break { +@Code if + @Code "cond {" @I boolean @Code "}" + @Code "then {" @I anything @Code "}" + @Code "else {" @I anything @Code "}" +} +@LI @OneRow lines @Break { +@I angle @Code quadcase + @Code "0 {" @I anything @Code "}" + @Code "0-90 {" @I anything @Code "}" + @Code "90 {" @I anything @Code "}" + @Code "90-180 {" @I anything @Code "}" + @Code "180 {" @I anything @Code "}" + @Code "180-270 {" @I anything @Code "}" + @Code "270 {" @I anything @Code "}" + @Code "270-360 {" @I anything @Code "}" +} +@LI @OneRow lines @Break { +@I number @Code signcase + @Code "neg {" @I anything @Code "}" + @Code "zero {" @I anything @Code "}" + @Code "pos {" @I anything @Code "}" +} +@LI @OneRow lines @Break { +@Code "xloop from {" @I number "} to {" @I number "} by {" @I number "} do {" + @I anything +@Code "}" +} +@LI @OneRow lines @Break { +@Code "yloop from {" @I number "} to {" @I number "} by {" @I number "} do {" + @I anything +@Code "}" +} +@LI @OneRow lines @Break { +@Code "zloop from {" @I number "} to {" @I number "} by {" @I number "} do {" + @I anything +@Code "}" +} +@EndList +The @Code "if" symbol returns @Code "then" or @Code "else" depending on +the value of {@Code "cond"}, and @Code "signcase" returns {@Code "neg"}, +{@Code zero}, or {@Code pos} depending on whether @I number (which +may also be an angle or a length) is negative, zero, or positive. The +@Code "quadcase" symbol decides whether the given angle points in +one of the four horizontal or vertical directions, or into the quadrants +between them, and returns the appropriate option. Don't be misled by +the unorthodox option names; it is not possible to give your own +ranges, only these ones. +@PP +The loops return a sequence of +repetitions of {@I anything}; any occurrences of {@Code x} in +{@Code xloop} will be replaced by the current value of the loop counter, +and similarly for the other loops. +@PP +Symbols not covered in this summary are the retagging symbol @Code "::" +(Section {@NumberOf dia_tags}); the symbols available within the +{@Code "@Tree"} symbol (Section {@NumberOf dia_posi}); and {@Code ":<"}, +{@Code ":="}, {@Code "@ShowPoints"}, {@Code "@ShowTags"}, and +{@Code "@ShowDirections"} from Section {@NumberOf dia_defi}. +@End @Section diff --git a/doc/user/dia_tags b/doc/user/dia_tags new file mode 100644 index 0000000..91cd7a1 --- /dev/null +++ b/doc/user/dia_tags @@ -0,0 +1,168 @@ +@Section + @Tag { dia_tags } + @Title { Tags } +@Begin +@PP +In addition to drawing the outline, each of the standard node +types also attaches names, called {@I tags}, to certain points. For +example, the @Code "@Ellipse" symbol creates nine tags: +@ID { +@Code { +"@Ellipse" +} +||7ct +@Diag { +//1.0f +@ShowTags @Ellipse + vsize { 1.5c } + hsize { 3.0c } +} +} +The standard link symbols also create tags: +@ID { +@Code { +"@Link" +} +||7ct +@Diag { +2.5c @High 2c @Wide +// +@ShowTags @Arrow + from { 0,0.8 } + to { 1,0 } +} +} +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 }" +} +||7ct +@Diag { +@Ellipse { Hello, world } +// +@Link from { SW } to { SE } +} +} +A tag may only be used later in the text of the diagram than the place +where it is defined. +@PP +Standard tags like @Code N and @Code S are not much use as they are, +since in general there will be many nodes and hence many @Code N and +@Code S tags. The retagging symbol, {@Code "::"}, solves this problem: +@ID { +@Code { +"A:: @Ellipse" +} +||7ct +@Diag { +//1.5f +@ShowTags { +A:: @Ellipse + vsize { 1.5c } + hsize { 3.0c } +} +} +} +Within the following object, the points have their original tags, but +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 }" +} +||7ct +@Diag { +A:: @Ellipse { Hello, world } +// +@Link from { A@SW } to { A@SE } +} +} +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 }" +"}" +} +||7ct +@Diag { +//1.0f +@ShowTags { +A:: { + 1:: @Ellipse + vsize { 1.0c } + hsize { 2.5c } + @DP + @DP + 2:: @Ellipse + vsize { 1.0c } + hsize { 2.5c } +} +} +} +} +In practice one usually only retags individual nodes. It is best to +use only upper-case letters and digits in tags, because Lout and +PostScript have tags of their own containing lower-case letters, and +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" +} +the circle lies within the square, and what you get in effect is +@ID @Code { +"@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 +effects on the positioning of labels of the outer node if inner tags are +not retagged. +@PP +Although @Code from and @Code to are just two of several options within +@Code "@Diag" where a point is expected, and hence where a tag may be +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 { +@Code { +"A:: @Circle" +"@DP" +"B:: @Ellipse { Hello, world }" +"//" +"@Link from { A } to { B }" +} +||7ct +@Diag { +A:: @Circle +@DP +B:: @Ellipse { Hello, world } +// +@Link from { A } to { B } +} +} +This will select a point on the outline of the named node, appropriate +to the type of link being drawn. It is extremely useful, of course, but +potentially confusing: @Code A and @Code B do not denote points and are +not tags, strictly speaking, at all. +@End @Section diff --git a/doc/user/dia_tree b/doc/user/dia_tree new file mode 100644 index 0000000..d16f2bc --- /dev/null +++ b/doc/user/dia_tree @@ -0,0 +1,379 @@ +@Section + @Tag { dia_tree } + @Title { Trees } +@Begin +@PP +@@Diag offers some symbols for producing tree diagrams, using the +tree. @Index { @Code "@Tree" symbol in @@Diag } +@Code "@Tree" symbol, which may appear anywhere within the nodes part: +@ID @OneRow @Code { +"@Diag {" +" ..." +" @Tree { ... }" +" ..." +"}" +} +Within this symbol, new symbols {@Code "@LeftSub"}, {@Code "@RightSub"}, +{@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" +"}" +} +||7ct +@Diag { +@Tree { + @Circle A + @LeftSub { + @Circle B + @LeftSub @Square C + @RightSub @Square D + } + @RightSub @Circle E +} +} +} +The root of the tree, which must be a single node but may have any +outline, comes first. After that comes the @Code "@LeftSub" symbol +followed by the left subtree, which must be enclosed in braces unless +it consists of a single node. After that comes the @Code "@RightSub" +symbol followed by the right subtree, again enclosed in braces unless it +consists of a single node. These rules apply recursively and will +produce a binary tree of arbitrary size and depth. If a node has no +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 +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" +"}" +} +||7ct +@Diag { +@Tree { + @Circle A + @FirstSub { + @Circle B + @FirstSub @Square C + @NextSub @Square D + } + @NextSub @Circle E + @NextSub @Circle F +} +} +} +The first subtree is preceded by {@Code "@FirstSub"}, and subsequent +trees are preceded by {@Code "@NextSub"}. The subtrees are spaced +at equal separations from each other, with the root centred over +them, in contrast to the binary tree arrangement in which the two +subtrees are positioned to the left and right of the root, never +intruding into the space beneath it. +@PP +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" +"}" +} +||7ct +@Diag { +@Tree +{ +@Circle +@FirstSub @Circle +@NextSub pathstyle { noline } + @Circle outlinestyle { noline } + ... +@NextSub @Circle +} +} +} +Clumsy as this is, it often assists in placing the unenclosed object +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: +@ID @OneRow { +@Code { +"@Tree {" +"@Circle @Eq { a }" +"@StubSub @Eq { T tsub a }" +"}" +} +||7ct +@Diag { +@Tree { +@Circle @Eq { a } +@StubSub @Eq { T tsub a } +} +} +} +Unlike the other subtree symbols, {@Code "@StubSub"} is not followed +by a subtree with a node for its root; rather, it is followed by an +arbitrary object, and the path is drawn around this stub object, which +is placed directly underneath the parent node with zero vertical +separation. In practice, it is usually necessary to attach margins to +the following object; the easiest way to do that is to enclose it in +{@Code "@Box outlinestyle { noline }"}. An example appears below. +@PP +It is possible to mix the three subtree types, by having binary tree +symbols following some nodes, non-binary tree symbols following +others, and a single {@Code "@StubSub"} following others. However, +at any one node the subtrees must be all either binary, non-binary, +or stub. +@PP +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" +"}" +} +||7ct +@Diag { +@Tree { + @Circle A + @LeftSub + arrow { yes } + xlabel { 1 } + @Circle B + @RightSub + arrow { yes } + xlabel { 2 } + @Circle C +} +} +} +To get reverse arrows use @Code "arrow { back }" as usual. +@PP +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 +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 }" +"}" +} +||7ct +@Diag +{ +@Tree { +@Circle +@LeftSub from { S } to { N } + @Isosceles vsize { 2f } +@RightSub from { S } to { N } + @Isosceles vsize { 2f } +} +} +} +In this example both links go from the @Code S tag of the parent node to the +@Code N tag of the child node (at the apex of the iscosceles triangle). These +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 }" +"}" +} +||7ct +@Diag { +@Tree { +@Circle @Eq { a } +@StubSub + from { SW } + to { SE } +@Box outlinestyle { noline } + @Eq { T tsub a } +} +} +} +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 +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" +"} }" +} +||7ct +@Diag { +@Tree +{ +@Circle +@LeftSub { + @Circle + @LeftSub @Square + @RightSub @Square +} +@RightSub { + @Circle + @LeftSub { + @Circle + @ZeroWidthLeftSub @Square + @ZeroWidthRightSub @Square + } + @RightSub @Square +} +} +} +} +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 +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 +and its subtrees: +@ID @OneRow { +@Code { +"@Diag" +" treehsep { 0c }" +" treevsep { 0c }" +"{" +"@Tree" +"{" +" @Circle A" +" @LeftSub @Square B" +" @RightSub @Square C" +"}" +"}" +} +||7ct +@Diag + treehsep { 0c } + treevsep { 0c } +{ +@Tree +{ + @Circle A + @LeftSub @Square B + @RightSub @Square C +} +} +} +These options may also be given to individual subtree symbols, although +@Code "treevsep" works as expected only with @Code "@LeftSub" and +{@Code "@FirstSub"}, since these determine the vertical separation of +all children of their parent. +@PP +The @Code "treehindent" option determines where the root of a non-binary +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 +the left. Owing to problems behind the scenes, this option may not be +given to individual subtree symbols; so as a consolation, it is permitted +as an option to the @Code "@Tree" symbol. +@PP +It is not possible to attach tags to nodes within a tree, because +tags are attached automatically by the tree symbols and any extra +tags would disrupt the linking. However, you can use @Code "@ShowTags" +to find out what these automatic tags are, and use them in a subsequent +links part. For example, the tag attached to the right child of the left +child of the root of a binary tree is {@Code "L@R@T"}, and in general the +tag records the path from the root to the node, with @Code "T" added to +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 } +@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 +@Code "@FirstSub" produce what might be called the top subtree, and +@Code "@RightSub" and @Code "@NextSub" produce lower trees. @Code "@HTree" +has no @Code "treehindent" option; instead, it has an exactly analogous +@Code "treevindent" option. +@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" +" }" +"}" +"}" +} +||7ct +@I @Diag arrow { yes } treehsep { 1c } { +@HTree { +@Node A +@FirstSub { + @Node B + @FirstSub @Node C +} +} +} +} +The braces are clumsy but necessary. The first node has tag {@Code "T"}, the +second has tag {@Code "S@T"}, the third has tag {@Code "S@S@T"}, and so on. +@End @Section diff --git a/doc/user/draft.eps b/doc/user/draft.eps new file mode 100644 index 0000000..bfc6e9a --- /dev/null +++ b/doc/user/draft.eps @@ -0,0 +1,289 @@ +%!PS-Adobe-3.0 +%%Creator: Basser Lout Version 3.00 (July 1994) +%%CreationDate: Fri Sep 9 10:46:13 1994 +%%DocumentData: Binary +%%DocumentNeededResources: (atend) +%%DocumentSuppliedResources: (atend) +%%Pages: (atend) +%%BoundingBox: 0 0 595 842 +%%EndComments + +%%BeginProlog +%%BeginResource: procset LoutStartUp +/m { 3 1 roll moveto show } bind def +/s { exch currentpoint exch pop moveto show } bind def +/k { exch neg 0 rmoveto show } bind def +/in { 1440 mul } def +/cm { 567 mul } def +/pt { 20 mul } def +/em { 120 mul } def +/sp { louts mul } def +/vs { loutv mul } def +/ft { loutf mul } def +/dg { } def + +/LoutGraphic { + /louts exch def + /loutv exch def + /loutf exch def + /ymark exch def + /xmark exch def + /ysize exch def + /xsize exch def +} def + +/LoutFont +{ findfont exch scalefont setfont +} bind def + +/LoutRecode { + { findfont dup length dict begin + {1 index /FID ne {def} {pop pop} ifelse} forall + /Encoding exch def + currentdict end definefont pop + } + stopped {} +} bind def + +/BeginEPSF { + /LoutEPSFState save def + /dict_count countdictstack def + /op_count count 1 sub def + userdict begin + /showpage { } def + 0 setgray 0 setlinecap + 1 setlinewidth 0 setlinejoin + 10 setmiterlimit [] 0 setdash newpath + /languagelevel where + { pop languagelevel + 1 ne + { false setstrokeadjust false setoverprint + } if + } if +} bind def + +/EndEPSF { + count op_count sub { pop } repeat + countdictstack dict_count sub { end } repeat + LoutEPSFState restore +} bind def +%%EndResource + +%%BeginResource encoding vec1 +/vec1 [ +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/space /exclam /quotedbl /numbersign /dollar /percent /ampersand /quoteright +/parenleft /parenright /asterisk /plus /comma /hyphen /period /slash +/zero /one /two /three /four /five /six /seven +/eight /nine /colon /semicolon /less /equal /greater /question +/at /A /B /C /D /E /F /G +/H /I /J /K /L /M /N /O +/P /Q /R /S /T /U /V /W +/X /Y /Z /bracketleft /backslash /bracketright /asciicircum /underscore +/quoteleft /a /b /c /d /e /f /g +/h /i /j /k /l /m /n /o +/p /q /r /s /t /u /v /w +/x /y /z /braceleft /bar /braceright /asciitilde /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /quotedblleft /quotedblright /fi +/fl /endash /emdash /bullet /dagger /daggerdbl /florin /fraction +/dotlessi /grave /acute /circumflex /tilde /macron /breve /dotaccent +/dieresis /.notdef /ring /cedilla /.notdef /hungarumlaut /ogonek /caron +/space /exclamdown /cent /sterling /currency /yen /brokenbar /section +/dieresis /copyright /ordfeminine /guillemotleft /logicalnot /hyphen /registered /macron +/degree /plusminus /twosuperior /threesuperior /acute /mu /paragraph /periodcentered +/cedilla /onesuperior /ordmasculine /guillemotright /onequarter /onehalf /threequarters /questiondown +/Agrave /Aacute /Acircumflex /Atilde /Adieresis /Aring /AE /Ccedilla +/Egrave /Eacute /Ecircumflex /Edieresis /Igrave /Iacute /Icircumflex /Idieresis +/Eth /Ntilde /Ograve /Oacute /Ocircumflex /Otilde /Odieresis /multiply +/Oslash /Ugrave /Uacute /Ucircumflex /Udieresis /Yacute /Thorn /germandbls +/agrave /aacute /acircumflex /atilde /adieresis /aring /ae /ccedilla +/egrave /eacute /ecircumflex /edieresis /igrave /iacute /icircumflex /idieresis +/eth /ntilde /ograve /oacute /ocircumflex /otilde /odieresis /divide +/oslash /ugrave /uacute /ucircumflex /udieresis /yacute /thorn /ydieresis +] def +%%EndResource + +%%EndProlog + +%%BeginSetup +%%IncludeResource: font Times-Roman +/Times-Romanfnt86 vec1 /Times-Roman LoutRecode +/fnt86 { /Times-Romanfnt86 LoutFont } def +%%IncludeResource: font Times-Bold +/Times-Boldfnt88 vec1 /Times-Bold LoutRecode +/fnt88 { /Times-Boldfnt88 LoutFont } def +%%IncludeResource: font Times-Italic +/Times-Italicfnt87 vec1 /Times-Italic LoutRecode +/fnt87 { /Times-Italicfnt87 LoutFont } def +/LoutExtColour [ currentrgbcolor ] cvx def +%%EndSetup + +%%Page: ? 1 +%%BeginPageSetup +%%PageResources: font Times-Roman +%%+ font Times-Bold +%%+ font Times-Italic +/pgsave save def +0.0500 dup scale 10 setlinewidth +%%EndPageSetup + +gsave +0 16840 translate +0.0000 rotate +gsave +3087 -14622 translate +17.7734 17.7734 scale +gsave +0 0 translate +62.0000 rotate +240 fnt86 0.8 0.8 0.8 setrgbcolor 0 -54(DRAFT)m +grestore + +grestore + +grestore +gsave +0 16840 translate +0.0000 rotate +240 fnt88 LoutExtColour setrgbcolor +5143 -3022(A)m 5376(T)s 22(est)k 5852(Example)s 240 fnt87 +5029 -3520(J)m 6(ef)k 4(fr)k 8(e)k 7(y)k +5713(H.)s 6006(Kingston)s 240 fnt86 3998 -4021(Basser)m 4695(Department)s +5883(of)s 6142(Computer)s 7159(Science)s 4446 -4309(The)m 4878(Uni)s 6(v)k 3(ersity)k +5938(of)s 6197(Sydne)s 3(y)k 6973(2006)s 5512 -4597(Australia)m +5053 -5050(9)m 5233(September)s 9(,)k 6366(1994)s 240 fnt88 +3097 -5692(Abstract)m 240 fnt86 1897 -6123(This)m 2403(is)s 2643(the)s +3016(abstract.)s 3959(It')s 13(s)k 4344(v)s 3(ery)k +4847(short,)s 5466(as)s 1417 -6411(be\207ts)m 2036(a)s 2243(tin)s 3(y)k +2713(test)s 3145(document.)s 4310(Ho)s 6(we)k 6(v)k 3(er)k +5273(it)s 5506(is)s 1417 -6699(long)m 1892(enough)s 2647(to)s +2882(check)s 3489(that)s 3896(things)s 4530(are)s 4870(w)s 2(orking)k +1417 -6987(as)m 1676(e)s 3(xpected.)k 240 fnt88 1417 -7780(1.)m +1717(The)s 2176(\207rst)s 2647(section)s 240 fnt86 1897 -8211(This)m +2408(is)s 2653(the)s 3031(\207rst)s 3488(section.)s 4371(It)s +4602(too)s 4994(is)s 5239(v)s 3(ery)k 1417 -8499(short,)m +2045(just)s 2480(a)s 2676(test)s 3097(section,)s 3924(nothing)s +4746(more)s 5327([)s 5406(1)s 5526(])s 5605(.)s +1417 -8787(This)m 1912(is)s 2141(the)s 2503(\207rst)s 2944(section.)s +3811(It)s 4026(too)s 4402(is)s 4631(v)s 3(ery)k +5123(short,)s 1417 -9075(just)m 1885(a)s 2114(test)s 2568(section,)s +3428(nothing)s 4283(more.)s 4957(This)s 5505(is)s 1417 -9363(the)m +1794(\207rst)s 2250(section.)s 3132(It)s 3362(too)s 3753(is)s +3997(v)s 3(ery)k 4504(short,)s 5127(just)s 5557(a)s +1417 -9651(test)m 1841(section,)s 2671(nothing)s 3496(more.)s 4140(This)s +4658(is)s 4910(the)s 5295(\207rst)s 1417 -9939(section.)m 2255(It)s +2441(too)s 2788(is)s 2988(v)s 3(ery)k 3451(short,)s +4030(just)s 4416(a)s 4563(test)s 4935(section,)s 1417 -10227(nothing)m +2254(more.)s 153 fnt86 2805 -10121(i)m 240 fnt86 2952 -10227(This)m +3482(is)s 3746(the)s 4143(\207rst)s 4619(section.)s 5521(It)s +1417 -10515(too)m 1794(is)s 2024(v)s 3(ery)k 2517(short,)s +3126(just)s 3542(a)s 3719(test)s 4121(section,)s 4929(nothing)s +1417 -10803(more.)m 2037(This)s 2531(is)s 2759(the)s 3120(\207rst)s +3560(section.)s 4426(It)s 4640(too)s 5015(is)s 5243(v)s 3(ery)k +1417 -11091(short,)m 2024(just)s 2438(a)s 2613(test)s 3013(section,)s +3819(nothing)s 4620(more.)s 5240(This)s 1417 -11379(is)m 1655(the)s +2026(\207rst)s 2476(section.)s 3352(It)s 3576(too)s 3961(is)s +4199(v)s 3(ery)k 4700(short,)s 5317(just)s 1417 -11667(a)m +1591(test)s 1990(section,)s 2795(nothing)s 3595(more.)s 4214(This)s +4707(is)s 4934(the)s 5294(\207rst)s 1417 -11955(section.)m 2255(It)s +2441(too)s 2788(is)s 2988(v)s 3(ery)k 3451(short,)s +4030(just)s 4416(a)s 4563(test)s 4935(section,)s 1417 -12243(nothing)m +2260(more.)s 2922(This)s 3458(is)s 3728(the)s 4131(\207rst)s +4613(section.)s 5521(It)s 1417 -12531(too)m 1794(is)s 2024(v)s 3(ery)k +2517(short,)s 3126(just)s 3542(a)s 3719(test)s 4121(section,)s +4929(nothing)s 1417 -12819(more.)m 2037(This)s 2531(is)s 2759(the)s +3120(\207rst)s 3560(section.)s 4426(It)s 4640(too)s 5015(is)s +5243(v)s 3(ery)k 1417 -13107(short,)m 2024(just)s 2438(a)s +2613(test)s 3013(section,)s 3819(nothing)s 4620(more.)s 5240(This)s +1417 -13395(is)m 1655(the)s 2026(\207rst)s 2476(section.)s 3352(It)s +3576(too)s 3961(is)s 4199(v)s 3(ery)k 4700(short,)s +5317(just)s 1417 -13683(a)m 1591(test)s 1990(section,)s 2795(nothing)s +3595(more.)s 4214(This)s 4707(is)s 4934(the)s 5294(\207rst)s +1417 -13971(section.)m 2255(It)s 2441(too)s 2788(is)s 2988(v)s 3(ery)k +3451(short,)s 4030(just)s 4416(a)s 4563(test)s 4935(section,)s +1417 -14259(nothing)m 2260(more.)s 2922(This)s 3458(is)s 3728(the)s +4131(\207rst)s 4613(section.)s 5521(It)s 1417 -14547(too)m 1794(is)s +2024(v)s 3(ery)k 2517(short,)s 3126(just)s 3542(a)s +3719(test)s 4121(section,)s 4929(nothing)s 1417 -14835(more.)m 2037(This)s +2531(is)s 2759(the)s 3120(\207rst)s 3560(section.)s 4426(It)s +4640(too)s 5015(is)s 5243(v)s 3(ery)k 1417 -15123(short,)m +2024(just)s 2438(a)s 2613(test)s 3013(section,)s 3819(nothing)s +4620(more.)s 5240(This)s 6233 -5690(is)m 6471(the)s 6842(\207rst)s +7292(section.)s 8168(It)s 8392(too)s 8777(is)s 9015(v)s 3(ery)k +9516(short,)s 10133(just)s 6233 -5978(a)m 6407(test)s 6806(section,)s +7611(nothing)s 8411(more.)s 9030(This)s 9523(is)s 9750(the)s +10110(\207rst)s 6233 -6266(section.)m 7071(It)s 7257(too)s 7604(is)s +7804(v)s 3(ery)k 8267(short,)s 8846(just)s 9232(a)s +9379(test)s 9751(section,)s 6233 -6554(nothing)m 7076(more.)s 7738(This)s +8274(is)s 8544(the)s 8947(\207rst)s 9429(section.)s 10337(It)s +6233 -6842(too)m 6610(is)s 6840(v)s 3(ery)k 7333(short,)s +7942(just)s 8358(a)s 8535(test)s 8937(section,)s 9745(nothing)s +6233 -7130(more.)m 6853(This)s 7347(is)s 7575(the)s 7936(\207rst)s +8376(section.)s 9242(It)s 9456(too)s 9831(is)s 10059(v)s 3(ery)k +6233 -7418(short,)m 6829(just)s 7232(a)s 7396(test)s 7785(section,)s +8580(nothing)s 9370(more.)s 153 fnt86 9921 -7312(ii)m 240 fnt86 +10063 -7418(This)m 6233 -7706(is)m 6471(the)s 6842(\207rst)s 7292(section.)s +8168(It)s 8392(too)s 8777(is)s 9015(v)s 3(ery)k +9516(short,)s 10133(just)s 6233 -7994(a)m 6407(test)s 6806(section,)s +7611(nothing)s 8411(more.)s 9030(This)s 9523(is)s 9750(the)s +10110(\207rst)s 6233 -8282(section.)m 7071(It)s 7257(too)s 7604(is)s +7804(v)s 3(ery)k 8267(short,)s 8846(just)s 9232(a)s +9379(test)s 9751(section,)s 6233 -8570(nothing)m 7066(more.)s 153 fnt86 +7617 -8464(a)m 240 fnt86 7785 -8570(This)m 8311(is)s 8571(the)s +8964(\207rst)s 9436(section.)s 10334(It)s 6233 -8858(too)m 6610(is)s +6840(v)s 3(ery)k 7333(short,)s 7942(just)s 8358(a)s +8535(test)s 8937(section,)s 9745(nothing)s 6233 -9146(more.)m 6853(This)s +7347(is)s 7575(the)s 7936(\207rst)s 8376(section.)s 9242(It)s +9456(too)s 9831(is)s 10059(v)s 3(ery)k 6233 -9434(short,)m +6840(just)s 7254(a)s 7429(test)s 7829(section,)s 8635(nothing)s +9436(more.)s 10056(This)s 6233 -9722(is)m 6471(the)s 6842(\207rst)s +7292(section.)s 8168(It)s 8392(too)s 8777(is)s 9015(v)s 3(ery)k +9516(short,)s 10133(just)s 6233 -10010(a)m 6407(test)s 6806(section,)s +7611(nothing)s 8411(more.)s 9030(This)s 9523(is)s 9750(the)s +10110(\207rst)s 6233 -10298(section.)m 7071(It)s 7257(too)s 7604(is)s +7804(v)s 3(ery)k 8267(short,)s 8846(just)s 9232(a)s +9379(test)s 9751(section,)s 6233 -10586(nothing)m 7076(more.)s 7738(This)s +8274(is)s 8544(the)s 8947(\207rst)s 9429(section.)s 10337(It)s +6233 -10874(too)m 6610(is)s 6840(v)s 3(ery)k 7333(short,)s +7942(just)s 8358(a)s 8535(test)s 8937(section,)s 9745(nothing)s +6233 -11162(more.)m 240 fnt88 6233 -11761(1.1)m 6533(.)s 6713(The)s +7172(\207rst)s 7643(subsection)s 240 fnt86 6713 -12192(This)m 7244(is)s +7509(the)s 7907(\207rst)s 8384(subsection,)s 9560(and)s 10012(what)s +6233 -12480(is)m 6518(more)s 7135(it)s 7393(has)s 7838(sub-subsections)s +9479(which)s 10190(are)s 6233 -12768(starting)m 7009(no)s 6(w)k 15(.)k +240 fnt87 6233 -13415(The)m 6652(\207r)s 2(st)k 7082(sub-subsection)s +240 fnt86 6713 -13893(This)m 7222(is)s 7465(the)s 7841(\207rst)s +8296(sub-subsection.)s 9922(There)s 6233 -14181(will)m 6664(be)s 6950(a)s +7116(second)s 7841(one)s 8247(in)s 8493(a)s 8659(minute.)s +gsave +6233 -14668 translate +240 fnt86 LoutExtColour setrgbcolor 1134 0 0 0 240 288 60 LoutGraphic +gsave +0 0 moveto xsize 0 lineto stroke +grestore + +grestore +122 fnt86 LoutExtColour setrgbcolor 6233 -14836(a)m 192 fnt86 6287 -14921(This)m +6687(is)s 6874(the)s 7168(\207rst)s 7524(footnote,)s 8270(anchored)s +9032(to)s 4(w)k 1(ards)k 9692(the)s 9986(end)s +10323(of)s 6233 -15151(the)m 6530(\207rst)s 6889(section.)s 7590(It)s +7769(should)s 8343(appear)s 8916(at)s 9117(the)s 9414(bottom)s +10020(of)s 10242(the)s 6233 -15381(page.)m 6739(Let')s 10(s)k +7169(hope)s 7590(it)s 7744(comes)s 8281(out)s 8574(right.)s + +grestore + +pgsave restore +showpage + +%%Trailer +%%DocumentNeededResources: font Times-Roman +%%+ font Times-Italic +%%+ font Times-Bold +%%DocumentSuppliedResources: procset LoutStartUp +%%+ encoding vec1 +%%Pages: 1 +%%EOF diff --git a/doc/user/equ b/doc/user/equ new file mode 100644 index 0000000..7a87fdb --- /dev/null +++ b/doc/user/equ @@ -0,0 +1,28 @@ +@Chapter + @Title { Equations } + @Tag { equations } +@Begin +@LP +This chapter explains how to produce mathematical formulas in Lout, +equations. @Index { equations } +mathematics. @Index mathematics +eq. @Index @Code "@Eq" +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 }" +} +This example produces +@ID @Eq { big int supp 1 on 0 ` dx over sqrt {1 - x sup 2} = pi over 2 } +The @Code "@Eq" symbol looks after all the details of spacing for +you, and it provides several hundred mathematical symbols. +@BeginSections +@Include { equ_intr } +@Include { equ_symb } +@Include { equ_vert } +@Include { equ_spac } +@Include { equ_disp } +@Include { equ_defs } +@Include { equ_summ } +@Include { equ_tequ } +@EndSections +@End @Chapter diff --git a/doc/user/equ_defs b/doc/user/equ_defs new file mode 100644 index 0000000..0e38da7 --- /dev/null +++ b/doc/user/equ_defs @@ -0,0 +1,53 @@ +@Section + @Title { Defining new equation formatting symbols } +@Begin +@PP +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 +of their use in equation formatting. +@PP +Suppose for example that @OneCol @Eq { p sub i ` log sub 2 ` p sub i } +occurs frequently in your document. Then +@ID @Code "def epi { p sub i ` log sub 2 ` p sub i }" +makes the symbol @Code "epi" stand for the object between the braces: +@ID { +@Code "big sum from i=1 to n ` epi" +|7ct +@Eq { big sum from i=1 to n ` epi } +} +Parameters are very useful when parts of the symbol vary: +@ID @OneRow @Code { +"def ep" +" right x" +"{ p sub x ` log sub 2 ` p sub x" +"}" +} +The parameter @Code x will be replaced by the object just to the right +of {@Code "ep"}: +@ID { +@Code { +"big sum from i=1 to k ` ep i +" +"big sum from j=k+1 to n ep j" +} +||7ct +@Eq { +big sum from i=1 to k ` ep i + +big sum from j=k+1 to n ep j +} +} +The precedence of the symbols you define will be 100 by default. +@PP +To make the symbols of @Code "@Eq" available within such definitions, +each must be preceded by {@Code "import @Eq"}. As explained in Section +{@NumberOf definitions}, the definitions go into a file called +{@Code "mydefs"}, which might then look like this: +@ID @OneRow @Code { +"import @Eq" +"def epi { p sub i ` log sub 2 ` p sub i }" +"" +"import @Eq" +"def ep right x { p sub x ` log sub 2 ` p sub x }" +} +Use of @Code "epi" and @Code "ep" outside @Code "@Eq" will cause an error. +@End @Section diff --git a/doc/user/equ_disp b/doc/user/equ_disp new file mode 100644 index 0000000..0167b8d --- /dev/null +++ b/doc/user/equ_disp @@ -0,0 +1,126 @@ +@Section + @Title { Displaying equations } + @Tag { mathdisplays } +@Begin +@PP +The result of the @Code "@Eq" symbol is an object which, according to the +displayed.equations @Index { displayed equations } +golden rule (Section {@NumberOf objects}), may appear anywhere: inside +a paragraph, inside a table, and so on. In particular, equations are +often displayed using the @Code "@CentredDisplay" or @Code "@IndentedDisplay" +symbols from Section {@NumberOf displays}: +@ID @Code "@IndentedDisplay @Eq { ... }" +Now displayed equations are often numbered, and often aligned with one +another on their equals signs. For this there are special display +symbols which are the the subject of this section. These symbols can +align and number any display at all, but since in practice they seem to +be used only with equations, we discuss them here rather than in +Section {@NumberOf displays} where they really belong. +@PP +Let's begin by looking at a first example of a numbered display: +aligned.displays @Index { aligned displays } +aligned.equations @Index { aligned equations } +numbered.displays @Index { numbered displays } +numbered.equations @Index { numbered equations } +@BeginAlignedDisplays +@CentredAlignedNumberedDisplay + @Tag { fibeq } +@Eq { F sub n ^= F sub {n-1} + F sub {n-2} } +After the display we might have some more text for a while, and then +we might want a second display, aligned on its equals sign with the +first, and also numbered in sequence with it: +@CentredAlignedNumberedDisplay +@Eq { F sub n - F sub {n-1} ^= F sub {n-2} } +@EndAlignedDisplays +Notice that the two displays are centred as a block as well as +aligned. Altogether there are four ways in which displays vary: +@BL +@LI { A display can be raw or not raw (see below); } +@LI { It can be a {@Code "@Display"}, {@Code "@LeftDisplay"}, +{@Code "@IndentedDisplay"}, {@Code "@QuotedDisplay"}, +{@Code "@CentredDisplay"}, {@Code "@CenteredDisplay"}, +or {@Code "@RightDisplay"}; } +@LI { It can be aligned or not aligned; } +@LI { It can be numbered or not numbered. } +@EL +All possible combinations are allowed. The display that has everything +is called +@ID @Code "@RawCentredAlignedNumberedDisplay" +By leaving out some or all of {@Code Raw}, {@Code Aligned}, and +{@Code Numbered}, and by changing or leaving out {@Code Centred}, +we get all these combinations. Here +numbereddisplay. @Index @Code "@NumberedDisplay" +aligneddisplay. @Index @Code "@AlignedDisplay" +then is how the two displays given earlier were made: +@ID @OneRow @Code { +"... a first example of a numbered display:" +"@BeginAlignedDisplays" +"@CentredAlignedNumberedDisplay" +" @Tag { fibeq }" +"@Eq { F sub n ^= F sub { n-1 } + F sub { n-2 } }" +"After the display we might ... numbered in sequence with it:" +"@CentredAlignedNumberedDisplay @Eq { F sub n - F sub { n-1 } ^= F sub { n-2 } }" +"@EndAlignedDisplays" +"Notice that the two displays are centred ..." +} +All numbered displays have an optional @Code "@Tag" option which is +used for cross referencing (see Section {@NumberOf cross}). Alignment +and numbering work quite independently; they don't have to start or end +together, and there can be non-aligned and non-numbered displays among +the others. +@PP +When aligned displays are used, it is necessary to indicate where the +aligned group begins and ends, by placing @Code "@BeginAlignedDisplays" +beginaligneddisplays @Index @Code "@BeginAlignedDisplays" +endaligneddisplays @Index @Code "@EndAlignedDisplays" +just before the first, and @Code "@EndAlignedDisplays" just after the +last. The alignment points are indicated by preceding them by the +symbol {@Code "^"}, so you aren't restricted to aligning at equals +signs. @Code "@BeginAlignedDisplays" and @Code "@EndAlignedDisplays" +cannot span across several sections or subsections: the equations +aligned by them must lie within a single large-scale structure symbol. +@PP +In our example of aligned and numbered displays, the two displays +were separated by some ordinary text. Very often, though, aligned +displays follow directly after each other. This is a problem, because +if you have one display directly following another there will be too +much vertical space between them. This problem was mentioned in +Section {@NumberOf displays}, and the recommended solution was to +use a list. However, there are no aligned or numbered (in this sense) +lists. +@PP +To solve this problem, 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" +} +You get the right spacing by placing {@Code "@DP"} symbols before, +between, and after each display; and you get to use the specialized +displays that you need. Raw and non-raw displays may be numbered and +aligned together. +@PP +Numbered displays are numbered automatically. Depending on where in +the document they appear, the number might include a chapter number +or section number, etc. This is controlled by options in the setup +file; for example, setting @Code "@ChapterNumInDisplays" to @Code Yes +ensures that numbered displays will be numbered afresh at the beginning +of each chapter, and that the number will include a chapter number. There +is also a @Code "@DisplayNumStyle" option which controls the style of +displays; the default value, {@Code "(num)"}, encloses the number in +parentheses as is conventional when numbering equations. +@PP +Every display symbol has an abbreviated form consisting of @Code "@" +followed by its capital letters only. For example, +@Code "@BeginAlignedDisplays" may be abbreviated to {@Code "@BAD"}, and +the display that has everything to {@Code "@RCAND"}. Owing to an +unfortunate clash between the initial letters of `raw' and `right', +@Code "@RightDisplay" and the other right displays have no abbreviations. +@End @Section diff --git a/doc/user/equ_intr b/doc/user/equ_intr new file mode 100644 index 0000000..882aaff --- /dev/null +++ b/doc/user/equ_intr @@ -0,0 +1,61 @@ +@Section + @Title { Introduction } +@Begin +@PP +The Lout definitions for the @Code "@Eq" symbol are accessed via a setup +file called {@Code "eq"}, which you must include at the start of your +document if +eq.file @Index { @Code "eq" file } +you want equations, like this: +@ID @OneRow @Code { +"@SysInclude { tbl }" +"@SysInclude { eq }" +"@SysInclude { doc }" +"@Doc @Text @Begin" +"..." +"@End @Text" +} +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"}, +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 +to be available inside, which means that equations may be freely mixed +with other symbols, without restriction. +@PP +Equations may appear within a paragraph of text, or they may be +displayed. {@Code "@Eq"}'s job is to produce an object containing the +equation; it neither knows nor cares where this equation goes. +@PP +To get an equation within a paragraph, simply place @Code "@Eq { ... }" +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" } +which is an abbreviation for {@Code "@OneCol @Eq"}. +@PP +To display an equation, use a display symbol like @Code "@IndentedDisplay" +or @Code "@CentredDisplay" (Section {@NumberOf displays}). For example, +@ID @Code "@CentredDisplay @Eq { int supp pi on 0 sin ` x = 0 }" +produces +@CentredDisplay @Eq { int supp pi on 0 sin ` x = 0 } +There are also symbols for aligned and numbered displays, which are +very commonly used with equations. These symbols are the subject of +Section {@NumberOf mathdisplays}. +@PP +In this chapter we show the Lout input at the left, and its +result at the right: +@ID { +@Code "@Eq { {x sup 2 + y sup 2} over 2 }" +|7ct +@Eq { {x sup 2 + y sup 2} over 2 } +} +Subsequent examples will omit the enclosing {@Code "@Eq { ... }"}. +@End @Section diff --git a/doc/user/equ_spac b/doc/user/equ_spac new file mode 100644 index 0000000..2a79fb1 --- /dev/null +++ b/doc/user/equ_spac @@ -0,0 +1,81 @@ +@Section + @Title { Spacing } +@Begin +@PP +There is a basic rule governing the use of white space characters (space, +tab, and newline) in the input to Lout: white space between two objects +affects the result; white space between a symbol and its parameter does +not. This is explained at length in Section {@NumberOf spaces}. +@PP +Although this rule is just right most of the time, it is not adequate +for equation formatting. Getting the horizontal spacing right in +equations is a very fiddly business, involving four different sizes of +space (zero, thin, medium, and thick), and different rules for spacing +within superscripts and subscripts to those applying outside, according +to a leading authority @Cite { $knuth1984tex }. {@Code "@Eq"} therefore +takes the spacing decisions upon itself, and consequently chooses to +ignore all white space in its input, even between two objects. (The +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 +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 +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 +@Code lessequal and short name {@Code "<="}: +@IL +@LI { +@Code "a lessequal b" +|7ct +@Eq { a lessequal b } +} +@LI { +@Code "a <= b" +|7ct +@Eq { a <= b } +} +@EL +{@Code "@Eq"} puts a thick space around relation symbols like {@Code "<="}, +relations @Index { relation symbols in equations } +a medium space around binary operator symbols like {@Code "+"}, and a thin +binary.op @Index { binary operators in equations } +space after punctuation symbols (@Code ";" and {@Code ","}); except that +punctuation @Index { punctuation 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. +@PP +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, +and thin, medium and thick space can be added using the following symbols: +@ID @Tab + vmargin { 0.5vx } + @Fmta { @Col A ! @Col B } +{ +@Rowa + A { @Code "`" } + B { {@Code "0.18f"} ({@Code "0.018f"} in subscripts, etc.) } +@Rowa + A { @Code "``" } + B { {@Code "0.24f"} ({@Code "0.024f"} in subscripts, etc.) } +@Rowa + A { @Code "```" } + B { {@Code "0.30f"} ({@Code "0.030f"} in subscripts, etc.) } +} +where @Code "1f" is the current font size. These symbols have low +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 } +which removes spaces from its right parameter; thus @Code "non <=" is +equivalent to {@Code "lessequal"}. There are also {@Code "rel"}, +{@Code "bin"}, and {@Code "punct"} symbols for telling {@Code "@Eq"} +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 new file mode 100644 index 0000000..bcfbeb3 --- /dev/null +++ b/doc/user/equ_summ @@ -0,0 +1,721 @@ +@Section + @Title { Summary } +@Begin +@PP +This section is a complete list of the symbols provided by +{@Code "@Eq"}. We divide them into auxiliary, parameterized, short names +(further divided into relations, binary operators, and punctuation), +and full names. The auxiliary symbols are: +@ID @Tab + vmargin { 0.5vx } + @Fmta { @Col A ! @Col B } +{ +@Rowa + A { @Code "`" } + B { Thin space } +@Rowa + A { @Code "``" } + B { Medium space } +@Rowa + A { @Code "```" } + B { Thick space } +@Rowa + A { @Code "bin x" } + B { Treat @Code x as a binary operator } +@Rowa + A { @Code "rel x" } + B { Treat @Code x as a relation } +@Rowa + A { @Code "punct x" } + B { Treat @Code x as a punctuation symbol } +@Rowa + A { @Code "non x" } + B { Remove spaces normally put into @Code x } +@Rowa + A { @Code "vctr x" } + B { Centre @Code x vertically } +@Rowa + A { @Code "big x" } + B { Make @Code x larger } +} +Here are all the parameterized symbols, shown in groups of equal +precedence, with the precedence itself at right: +@ID @OneRow lines @Break { +@Code "matrix pmatrix bmatrix brmatrix fmatrix cmatrix amatrix not" (100) +@Code "dot dotdot hat tilde vec dyad overbar underbar" (62) +@Code "sup sub tsub supp" (60) @Code "on ton" (61) +@Code "from to widefrom wideto" (58) +@Code "sqrt root" (56) +@Code "over frac" (54) +@Code "col lcol ccol rcol mcol" (52) +@Code "row axisrow" (50) +# @Code "above labove cabove rabove mabove" (52) +# @Code "nextcol" (50) +} +See Section {@NumberOf symbols} for examples of matrices. Here are some +examples of the other symbols: +@IL + +@LI { +@Code "x dot" +|7ct +@Eq { x dot } +} + +@LI { +@Code "x dotdot" +|7ct +@Eq { x dotdot } +} + +@LI { +@Code "x hat" +|7ct +@Eq { x hat } +} + +@LI { +@Code "x tilde" +|7ct +@Eq { x tilde } +} + +@LI { +@Code "x vec" +|7ct +@Eq { x vec } +} + +@LI { +@Code "x dyad" +|7ct +@Eq { x dyad } +} + +@LI { +@Code "x+y overbar" +|7ct +@Eq { x+y overbar } +} + +@LI { +@Code "x+y underbar" +|7ct +@Eq { x+y underbar } +} + +@EL +These marks are centred over the preceding object, except the last two +which are extended to the width of the object. +@IL + +@LI { +@Code "a sup b" +|7ct +@Eq {a sup b} +} + +@LI { +@Code "a sub b" +|7ct +@Eq {a sub b} +} + +@LI { +@Code "W tsub b" +|7ct +@Eq {W tsub b} +} + +@LI { +@Code "a supp b on c" +|7ct +@Eq {a supp b on c} +} + +@LI { +@Code "W supp b ton c" +|7ct +@Eq {W supp b ton c} +} + +@EL +Note that @Code "supp" and @Code "on" (or {@Code "ton"}) must be used +together as shown; @Code "tsub" and @Code "ton" are exactly like +@Code "sub" and @Code "on" except that the subscript is tucked in. +@IL + +@LI { +@Code "big sum from i" +|7ct +@Eq {big sum from i} +} + +@LI { +@Code "big prod to j" +|7ct +@Eq {big prod to j} +} + +@LI { +@Code { "{a, ... , z} widefrom" +"{90d @Rotate blbrace}" } +|7ct +@Eq { {a, ... , z} widefrom {90d @Rotate blbrace} } +} + +@LI { +@Code "{a, ... , z} wideto minus" +|7ct +@Eq { {a, ... , z} wideto minus } +} + +@EL +@Code "widefrom" and @Code "wideto" are like @Code "from" and +@Code "to" except that they horizontally scale the right parameter +to the width of the left. +@IL + +@LI { +@Code "sqrt {x over y}" +|7ct +@Eq { sqrt {x over y} } +} + +@LI { +@Code "3 root {x over y}" +|7ct +@Eq { 3 root {x over y} } +} + +@EL +The left parameter of @Code "root" may be any object. Here are +four ways to denote division: +@IL + +@LI { +@Code "2 over 3" +|7ct +@Eq { 2 over 3 } +} + +@LI { +@Code "2 frac 3" +|7ct +@Eq { 2 frac 3 } +} + +@LI { +@Code "2 div 3" +|7ct +@Eq { 2 div 3 } +} + +@LI { +@Code "2 slash 3" +|7ct +@Eq { 2 slash 3 } +} + +@EL +The @Code "div" symbol is a binary operator (see below), and +@Code "slash" is the full name for the @Code "/" character from +the Adobe Symbol font. You can't use @Code "/" itself, because +it is one of Lout's special symbols. +@PP +The following short names define relations (that is, they have a thick +space on each side): +@DP +ragged @Break { +"<" @Dbl @Eq { < } +">" @Dbl @Eq { > } +"=" @Dbl @Eq { = } +"<=" @Dbl @Eq { <= } +"prec" @Dbl @Eq { prec } +"preceq" @Dbl @Eq { preceq } +"<<" @Dbl @Eq { << } +"subset" @Dbl @Eq { subset } +"subseteq" @Dbl @Eq { subseteq } +"sqsubseteq" @Dbl @Eq { sqsubseteq } +"in" @Dbl @Eq { in } +"vdash" @Dbl @Eq { vdash } +"smile" @Dbl @Eq { smile } +"frown" @Dbl @Eq { frown } +">=" @Dbl @Eq { >= } +"succ" @Dbl @Eq { succ } +"succeq" @Dbl @Eq { succeq } +">>" @Dbl @Eq { >> } +"supset" @Dbl @Eq { supset } +"supseteq" @Dbl @Eq { supseteq } +"sqsupseteq" @Dbl @Eq { sqsupseteq } +"ni" @Dbl @Eq { ni } +"dashv" @Dbl @Eq { dashv } +"mid" @Dbl @Eq { mid } +"parallel" @Dbl @Eq { parallel } +"==" @Dbl @Eq { == } +"~" @Dbl @Eq { ~ } +"-~" @Dbl @Eq { -~ } +"asymp" @Dbl @Eq { asymp } +"~~" @Dbl @Eq { ~~ } +"=~" @Dbl @Eq { =~ } +"bowtie" @Dbl @Eq { bowtie } +"propto" @Dbl @Eq { propto } +"models" @Dbl @Eq { models } +"doteq" @Dbl @Eq { doteq } +"perp" @Dbl @Eq { perp } +"notsub" @Dbl @Eq { notsub } +"notin" @Dbl @Eq { notin } +"!=" @Dbl @Eq { != } +"<->" @Dbl @Eq { <-> } +"<--" @Dbl @Eq { <-- } +"-->" @Dbl @Eq { --> } +"up" @Dbl @Eq { up } +"down" @Dbl @Eq { down } +"<=>" @Dbl @Eq { <=> } +"<==" @Dbl @Eq { <== } +"==>" @Dbl @Eq { ==> } +"dblup" @Dbl @Eq { dblup } +"dbldown" @Dbl @Eq { dbldown } +":" @Dbl @Eq { : } +"::" @Dbl @Eq { :: } +":=" @Dbl @Eq { := } +} +@DP +These can be negated by preceding them with {@Code "not"}, as in +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): +@DP +ragged @Break { +"+" @Dbl @Eq { + } +"-" @Dbl @Eq { - } +"+-" @Dbl @Eq { +- } +"-+" @Dbl @Eq { -+ } +"setminus" @Dbl @Eq { setminus } +"cdot" @Dbl @Eq { cdot } +"times" @Dbl @Eq { times } +"*" @Dbl @Eq { * } +"circ" @Dbl @Eq { circ } +"div" @Dbl @Eq { div } +"cap" @Dbl @Eq { cap } +"cup" @Dbl @Eq { cup } +"uplus" @Dbl @Eq { uplus } +"sqcap" @Dbl @Eq { sqcap } +"sqcup" @Dbl @Eq { sqcup } +"triangleleft" @Dbl @Eq { triangleleft } +"triangleright" @Dbl @Eq { triangleright } +"wr" @Dbl @Eq { wr } +"bigcirc" @Dbl @Eq { bigcirc } +"bigtriangleup" @Dbl @Eq { bigtriangleup } +"bigtriangledown"@Dbl @Eq { bigtriangledown } +"vee" @Dbl @Eq { vee } +"wedge" @Dbl @Eq { wedge } +"oplus" @Dbl @Eq { oplus } +"ominus" @Dbl @Eq { ominus } +"otimes" @Dbl @Eq { otimes } +"oslash" @Dbl @Eq { oslash } +"odot" @Dbl @Eq { odot } +"dagger" @Dbl @Eq { dagger } +"daggerdbl" @Dbl @Eq { daggerdbl } +"amalg" @Dbl @Eq { amalg } +} +@DP +The following names define arrow symbols (no extra space): +@DP +ragged @Break { +"leftarrow" @Dbl @Eq { leftarrow } +"longleftarrow" @Dbl @Eq { longleftarrow } +"dblleftarrow" @Dbl @Eq { dblleftarrow } +"dbllongleftarrow" @Dbl @Eq { dbllongleftarrow } +"rightarrow" @Dbl @Eq { rightarrow } +"longrightarrow" @Dbl @Eq { longrightarrow } +"dblrightarrow" @Dbl @Eq { dblrightarrow } +"dbllongrightarrow" @Dbl @Eq { dbllongrightarrow } +"leftrightarrow" @Dbl @Eq { leftrightarrow } +"longleftrightarrow" @Dbl @Eq { longleftrightarrow } +"dblleftrightarrow" @Dbl @Eq { dblleftrightarrow } +{ 1.15i @Wide @HScale "dbllongleftrightarrow" } @Dbl @Eq { dbllongleftrightarrow } +"mapsto" @Dbl @Eq { mapsto } +"longmapsto" @Dbl @Eq { longmapsto } +"hookleftarrow" @Dbl @Eq { hookleftarrow } +"hookrightarrow" @Dbl @Eq { hookrightarrow } +"leadsto" @Dbl @Eq { leadsto } +"leftharpoonup" @Dbl @Eq { leftharpoonup } +"rightharpoonup" @Dbl @Eq { rightharpoonup } +"leftharpoondown" @Dbl @Eq { leftharpoondown } +"rightharpoondown" @Dbl @Eq { rightharpoondown } +"rightleftharpoons" @Dbl @Eq { rightleftharpoons } +"uparrow" @Dbl @Eq { uparrow } +"dbluparrow" @Dbl @Eq { dbluparrow } +"downarrow" @Dbl @Eq { downarrow } +"dbldownarrow" @Dbl @Eq { dbldownarrow } +"updownarrow" @Dbl @Eq { updownarrow } +"dblupdownarrow" @Dbl @Eq { dblupdownarrow } +"nearrow" @Dbl @Eq { nearrow } +"searrow" @Dbl @Eq { searrow } +"swarrow" @Dbl @Eq { swarrow } +"nwarrow" @Dbl @Eq { nwarrow } +} +@DP +The following names define punctuation symbols (thin space on the +right-hand side): +@DP +ragged @Break { +";" @Dbl @Eq { ; } +"," @Dbl @Eq { , } +"col" @Dbl @Eq { col } +} +@DP +The following symbols are used in ways typified by the large sum and +product symbols. In display equations they should be preceded by the +@Code "big" symbol: +@DP +ragged @Break { +"sum" @Dbl @Eq { sum } +"prod" @Dbl @Eq { prod } +"coprod" @Dbl @Eq { coprod } +@LP +"int" @Dbl @Eq { int } +"oint" @Dbl @Eq { oint } +"bcap" @Dbl @Eq { bcap } +@LP +"bcup" @Dbl @Eq { bcup } +"bvee" @Dbl @Eq { bvee } +"bwedge" @Dbl @Eq { bwedge } +@LP +"bodot" @Dbl @Eq { bodot } +"botimes" @Dbl @Eq { botimes } +"boplus" @Dbl @Eq { boplus } +@LP +"buplus" @Dbl @Eq { buplus } +} +@DP +The following symbols are defined so that they will appear in Roman, +as is conventional for them in equations: +@DP +ragged @Break { +"arccos" @Dbl @Eq { arccos } +"arcsin" @Dbl @Eq { arcsin } +"arctan" @Dbl @Eq { arctan } +"arg" @Dbl @Eq { arg } +"cos" @Dbl @Eq { cos } +"cosh" @Dbl @Eq { cosh } +"cot" @Dbl @Eq { cot } +"coth" @Dbl @Eq { coth } +"csc" @Dbl @Eq { csc } +"deg" @Dbl @Eq { deg } +"det" @Dbl @Eq { det } +"dim" @Dbl @Eq { dim } +"exp" @Dbl @Eq { exp } +"gcd" @Dbl @Eq { gcd } +"hom" @Dbl @Eq { hom } +"inf" @Dbl @Eq { inf } +"ker" @Dbl @Eq { ker } +"lg" @Dbl @Eq { lg } +"lim" @Dbl @Eq { lim } +"liminf" @Dbl @Eq { liminf } +"limsup" @Dbl @Eq { limsup } +"ln" @Dbl @Eq { ln } +"log" @Dbl @Eq { log } +"max" @Dbl @Eq { max } +"min" @Dbl @Eq { min } +"Pr" @Dbl @Eq { Pr } +"sec" @Dbl @Eq { sec } +"sin" @Dbl @Eq { sin } +"sinh" @Dbl @Eq { sinh } +"supr" @Dbl @Eq { supr } +"tan" @Dbl @Eq { tan } +"tanh" @Dbl @Eq { tanh } +"mod" @Dbl @Eq { mod } +} +@DP +The following symbols are also defined to ensure that they will appear +in Roman: +@DP +ragged @Break { +"0" @Dbl @Eq { 0 } +"1" @Dbl @Eq { 1 } +"2" @Dbl @Eq { 2 } +"3" @Dbl @Eq { 3 } +"4" @Dbl @Eq { 4 } +"5" @Dbl @Eq { 5 } +"6" @Dbl @Eq { 6 } +"7" @Dbl @Eq { 7 } +"8" @Dbl @Eq { 8 } +"9" @Dbl @Eq { 9 } +"!" @Dbl @Eq { ! } +"?" @Dbl @Eq { ? } +"%" @Dbl @Eq { % } +"(" @Dbl @Eq { ( } +")" @Dbl @Eq { ) } +"[" @Dbl @Eq { [ } +"]" @Dbl @Eq { ] } +} +@DP +The following symbols make good @Code atleft and @Code atright parameters +of the @Code matrix symbol: +@LP +@LP +ragged @Break { +"lpar" @Dbl @Eq { lpar } +"blpar" @Dbl @Eq { blpar } +"rpar" @Dbl @Eq { rpar } +"brpar" @Dbl @Eq { brpar } +"lbrack" @Dbl @Eq { lbrack } +"blbrack" @Dbl @Eq { blbrack } +"rbrack" @Dbl @Eq { rbrack } +"brbrack" @Dbl @Eq { brbrack } +"lbrace" @Dbl @Eq { lbrace } +"blbrace" @Dbl @Eq { blbrace } +"rbrace" @Dbl @Eq { rbrace } +"brbrace" @Dbl @Eq { brbrace } +"lfloor" @Dbl @Eq { lfloor } +"blfloor" @Dbl @Eq { blfloor } +"rfloor" @Dbl @Eq { rfloor } +"brfloor" @Dbl @Eq { brfloor } +"lceil" @Dbl @Eq { lceil } +"blceil" @Dbl @Eq { blceil } +"rceil" @Dbl @Eq { rceil } +"brceil" @Dbl @Eq { brceil } +"langle" @Dbl @Eq { langle } +"blangle" @Dbl @Eq { blangle } +"rangle" @Dbl @Eq { rangle } +"brangle" @Dbl @Eq { brangle } +} +@LP +@LP +Here are some miscellaneous symbols: +@DP +ragged @Break { +"hbar" @Dbl @Eq { hbar } +"Re" @Dbl @Eq { Re } +"Im" @Dbl @Eq { Im } +"partial" @Dbl @Eq { partial } +"infty" @Dbl @Eq { infty } +"prime" @Dbl @Eq { prime } +"nabla" @Dbl @Eq { nabla } +"surd" @Dbl @Eq { surd } +"top" @Dbl @Eq { top } +"bot" @Dbl @Eq { bot } +"dbar" @Dbl @Eq { dbar } +"triangle" @Dbl @Eq { triangle } +"backslash" @Dbl @Eq { backslash } +"forall" @Dbl @Eq { forall } +"exists" @Dbl @Eq { exists } +"neg" @Dbl @Eq { neg } +"circle" @Dbl @Eq { circle } +"square" @Dbl @Eq { square } +"ldots" @Dbl @Eq { ldots } +"cdots" @Dbl @Eq { cdots } +"vdots" @Dbl @Eq { vdots } +"ddots" @Dbl @Eq { ddots } +"del" @Dbl @Eq { del } +"grad" @Dbl @Eq { grad } +"..." @Dbl @Eq { ... } +",...," @Dbl @Eq { ,..., } +"half" @Dbl @Eq { half } +"third" @Dbl @Eq { third } +"'" @Dbl @Eq { ' } +"empty" @Dbl @Eq { empty } +} +@DP +Finally, here is the long list of full names from the Adobe Symbol font; +these are the same characters as you get with the @Code "@Sym" symbol +of Section {@NumberOf characters}, but within equations you don't need +to type {@Code "@Sym"}: +@DP +ragged @Break { +"space" @Dbl @Eq { space } +"exclam" @Dbl @Eq { exclam } +"universal" @Dbl @Eq { universal } +"numbersign" @Dbl @Eq { numbersign } +"existential" @Dbl @Eq { existential } +"percent" @Dbl @Eq { percent } +"ampersand" @Dbl @Eq { ampersand } +"suchthat" @Dbl @Eq { suchthat } +"parenleft" @Dbl @Eq { parenleft } +"parenright" @Dbl @Eq { parenright } +"asteriskmath" @Dbl @Eq { asteriskmath } +"plus" @Dbl @Eq { plus } +"comma" @Dbl @Eq { comma } +"minus" @Dbl @Eq { minus } +"period" @Dbl @Eq { period } +"slash" @Dbl @Eq { slash } +"zero" @Dbl @Eq { zero } +"one" @Dbl @Eq { one } +"two" @Dbl @Eq { two } +"three" @Dbl @Eq { three } +"four" @Dbl @Eq { four } +"five" @Dbl @Eq { five } +"six" @Dbl @Eq { six } +"seven" @Dbl @Eq { seven } +"eight" @Dbl @Eq { eight } +"nine" @Dbl @Eq { nine } +"colon" @Dbl @Eq { colon } +"semicolon" @Dbl @Eq { semicolon } +"less" @Dbl @Eq { less } +"equal" @Dbl @Eq { equal } +"greater" @Dbl @Eq { greater } +"question" @Dbl @Eq { question } +"congruent" @Dbl @Eq { congruent } +"Alpha" @Dbl @Eq { Alpha } +"Beta" @Dbl @Eq { Beta } +"Chi" @Dbl @Eq { Chi } +"Delta" @Dbl @Eq { Delta } +"Epsilon" @Dbl @Eq { Epsilon } +"Phi" @Dbl @Eq { Phi } +"Gamma" @Dbl @Eq { Gamma } +"Eta" @Dbl @Eq { Eta } +"Iota" @Dbl @Eq { Iota } +"thetaone" @Dbl @Eq { thetaone } +"Kappa" @Dbl @Eq { Kappa } +"Lambda" @Dbl @Eq { Lambda } +"Mu" @Dbl @Eq { Mu } +"Nu" @Dbl @Eq { Nu } +"Omicron" @Dbl @Eq { Omicron } +"Pi" @Dbl @Eq { Pi } +"Theta" @Dbl @Eq { Theta } +"Rho" @Dbl @Eq { Rho } +"Sigma" @Dbl @Eq { Sigma } +"Tau" @Dbl @Eq { Tau } +"Upsilon" @Dbl @Eq { Upsilon } +"sigmaone" @Dbl @Eq { sigmaone } +"Omega" @Dbl @Eq { Omega } +"Xi" @Dbl @Eq { Xi } +"Psi" @Dbl @Eq { Psi } +"Zeta" @Dbl @Eq { Zeta } +"bracketleft" @Dbl @Eq { bracketleft } +"therefore" @Dbl @Eq { therefore } +"bracketright" @Dbl @Eq { bracketright } +"perpendicular" @Dbl @Eq { perpendicular } +"underscore" @Dbl @Eq { underscore } +"radicalex" @Dbl @Eq { radicalex } +"alpha" @Dbl @Eq { alpha } +"beta" @Dbl @Eq { beta } +"chi" @Dbl @Eq { chi } +"delta" @Dbl @Eq { delta } +"epsilon" @Dbl @Eq { epsilon } +"phi" @Dbl @Eq { phi } +"gamma" @Dbl @Eq { gamma } +"eta" @Dbl @Eq { eta } +"iota" @Dbl @Eq { iota } +"phione" @Dbl @Eq { phione } +"kappa" @Dbl @Eq { kappa } +"lambda" @Dbl @Eq { lambda } +"mu" @Dbl @Eq { mu } +"nu" @Dbl @Eq { nu } +"omicron" @Dbl @Eq { omicron } +"pi" @Dbl @Eq { pi } +"theta" @Dbl @Eq { theta } +"rho" @Dbl @Eq { rho } +"sigma" @Dbl @Eq { sigma } +"tau" @Dbl @Eq { tau } +"upsilon" @Dbl @Eq { upsilon } +"omegaone" @Dbl @Eq { omegaone } +"omega" @Dbl @Eq { omega } +"xi" @Dbl @Eq { xi } +"psi" @Dbl @Eq { psi } +"zeta" @Dbl @Eq { zeta } +"braceleft" @Dbl @Eq { braceleft } +"bar" @Dbl @Eq { bar } +"braceright" @Dbl @Eq { braceright } +"similar" @Dbl @Eq { similar } +"Upsilonone" @Dbl @Eq { Upsilonone } +"minute" @Dbl @Eq { minute } +"lessequal" @Dbl @Eq { lessequal } +"fraction" @Dbl @Eq { fraction } +"infinity" @Dbl @Eq { infinity } +"florin" @Dbl @Eq { florin } +"club" @Dbl @Eq { club } +"diamond" @Dbl @Eq { diamond } +"heart" @Dbl @Eq { heart } +"spade" @Dbl @Eq { spade } +"arrowboth" @Dbl @Eq { arrowboth } +"arrowleft" @Dbl @Eq { arrowleft } +"arrowup" @Dbl @Eq { arrowup } +"arrowright" @Dbl @Eq { arrowright } +"arrowdown" @Dbl @Eq { arrowdown } +"degree" @Dbl @Eq { degree } +"plusminus" @Dbl @Eq { plusminus } +"second" @Dbl @Eq { second } +"greaterequal" @Dbl @Eq { greaterequal } +"multiply" @Dbl @Eq { multiply } +"proportional" @Dbl @Eq { proportional } +"partialdiff" @Dbl @Eq { partialdiff } +"bullet" @Dbl @Eq { bullet } +"divide" @Dbl @Eq { divide } +"notequal" @Dbl @Eq { notequal } +"equivalence" @Dbl @Eq { equivalence } +"approxequal" @Dbl @Eq { approxequal } +"ellipsis" @Dbl @Eq { ellipsis } +"arrowvertex" @Dbl @Eq { arrowvertex } +"arrowhorizex" @Dbl @Eq { arrowhorizex } +"carriagereturn"@Dbl @Eq { carriagereturn } +"aleph" @Dbl @Eq { aleph } +"Ifraktur" @Dbl @Eq { Ifraktur } +"Rfraktur" @Dbl @Eq { Rfraktur } +"weierstrass" @Dbl @Eq { weierstrass } +"circlemultiply"@Dbl @Eq { circlemultiply } +"circleplus" @Dbl @Eq { circleplus } +"emptyset" @Dbl @Eq { emptyset } +"intersection" @Dbl @Eq { intersection } +"union" @Dbl @Eq { union } +"propersuperset"@Dbl @Eq { propersuperset } +"reflexsuperset"@Dbl @Eq { reflexsuperset } +"notsubset" @Dbl @Eq { notsubset } +"propersubset" @Dbl @Eq { propersubset } +"reflexsubset" @Dbl @Eq { reflexsubset } +"element" @Dbl @Eq { element } +"notelement" @Dbl @Eq { notelement } +"angle" @Dbl @Eq { angle } +"gradient" @Dbl @Eq { gradient } +"registerserif" @Dbl @Eq { registerserif } +"copyrightserif"@Dbl @Eq { copyrightserif } +"trademarkserif"@Dbl @Eq { trademarkserif } +"product" @Dbl @Eq { product } +"radical" @Dbl @Eq { radical } +"dotmath" @Dbl @Eq { dotmath } +"logicalnot" @Dbl @Eq { logicalnot } +"logicaland" @Dbl @Eq { logicaland } +"logicalor" @Dbl @Eq { logicalor } +"arrowdblboth" @Dbl @Eq { arrowdblboth } +"arrowdblleft" @Dbl @Eq { arrowdblleft } +"arrowdblup" @Dbl @Eq { arrowdblup } +"arrowdblright" @Dbl @Eq { arrowdblright } +"arrowdbldown" @Dbl @Eq { arrowdbldown } +"lozenge" @Dbl @Eq { lozenge } +"angleleft" @Dbl @Eq { angleleft } +"registersans" @Dbl @Eq { registersans } +"copyrightsans" @Dbl @Eq { copyrightsans } +"trademarksans" @Dbl @Eq { trademarksans } +"summation" @Dbl @Eq { summation } +"parenlefttp" @Dbl @Eq { parenlefttp } +"parenleftex" @Dbl @Eq { parenleftex } +"parenleftbt" @Dbl @Eq { parenleftbt } +"bracketlefttp" @Dbl @Eq { bracketlefttp } +"bracketleftex" @Dbl @Eq { bracketleftex } +"bracketleftbt" @Dbl @Eq { bracketleftbt } +"bracelefttp" @Dbl @Eq { bracelefttp } +"braceleftmid" @Dbl @Eq { braceleftmid } +"braceleftbt" @Dbl @Eq { braceleftbt } +"braceex" @Dbl @Eq { braceex } +"angleright" @Dbl @Eq { angleright } +"integral" @Dbl @Eq { integral } +"integraltp" @Dbl @Eq { integraltp } +"integralex" @Dbl @Eq { integralex } +"integralbt" @Dbl @Eq { integralbt } +"parenrighttp" @Dbl @Eq { parenrighttp } +"parenrightex" @Dbl @Eq { parenrightex } +"parenrightbt" @Dbl @Eq { parenrightbt } +"bracketrighttp"@Dbl @Eq { bracketrighttp } +"bracketrightex"@Dbl @Eq { bracketrightex } +"bracketrightbt"@Dbl @Eq { bracketrightbt } +"bracerighttp" @Dbl @Eq { bracerighttp } +"bracerightmid" @Dbl @Eq { bracerightmid } +"bracerightbt" @Dbl @Eq { bracerightbt } +} +@DP +The names given are the same as Adobe's, as used by the @Code "@Sym" +symbol, except in a few places where the Adobe name contains a digit, +which is not possible for a symbol name in Lout. +@End @Section diff --git a/doc/user/equ_symb b/doc/user/equ_symb new file mode 100644 index 0000000..f56eca2 --- /dev/null +++ b/doc/user/equ_symb @@ -0,0 +1,357 @@ +@Section + @Title { Symbols } + @Tag { symbols } +@Begin +@PP +@Code "@Eq" prints characters in the fonts appropriate for mathematics: +@ID { +@Code "x - 2" +|7ct +@Eq { x-2 } +} +Here @Eq { x } is in Italic, @Eq { 2 } is in Roman, and @Eq { minus } is +from the Symbol font. The character @Code "-" is a @I symbol which +stands for @Eq {minus}, and @Code "2" is also a symbol, standing for +@Eq { 2 }. @Code "@Eq" includes a vast number of symbols: +@ID { +@Code "Omega delta int partial club" +|7ct +@Eq { Omega delta int partial club } +} +The summary at the end of this chapter has the complete list. +@PP +Symbols whose names are made from letters should be separated from each +other by at least one space or end of line, as was done above, or else +@Code "@Eq" will become confused: +@ID { +@Code "Omegadelta" +|7ct +@Eq { Omegadelta } +} +Symbols whose names are made from digits and punctuation characters can, +however, be run together with each other and with symbols made from +letters: +@ID { +@Code "Omega-delta<=2" +|7ct +@Eq { Omega-delta<=2 } +} +This rule applies throughout Lout (Section {@NumberOf spaces}). +@PP +Some symbols join objects together in mathematical ways: +@ID { +@Code "x sub 2" +|7ct +@Eq { x sub 2 } +} +Here the @Code "sub" symbol has taken the object just to its left, and +sub. @Index { @Code "sub" in 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 } +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 } +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: +@ID { +@Code { +"big sum from i=0 to n r sup i" +"= {r sup n+1 - 1} over r-1" +} +||7ct +@Eq { big sum from i=0 to n r sup i += {r sup n+1 - 1} over r-1 +} +} +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 } +@ID { +@Code "A supp b on a" +|7ct +@Eq { A supp b on a } +} +These two symbols should always be used together as shown. +@PP +Sometimes a subscript appears to be too far to the right, owing to +the slope of italic letters: in @Eq { W sub n }, for example. You +can fix this by using `tucked' subscripts, like this: +@IndentedList +@LI { +@Code "W tsub n" +|7ct +@Eq { W tsub n } +} +@LI { +@Code "W supp b ton a" +|7ct +@Eq { W supp b ton a } +} +@EndList +The @Code "tsub" and @Code "ton" symbols are exactly like @Code "sub" +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 +so is sensitive to the shape of the letters. +@PP +As usual in Lout, braces are used to group something into an indivisible +object. Leaving them out creates ambiguities: +@ID @Code "a sup b over c" +There are two possible interpretations for this: +@IndentedList +@LI { +@Code "{a sup b} over c" +|7ct +@Eq { {a sup b} over c } +} +@LI { +@Code "a sup {b over c}" +|7ct +@Eq { a sup {b over c} } +} +@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 +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 +symbols of equal precedence compete for an object, the association is +towards the left: +@ID { +@Code "a sup b sub 2" +|7ct +@Eq { a sup b sub 2 } +} +In this case it is more probable that the following right association +was actually wanted: +@ID { +@Code "a sup { b sub 2 }" +|7ct +@Eq { a sup { b sub 2 } } +} +When in doubt, use braces to make the grouping clear. +@PP +White space between two objects is considered to be a symbol with +precedence 7, which is lower than the precedence of any @Code "@Eq" +symbol; but if the two objects are immediately adjacent and neither is +enclosed in braces the precedence is 102, which is higher than the +precedence of any @Code "@Eq" symbol. Compare these three examples: +@IL +@LI { +@Code "big sum from i=0 to n" +|7ct +@Eq { big sum from i=0 to n } +} +@LI { +@Code "big sum from {i = 0} to n" +|7ct +@Eq { big sum from {i = 0} to n } +} +@LI { +@Code "big sum from i = 0 to n" +|7ct +@Eq { big sum from i = 0 to n } +} +@EL +and you will see that some care is needed on this point. Braces can +always be used to override precedence and associativity, and when in +doubt the easiest course is to insert them. Although Lout allows +symbols to associate towards the left or right, @Code "@Eq" chooses +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 } +@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" +"}" +} +||9ct +@Eq { +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 +} +} +} +The @Code atleft and @Code atright options place vertically scaled +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 { ) }" +} +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 +@Code row symbols; each row is a sequence of objects introduced by +@Code col symbols. +@FootNote { +Older versions of Lout use different symbols, {@Code "above"} and +{@Code "nextcol"}, at this point. For backward compatibility these +symbols are still available, but they are obsolete and no longer documented. +} +The @Code row and @Code col symbols have low precedence, but not +as low as white space between two objects. Therefore, unless the +entries in the array are very simple, it is safest to enclose each of +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, +@Code ccol meaning the same as {@Code col}, @Code rcol for +right-justified entries, and @Code mcol for alignment along column +marks. Each column may contain entries of different kinds, except +that @Code mcol does not work well with any other sort. +@PP +When several matrices appear side by side, slight differences in height +can cause an unsightly appearance: +@ID @Eq { +matrix + atleft { ( } + atright { ) } +{ + row col a sub 11 col a sub 12 + row col a sub 21 col a sub 22 +} +matrix + atleft { ( } + atright { ) } +{ + row col b sub 11 col b sub 12 + row col b sub 21 col b sub 22 +} += +matrix + atleft { ( } + atright { ) } +{ + row col c sub 11 col c sub 12 + row col c sub 21 col c sub 22 +} +} +To assist in resolving this problem, the @Code "matrix" symbol has +a @Code "strut" option, which causes a strut to be inserted into +every row, guaranteeing that every row has height at least equal +to the height of the strut. By using +@ID @Code { +"matrix" +" strut { Yes }" +"..." +} +in each of the three matrices above, the result is improved to +@ID @Eq { +matrix + atleft { ( } + atright { ) } + strut { Yes } +{ + row col a sub 11 col a sub 12 + row col a sub 21 col a sub 22 +} +matrix + atleft { ( } + atright { ) } + strut { Yes } +{ + row col b sub 11 col b sub 12 + row col b sub 21 col b sub 22 +} += +matrix + atleft { ( } + atright { ) } + strut { Yes } +{ + row col c sub 11 col c sub 12 + row col c sub 21 col c sub 22 +} +} +By default, the strut has height @Code "0.5f" (half the current font +size) both above and below the axis of the row. This can be changed +by giving any length as the value of the @Code "strut" option: +@Code "strut { 2.0c }" for two centimetres above and below +the axis, and so on. +@PP +Some symbols have been added which produce `matrices' with commonly needed +@Code atleft and @Code atright options already set for you. Here are +these symbols, on the left, with the equivalent @Code matrix symbol +and, on the right, the result produced: +@ID @Tab + @Fmta { @Col @Code A ! @Col ! @Col @Code B ! @Col ! @Col C } +{ +@Rowa + A { "pmatrix" } + B { "matrix atleft { ( } atright { ) } { M }" } + C { @Eq { pmatrix { M } } } +@Rowa + A { "bmatrix" } + B { "matrix atleft { blbrack } atright { brbrack } { M }" } + C { @Eq { bmatrix { M } } } +@Rowa + A { "brmatrix" } + B { "matrix atleft { blbrace } atright { brbrace } { M }" } + C { @Eq { brmatrix { M } } } +@Rowa + A { "fmatrix" } + B { "matrix atleft { blfloor } atright { brfloor } { M }" } + C { @Eq { fmatrix { M } } } +@Rowa + A { "cmatrix" } + B { "matrix atleft { blceil } atright { brceil } { M }" } + C { @Eq { cmatrix { M } } } +@Rowa + A { "amatrix" } + B { "matrix atleft { blangle } atright { brangle } { M }" } + C { @Eq { amatrix { M } } } +} +For example: +@ID { +@Code { +"fmatrix { (n+1) over 2 }" +} +|7ct +@Eq { +fmatrix { (n+1) over 2 } +} +} +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 +option, which controls the amount of space inserted by the symbol: +@IL +@LI { +@Code "x over y" +|7ct +@Eq { x over y } +} +@LI { +6c @Wide @Code "x over gap { 3p } y" +|7ct +@Eq { x over gap { 3p } y } +} +@EL +@Code "@Eq" usually gets the spacing right without help. +@End @Section diff --git a/doc/user/equ_tequ b/doc/user/equ_tequ new file mode 100644 index 0000000..bbb1d20 --- /dev/null +++ b/doc/user/equ_tequ @@ -0,0 +1,41 @@ +@Section + @Title { An alternative version that uses @TeX's fonts } + @Tag { teq } +@Begin +@PP +There is an alternative version of the @Code "@Eq" symbol that +tex.mathfonts @SubIndex { mathematical fonts } +uses fonts taken from the @TeX document formatting +system. These fonts are said to produce better-looking +mathematics than the Adobe Systems Symbol font used by the +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 +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 +rest of Lout, although you can get them from the same place (see the +preface of this guide). +@PP +Once these files are installed, you change from the standard +@Code "@Eq" symbol to the @TeX version by changing the initial +@Code "@SysInclude { eq }" to {@Code "@SysInclude { teq }"}. Do +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. +@PP +It is possible to gain access to characters in the @TeX +fonts that are not accessible directly from {@Code "@Eq"}, mainly +script capitals and bold-italic Greek letters. For example, you can +use @Code "{cmsy Base} @Font @Char \"A\"" to get a script A, and +@Code "{cmmi Bold} @Font @Char \"pi\"" to get a bold-italic +{@Sym pi}. For the full story, consult file @Code "teq" in the +Lout system include directory for the names of these fonts, and then +look in Lout's font directory for their font metrics files, which +show the names and encodings of all the characters. +@End @Section diff --git a/doc/user/equ_vert b/doc/user/equ_vert new file mode 100644 index 0000000..1595ed8 --- /dev/null +++ b/doc/user/equ_vert @@ -0,0 +1,164 @@ +@Section + @Tag { vpos } + @Title { Vertical positioning } +@Begin +@PP +Every equation and every object within every equation has an +@I axis running through it which is used to position it vertically +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 }, +but we'll stick with axis. Here are some examples with the axis +shown as a dashed line: +@ID { +@ShowHMark @Eq { x sup 2 } +||2c +@ShowHMark @Eq { non + } +||2c +@ShowHMark @Eq { @ExA } +} +When these objects are placed adjacent to one another, their +axes are merged, giving the correct vertical positioning: +@ID @ShowHMark @Eq { x sup 2 + @ExA } +Most of the time you do not need to think about vertical +positioning, because for most objects there is just one +sensible place for the axis to go, and Lout puts it there. +@PP +Matrices and the delimiters that enclose them are the two +exceptions. Lout makes the axis of a matrix pass through +its exact centre, and it shifts the axes of delimiters +so that they exactly enclose the thing delimited. These +choices are never disastrous, but there are other possibilities +that might be better sometimes. +@PP +The axis of a matrix could reasonably be set to the axis +of any of its rows: +@ID { +@ShowHMark @Eq { +matrix userow { yes } { + axisrow col { x sup 3 } col { y sup 3 } col { z sup 3 } + row col { x sup 2 } col { y sup 2 } col { z sup 2 } + row col { x } col { y } col { z } +} +} +||2c +@ShowHMark @Eq { +matrix userow { yes } { + row col { x sup 3 } col { y sup 3 } col { z sup 3 } + axisrow col { x sup 2 } col { y sup 2 } col { z sup 2 } + row col { x } col { y } col { z } +} +} +||2c +@ShowHMark @Eq { +matrix userow { yes } { + row col { x sup 3 } col { y sup 3 } col { z sup 3 } + row col { x sup 2 } col { y sup 2 } col { z sup 2 } + axisrow col { x } col { y } col { z } +} +} +} +Alternatively, it could be set to where Lout usually places it, +through the exact centre: +@ID { +@ShowHMark @Eq { +matrix { + row col { x sup 3 } col { y sup 3 } col { z sup 3 } + row col { x sup 2 } col { y sup 2 } col { z sup 2 } + row col { x } col { y } col { z } +} +} +} +Delimiters could reasonably keep the axes that they naturally +have (approximately through their centres, but not exactly): +@ID { +@ShowHMark @Eq { pmatrix userow { yes } shiftdelim { no } { @ExA } } +} +or they could have their axes moved in the way that Lout usually does, +to the point which allows them to evenly cover the thing delimited: +@ID { +@ShowHMark @Eq { pmatrix userow { yes } { @ExA } } +} +Altogether then there are four possibilities when these two alternatives +interact: +@CD lines @Break @Tab + @Fmta { @Col 0.5w @VShift A ! @Col ! @Col B ! @Col ! @Col C } +{ +@Rowa + A { } + B { Matrix axis +uses row axis } + C { Matrix axis passes +through centre } +@Rowa +@Rowa + A { Delimiter +keeps its axis } + B { @ShowHMark @Eq { pmatrix userow {yes} shiftdelim {no } { @ExA } } } + C { @ShowHMark @Eq { pmatrix userow {no } shiftdelim {no } { @ExA } } } +@Rowa +@Rowa + A { Delimiter +axis shifted } + B { @ShowHMark @Eq { pmatrix userow {yes} shiftdelim {yes} { @ExA } } } + C { @ShowHMark @Eq { pmatrix userow {no } shiftdelim {yes} { @ExA } } } +} +To supply these possibilities, the @Code "matrix" symbol and all +its variants (@Code "pmatrix" etc.) have two options whose +values may be {@Code "yes"} or {@Code "no"}: +@ID @Code { +"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 +centre the axis instead. The @Code "shiftdelim" option +determines whether the axis of the delimiter will be shifted +so that the delimiter evenly covers the thing delimited; the +default is to do this. +@PP +If @Code "userow" is {@Code "yes"}, the next question is +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"}: +@ID @Code @Tab + vmargin { 0.5vx } + hmargin { 1s } + @Fmta { @Col A ! @Col ! @Col B ! @Col ! @Col C ! @Col ! @Col D ! @Col } + @Fmtb { @Col A ! @Col " col {" ! @Col B ! @Col "} col {" ! @Col C ! @Col "} col {" ! @Col D ! @Col "}" } +{ +@Rowa + A { "matrix userow { yes } {" &0io } +@Rowb + A { " row" } + B { "x sup 3" } + C { "y sup 3" } + D { "z sup 3" } +@Rowb + A { " axisrow" } + B { "x sup 2" } + C { "y sup 2" } + D { "z sup 2" } +@Rowb + A { " row" } + B { "x" } + C { "y" } + D { "z" } +@Rowa + A { "}" } +} +The result of this is +@ID @ShowHMark @Eq { +matrix userow { yes } { + row col { x sup 3 } col { y sup 3 } col { z sup 3 } + axisrow col { x sup 2 } col { y sup 2 } col { z sup 2 } + row col { x } col { y } col { z } +} +} +with the axis through the second row as desired. +@End @Section diff --git a/doc/user/fmt b/doc/user/fmt new file mode 100644 index 0000000..ffd5e7f --- /dev/null +++ b/doc/user/fmt @@ -0,0 +1,16 @@ +@Chapter + @Title { Changing the Overall Format } + @Tag { changes } +@Begin +@LP +The symbols of Lout make many decisions behind the scenes. Even the +humble @Code "@PP" symbol has to decide how much vertical space to +leave, and how far to indent the first line of the paragraph. How to +change these decisions is the subject of this chapter. +@BeginSections +@Include { fmt_setu } +@Include { fmt_size } +@Include { fmt_marg } +@Include { fmt_head } +@EndSections +@End @Chapter diff --git a/doc/user/fmt_head b/doc/user/fmt_head new file mode 100644 index 0000000..77cbada --- /dev/null +++ b/doc/user/fmt_head @@ -0,0 +1,313 @@ +@Section + @Title { Page numbers and running headers } + @Tag { headers } +@Begin +@PP +A @I { page header } is a line at the top of a page containing a page +page.header @Index { page header } +running.header @Index { running header } +number or running title. A @I { page footer } is a similar line at +page.footer @Index { page footer } +the bottom of a page. This section describes the setup file options +that control the appearance of page headers and footers. +@PP +There are four basic styles, selected by the @Code "@PageHeaders" option: +page.headers @Index @Code "@PageHeaders" +@ID @Tab + @Fmta { @Col @Code { "@PageHeaders {" A "}" } ! @Col B } +{ +@Rowa + A { None } + B { No page headers, no page footers. } +@Rowa + A { Simple } + B { No footers, and a centred page number between hyphens for +header on every page whose number is not 0 or 1. } +@Rowa + A { Titles } + B { Full running titles as in the present document. } +@Rowa + A { NoTitles } + B { Page numbers placed as for @Code { Titles }, but with the +titles themselves blanked out. } +} +@Code Titles and @Code NoTitles use Lout's cross-referencing machinery, +so will require a few runs to settle down. @Code None and @Code Simple +do not, so they work first time and may be used with the @Code "-s" +command line flag. Section {@NumberOf cross} has a fuller discussion +of these ramifications of cross referencing. +@PP +The next step is to set the page numbers, using +the @Code "@PageNumbers" and @Code "@FirstPageNumber" options. There +page.numbers @Index @Code "@PageNumbers" +are two useful values for {@Code "@PageNumbers"}: +@ID @Tab + @Fmta { @Col @Code { "@PageNumbers {" A "}" } ! @Col B } +{ +@Rowa + A { Arabic } + B { Arabic page numbers } +@Rowa + A { Roman } + B { Lower-case Roman page numbers } +} +although the full range of choices is {@Code "None"}, {@Code "Arabic"}, +{@Code "Roman"}, {@Code "UCRoman"}, {@Code "Alpha"}, and +{@Code "UCAlpha"}. @Code "@FirstPageNumber" is the number of the +first.page.number @Index @Code "@FirstPageNumber" +first page. Its default value is of course {@Code 1}, although +@ID @Code "@FirstPageNumber { 0 }" +might be useful if the first page is really an unnumbered cover +sheet. @Code "@FirstPageNumber" must be an Arabic number even if +@Code "@PageNumbers" is set to something other than {@Code "Arabic"}. +@PP +Some document types, such as books and technical reports with cover +sheets, have a separate introductory +sequence of pages preceding the main sequence. For the page numbers on +introductory pages there are two options, @Code "@IntroPageNumbers" +intro.page.numbers @Index @Code "@IntroPageNumbers" +intro.first.page.number @Index @Code "@IntroFirstPageNumber" +and {@Code "@IntroFirstPageNumber"}, which are exactly analogous to +@Code "@PageNumbers" and {@Code "@FirstPageNumber"}. It is traditional +to number introductory pages using Roman numerals, so @Code Roman is +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 }" +} +The remainder of this section goes beyond these basic choices to explain +how to change the detailed appearance of page headers +and footers. Inevitably it gets quite a lot harder. +@PP +Pages are classified by the page header options in three ways: +@NumberedList +@LI { @I { Odd vs. even }. The first page is odd, the second is even, +odd.pages @Index { odd and even pages } +the third is odd, and so on. If @Code "@FirstPageNumber" is set to +an even number, the first page will have that number, but it will still +be classified as odd. } +@LI { @I { Start vs. non-start }. A start page is the first page of +start.pages @Index { start and non-start pages } +some major part of the document (a chapter, say); other pages are +non-start. The @Code { Simple } header type uses a simpler +definition: a page whose number is 0 or 1 is a start page, all others +are non-start. } +@LI { @I { Intro vs. non-intro }. Intro pages form a separate sequence of +intro.pages @Index { intro and non-intro pages } +pages that precede the main (non-intro) sequence. They typically contain +prefatory material such as a title page, preface, and table of contents. +In a book there will always be an even number of Intro pages, even if +it means that the last one is empty. } +@EndList +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. +@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 }" +} +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 }" +} +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 +will be explained now. +@PP +The full set of symbols of the BasicSetup package can be used +when setting page header options (and indeed any of the options +of the @Code "@BasicSetup" @Code "@Use" clause package), as well as +symbols from special-purpose +packages that have been included before this setup file. This means +you can use any symbol you might reasonably expect to. But footnotes and +floating figures and tables, for example, are not from BasicSetup so +cannot be used. +@PP +There are five symbols of special relevance to page headers and +footers: {@Code "@Null"}, {@Code "@Centre"}, {@Code "@Center"}, +{@Code "@Right"}, and {@Code "@PageNum"}. +@PP +The @Code "@Null" symbol is similar to the empty object in printing as +null. @Index @Code "@Null" +nothing, but in addition it removes the vertical space that ordinarily +separates the header line from the page body. If there is no header +there should be no vertical space either, so always use @Code "@Null" +rather than the empty object in header and footer options. +@PP +@Code "@Centre" and @Code "@Center" centre the following object, and +centre. @Index @Code "@Centre" +center. @Index @Code "@Center" +right. @Index @Code "@Right" +@Code "@Right" right-justifies it: +@ID @Code "at left @Centre { - 27 - } @Right { at right }" +produces +@QD @HExpand { at left @Centre { - 27 - } @Right { at right } } +The objects should be enclosed in braces if they contain spaces. +@PP +The @Code "@PageNum" symbol produces the number of the current page, in +page.num. @Index @Code "@PageNum" +Arabic, Roman, etc. as specified by the @Code "@PageNumbers" or +@Code "@IntroPageNumbers" option. @Code "@PageNum" is available only +within page header and footer options. +@PP +At this point you might like to pause and verify that the default +values of the sixteen options given above produce what we said they +would: no footers, and a centred page number between hyphens on every +page whose number is not 0 or 1. It should be clear now what to do if +you want to remove the hyphens, move the numbers to the page footer, +make them bold, have them at the left on even pages and at the right on +odd pages, and so on. +@PP +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 }" +} +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 }" +} +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 +except that @Code Running is added to each. Remember that a start +page is now one that begins a major part of the document. +@PP +In addition to the symbols described earlier for simple page headers +and footers, these running header options may contain the symbols +{@Code "@MajorNum"}, {@Code "@MajorTitle"}, {@Code "@MinorNum"}, +{@Code "@MinorTitle"}, {@Code "@DotSep"}, {@Code "@NoDotSep"}, +{@Code "@DotJoin"}, {@Code "@NoDotJoin"}, {@Code "@DashJoin"}, +and {@Code "@NumSep"} described below. +major.num @Index @Code "@MajorNum" +major.title @Index @Code "@MajorTitle" +minor.num @Index @Code "@MinorNum" +minor.title @Index @Code "@MinorTitle" +@PP +The exact values of {@Code "@MajorNum"}, {@Code "@MajorTitle"}, +{@Code "@MinorNum"}, and {@Code "@MinorTitle"} depend on the document +type, but they are intended to describe what is on the current page. Here +are some values typical of books: +@ID @Tab + @Fmta { @Col @Code A ! @Col @Code B } + vmargin { 0.5vx } +{ +@Rowa + A { "@MajorNum" } + B { Chapter 2 } +@Rowa + A { "@MajorTitle" } + B { Adding Structure to Documents } +@Rowa + A { "@MinorNum" } + B { 2.7 } +@Rowa + A { "@MinorTitle" } + B { Tables of contents } +} +It is not possible to change the values assigned to these symbols, but +the sixteen options allow you to choose whether to use them and how to +arrange them, in the usual way. +@PP +The @Code "@DotSep" symbol consumes the objects to its left and right +dot.sep @Index @Code "@DotSep" +and produces them separated by a dot and two spaces: +@ID @Code "@MinorNum @DotSep @MinorTitle" +is the same as +@ID @Code "@MinorNum. @MinorTitle" +However, if either object is empty, the dot and two spaces are +omitted. It's a fine point, needed mainly for unnumbered chapters +and sections. @Code "@DotJoin" is the same as @Code "@DotSep" but +dot.join @Index @Code "@DotJoin" +without the two spaces. @Code "NoDotSep" is the same as +nodot.sep @Index @Code "@NoDotSep" +@Code "@DotSep" but leaving out the dot, @Code "@NoDotJoin" is the same +nodot.join @Index @Code "@NoDotJoin" +as @Code "@DotJoin" but again leaving out the dot, and @Code "@DashJoin" +dash.join @Index @Code "@DashJoin" +is the same as @Code "@DotJoin" except that `--' replaces the dot. +@PP +Lout uses @Code "@DotSep" between numbers and titles by default. To +get rid of all dots between numbers and titles it is necessary to +change all occurrences of @Code "@DotSep" in the setup file to +{@Code "@NoDotSep"}. There are about ten occurrences, depending +on the setup file. +@PP +@Code "@NumSep" {@PageMark numsep} is similar to @Code "@NoDotSep" +except that one space +num.sep @Index @Code "@NumSep" +hungarian @Index { Hungarian and @Code "@NumSep" } +is used, not two, and also the order of the two parts is reversed and +a dot is added if the current language is Hungarian (apparently +Hungarians write `3. Table' where other people write `Table 3'). +@Code "@NumSep" is used behind the scenes in a variety of places. +@PP +The present document was produced using @Code "@PageHeaders { Titles }" +with the default values of the sixteen options unchanged, as you might +like to verify. @Code "@PageHeaders { NoTitles }" is identical to +@Code "@PageHeaders { Titles }" except that {@Code "@MajorNum"}, +{@Code "@MajorTitle"}, {@Code "@MinorNum"}, and {@Code "@MinorTitle"} +are always replaced by empty objects. The description given at the +beginning of this section, `like @Code "Titles" but with the titles +blanked out,' is therefore accurate. +@PP +There is a @Code "@StructPageNums" setup file option that produces +structpagenums. @Index @Code "@StructPageNums" +structured page numbers when it is changed to {@Code Yes}; that is, +page numbers that include a section number, subsection number, and so +on. Precisely which structure numbers are included is determined by the +@Code "@SectionNumInRunners" option and its relatives. @Code "@PageHeaders" +must be @Code Titles when structured page numbers are used, and it is +probably best to set @Code "@SectionGap" and some similar options to +{@Code "2b"} (meaning new page) as well. The @Code "@NumberSeparator" +setup file option (Section {@NumberOf largescale}) affects the format +of the structured page numbers. +@End @Section diff --git a/doc/user/fmt_marg b/doc/user/fmt_marg new file mode 100644 index 0000000..1b82d41 --- /dev/null +++ b/doc/user/fmt_marg @@ -0,0 +1,121 @@ +@Section + @Title { Page margins, page boxes, and page backgrounds } + @Tag { margins } +@Begin +@PP +There are six options for setting the top and bottom margins on each +margins. @RawIndex { margins } +margins.in.pages @SubIndex { in pages } +top.margin @Index @Code "@TopMargin" +foot.margin @Index @Code "@FootMargin" +odd.left.margin @Index @Code "@OddLeftMargin" +odd.right.margin @Index @Code "@OddRightMargin" +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 }" +} +When setting these options you must ensure that +@ID @Eq { @Code "@OddLeftMargin" + @Code "@OddRightMargin" = +@Code "@EvenLeftMargin" + @Code "@EvenRightMargin" } +In other words, the total margin on odd pages must be the same as on +even pages. +@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 }" +} +You get boxes by changing the @Code "@PageBoxType" option: +page.box.type @Index @Code "@PageBoxType" +@ID @OneRow @Tab + @Fmta { @Col @Code A ! @Col @CC B } +{ +@Rowa + A { "@PageBoxType { None }" } + B { (no box) } +@Rowa +@Rowa + A { "@PageBoxType { Box }" } + B { @Box 1.0c @Wide 1.4c @High } +@Rowa +@Rowa + A { "@PageBoxType { CurveBox }" } + B { @CurveBox 1.0c @Wide 1.4c @High } +@Rowa +@Rowa + A { "@PageBoxType { ShadowBox }" } + B { @ShadowBox 1.0c @Wide 1.4c @High } +} +Page boxes reduce the amount of space available to the page contents, +so your columns will become somewhat narrower and shorter when you +introduce them. +@PP +The {@Code "@PageBoxMargin"}, {@Code "@PageBoxLineWidth"}, +{@Code "@PageBoxPaint"}, and {@Code "@PageBoxShadow"} options affect +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 }" +} +draws a curved box, painted grey, around each page, with a one +centimetre margin between its boundary and the page contents. If the +left margin is 2.5 centimetres, say, this gives a total left margin +from the page edge to the page contents of 3.5 centimetres. +@PP +Finally, it is possible to have something other than the usual white +background on the page, using the @Code "@PageBackground" option: +page.background @Index @Code "@PageBackground" +@ID @Code { +"@PageBackground { @Scale 60d @Rotate lightgrey @Colour DRAFT }" +} +The value of the option is an object which is drawn on each page, +within the margins, before the page contents are drawn. This +example draws a large word DRAFT in light grey diagonally across each +page: +@ID @Box margin { 0c } 0.2 @Scale @IncludeGraphic draft.eps +You have to find a suitable angle by experiment. As Section +{@NumberOf scaling} explains, @Code "@Scale" with no scale factor +only takes account of the available horizontal space, not the +available vertical space, so if your angle is too steep the result +will be too tall for the page and you will get a regrettably obscure +warning message about a `broken size constraint.' The solution is +to try a smaller angle. +@PP +Another useful page background draws marks to show where the margins +boundarymarks @Index @Code "@BoundaryMarks" +cut.marks @Index { cut marks } +lie: +@ID @Code "@PageBackground { @BoundaryMarks }" +produces something like this around each page: +@DP @DP +@ID { |@DisplayIndent 3c @High 2c @Wide @HExpand @VExpand @BoundaryMarks } +@DP @DP +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 }" +"}" +} +This shows the default values: 0.2 points for line width, +0.5 centimetres for the others. +@End @Section diff --git a/doc/user/fmt_setu b/doc/user/fmt_setu new file mode 100644 index 0000000..6e1bb05 --- /dev/null +++ b/doc/user/fmt_setu @@ -0,0 +1,210 @@ +@Section + @Title { Setup files } + @Tag { setup } +@Begin +@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 } +sysinclude. @Index @Code "@SysInclude" +system.include @Index { system include directory } +doc.file @Index { @Code "doc" file } +@ID @Code "@SysInclude { doc }" +The setup file's name in this example is @Code { doc }, and the @Code Sys +in @Code "@SysInclude" means that @Code doc is stored in the @I { Lout +system include directory }, which is where all the standard setup files +are kept. Each document type (Chapter {@NumberOf types}) has its own +setup file, and each specialized package (for equations, tables, and +so on) has a setup file too. +@PP +To change the overall format of a document, you need to create your own +setup file by copying and modifying one of the standard ones. We will +assume that you are making an ordinary document, with the @Code doc +setup file, but a similar procedure works for any setup file. +@PP +You first need to find out the name of the Lout system include +directory, by typing +@ID @Code "lout -V" +in Unix. This causes Lout to print out various facts about itself. Then, +supposing that this tells you that the Lout system include directory +is @Code { "/usr/lout/include" }, type the Unix command +@ID @Code "cp /usr/lout/include/doc mydoc" +to place a copy of the @Code doc setup file in your directory, +mydoc.file @Index { @Code "mydoc" file } +renaming it @Code {mydoc}. Since @Code "doc" is read-only, you may +also need to change the mode of @Code mydoc to be writable (by +@Code "chmod +w mydoc" in Unix). Now replace +@ID @Code "@SysInclude { doc }" +at the beginning of your document by +@ID @Code "@Include { mydoc }" +and Lout will read @Code mydoc as the setup file instead of +@Code { doc }. Since the two files are at present identical, this has +changed nothing so far; but now any changes you make to @Code mydoc +will affect your document. Notice the use of @Code "@Include" +rather than @Code { "@SysInclude" }; @Code "@Include" will search your +current directory for @Code { mydoc }, whereas @Code "@SysInclude" +searches only the system directory. +@PP +The remainder of this section is a tour through @Code {doc}, +explaining the various parts and how to modify them. The first lines +that actually do anything are these: +@ID @OneRow @Code { +"@SysInclude { fontdefs }" +"@SysInclude { langdefs }" +"@SysInclude { bsf }" +"@SysInclude { dsf }" +"@SysInclude { docf }" +} +We already know that @Code "@SysInclude" causes Lout to read a file from +the Lout system include directory. Files @Code fontdefs and @Code langdefs +fontdefs.file @Index { @Code "fontdefs" file } +langdefs.file @Index { @Code "langdefs" file } +tell Lout what fonts and languages there are. Files @Code "bsf" and +@Code "dsf" contain +bsf.file @Index { @Code "bsf" file } +dsf.file @Index { @Code "dsf" file } +the definitions of the BasicSetup and DocumentSetup packages, in which +all the symbols of the first two chapters of this guide are defined. File +@Code "docf" contains extra definitions specific to +docf.file @Index { @Code "docf" file } +ordinary documents (as distinct from technical reports, books, or the +other document types of Chapter {@NumberOf types}). So this line +will be different in the setup files for those other types. +@PP +The next line is +@ID @Code { +"@Include { mydefs }" +} +This searches your current directory for a file called @Code { mydefs }, +which (as Section {@NumberOf definitions} explains) is intended to hold +your own personal set of definitions of new symbols. It does no harm +if there is no @Code "mydefs" file in your current directory, because +@Code "@Include" then searches the Lout system include directory for +it, and there is an empty @Code mydefs file there. When using your own +setup file, you might prefer to delete @Code "@Include { mydefs }" and +put your definitions in its place, so that you have one file of setup +material rather than two. +@PP +Next we come to the BasicSetup @Code "@Use" clause. It looks like this: +use. @Index @Code "@Use" +@ID @OneRow @Code @Verbatim { +@Use { @BasicSetup + # @InitialFont { Times Base 12p } + # @InitialBreak { {adjust 1.20fx hyphen} @OrIfPlain {ragged 1fx nohyphen} } + # @InitialSpace { lout } + # @InitialLanguage { English } + # @InitialColour { black } + # @OptimizePages { No } + # @HeadingFont { Bold } + # @ParaGap { 1.3vx @OrIfPlain 1f } + # @ParaIndent { 2.00f @OrIfPlain 5s } +} +} +@Code "@BasicSetup" is a symbol, and @Code { "@InitialFont" }, +basic.layout @Index @Code "@BasicSetup" +@Code { "@InitialBreak" }, etc. are its options. There are more options +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 +@ID @Code "@InitialFont { Helvetica Base 10p }" +We won't go through all the options now, since they are the subject of +following sections. +@PP +The @Code "@OrIfPlain" symbol that appears within some setup file +options is used to set the value of the option differently when +plain text output (Section {@NumberOf plain}) is being produced. For +example, the default value of @Code "@InitialBreak" is usually +{@Code "adjust 1.20fx hyphen"}, but when plain text is being produced +it switches to {@Code "ragged 1fx nohyphen"}. When changing such +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 }" +"}" +} +This one has many options, starting with options for page +layout as shown, then going on to figures and tables, tables of +contents, etc. +@PP +The standard setup files are all much the same up to this point; the +main variation is that in some files, some options are already set. The +@Code "slides" setup file, for example, contains +@ID @Code "@InitialFont { Times Base 20p }" +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 }" +"}" +} +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 +second @Code "@Use" clauses assign values to options that are relevant to many +or all document types. +@PP +The setup file ends with a comment identifying a spot where database +declarations may +database.dec @Index { database declarations, where to put } +be put, and one such declaration, for reference printing styles. +@PP +The setup files used with other packages, such as C and C++ program printing, +diagrams, and graphs, are similar to the @Code { doc } setup file we +have just gone through. They contain a @@SysInclude line analogous to +@Code "@SysInclude { dsf }" for reading the package's definition, followed +by a @@Use clause for setting the package's options. The same procedure +is followed for changing these options. For example, to change the +options of the @Code "diag" package, copy file @Code "diag" from the +Lout system include directory to your directory, replace the +@ID @Code "@SysInclude { diag }" +line at the top of your document by {@Code "@Include { mydiag }"}, then +edit @Code "mydiag" and change the options as you wish. +@PP +If you are using several packages and you would like a single setup file, +that is quite easy to arrange. For example, suppose you have +@ID @Code { +"@Include { mydoc }" +"@Include { mydiag }" +"@Include { mycprint }" +} +To create a single setup file, just concatenate these three files into +one file (call it @Code { mysetup }, say), and replace the three lines by +@ID @Code { +"@Include { mysetup }" +} +As explained earlier, you can even replace the @Code "@Include { mydefs }" +line within the setup file by the actual definitions, giving just one +file of setup material for the entire document. +@End @Section diff --git a/doc/user/fmt_size b/doc/user/fmt_size new file mode 100644 index 0000000..8e4a258 --- /dev/null +++ b/doc/user/fmt_size @@ -0,0 +1,91 @@ +@Section + @Title { Page size and page orientation } + @Tag { pagesize } +@Begin +@PP +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 }" +} +The usual way to determine the page size is to set the @Code "@PageType" +option to the name of the paper you use: +@ID @Tab + vmargin { 0.5vx } + @Fmtb { @Col ! @Col ! @Col @I @RR B ! @Col @I @RR C } + @Fmta { @Col @Code { "@PageType {" A "}" } ! @Col ! @Col @Code @CC B ! + @Col @Code @CC C } +{ +@Rowb B { width in points } C { height in points } +@Rowa A { Letter } B { 612p } C { 792p } +@Rowa A { Tabloid } B { 792p } C { 1224p } +@Rowa A { Ledger } B { 1224p } C { 792p } +@Rowa A { Legal } B { 612p } C { 1008p } +@Rowa A { Statement } B { 396p } C { 612p } +@Rowa A { Executive } B { 540p } C { 720p } +@Rowa A { A3 } B { 842p } C { 1190p } +@Rowa A { A4 } B { 595p } C { 842p } +@Rowa A { A5 } B { 420p } C { 595p } +@Rowa A { B4 } B { 729p } C { 1032p } +@Rowa A { B5 } B { 516p } C { 729p } +@Rowa A { Folio } B { 612p } C { 936p } +@Rowa A { Quarto } B { 610p } C { 780p } +@Rowa A { 10x14 } B { 720p } C { 1008p } +} +This will automatically assign the widths and heights shown above to +the @Code "@PageWidth" and @Code "@PageHeight" options, so you don't +have to worry about those options. If your paper size is not on this +list, set @Code "@PageType" to @Code Other and supply your own width +and height: +page.width @Index @Code "@PageWidth" +page.height @Index @Code "@PageHeight" +@ID @Tab + vmargin { 0.5vx } + @Fmta { @Col @Code A } +{ +@Rowa A { "@PageType { Other }" } +@Rowa A { "@PageWidth { 12.0c }" } +@Rowa A { "@PageHeight { 18.0c }" } +} +The width and height may each be any length (Section {@NumberOf objects}), +and do not have to be in points. +@PP +The basic page orientations are @I portrait and @I landscape: +page.orientation @Index @Code "@PageOrientation" +@ID @Tab + @Fmta { @Col 8c @Wide @Code A ! @Col B } +{ +@Rowa + A { "@PageOrientation { Portrait }" } + B { @Box 1.0c @Wide 1.4c @High { Hello } } +@Rowa +@Rowa + A { "@PageOrientation { Landscape }" } + B { @Box 1.4c @Wide 1.0c @High { Hello } } +} +When changing to {@Code Landscape}, do not change the page type, page +width, or page height, and do not change the way you feed your paper +into the printer. Lout knows what to do. +@PP +Two other orientations are provided which are 180@Degree rotations of +the basic ones: +@ID @Tab + @Fmta { @Col 8c @Wide @Code A ! @Col B } +{ +@Rowa + A { "@PageOrientation { ReversePortrait }" } + B { @Box 1.0c @Wide 1.4c @High { //1rt &1rt 180d @Rotate Hello } } +@Rowa +@Rowa + A { "@PageOrientation { ReverseLandscape }" } + B { @Box 1.4c @Wide 1.0c @High { //1rt &1rt 180d @Rotate Hello } } +} +@Code ReverseLandscape might be useful when post-processing the PostScript output +to print two landscape pages per sheet. The @Code "@PageOrientation" symbol is +available at the start of a document, as well as in the setup file, like +{@Code "@InitialFont"} and {@Code "@PageHeaders"}. +@End @Section diff --git a/doc/user/gra b/doc/user/gra new file mode 100644 index 0000000..58c73ac --- /dev/null +++ b/doc/user/gra @@ -0,0 +1,46 @@ +@Chapter + @Title { Graphs } + @Tag { graphs } +@Begin +@LP +This chapter describes how to draw graphs, using the @Code "@Graph" +graphs. @Index { graphs (statistical) } +graph. @Index @Code "@Graph" +symbol. For example, +@ID @OneRow @Code { +"@Graph" +" 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 the graph +@CD @Graph + 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 + } +} +The features of @Code "@Graph" include captions, automatic and manual +ticks and labels, logarithmic axes, histograms, and plotting of +mathematical functions. +@BeginSections +@Include { gra_intr } +@Include { gra_over } +@Include { gra_capt } +@Include { gra_tick } +@Include { gra_data } +@Include { gra_plac } +@Include { gra_func } +@Include { gra_keys } +@Include { gra_erro } +@Include { gra_summ } +@EndSections +@End @Chapter diff --git a/doc/user/gra_capt b/doc/user/gra_capt new file mode 100644 index 0000000..089e6e5 --- /dev/null +++ b/doc/user/gra_capt @@ -0,0 +1,72 @@ +@Section + @Title { Captions } + @Tag { captions } +@Begin +@PP +There are options for placing captions above, below, left, and right of +captions.graphs @SubIndex { in graphs } +the frame: +@ID @OneRow @Code { +"@Graph" +" abovecaption { This appears above }" +" belowcaption { This appears below }" +" leftcaption { At left }" +" rightcaption { At right }" +"{" +"}" +} +produces +@CD @Graph + abovecaption { This appears above } + belowcaption { This appears below } + leftcaption { At left } + rightcaption { At right } +{ +} +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. Incidentally, this example shows +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 +default values: +@ID @OneRow @Code { +"@Graph" +" abovegap { 0.5 cm }" +" belowgap { 0.5 cm }" +" leftgap { 1.5 cm }" +" rightgap { 0.5 cm }" +"{" +" ..." +"}" +} +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 +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. +@PP +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 +making the left and right captions and gaps seem to Lout to have zero width: +@ID @OneRow @Code { +"@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 +this feature is not wanted (for example, if a graph appears as an entry +in a table), use {@Code "hidecaptions { no }"}. The y and r ticks and labels +seem to Lout to have zero width already, so do not need to be hidden. +@End @Section diff --git a/doc/user/gra_data b/doc/user/gra_data new file mode 100644 index 0000000..323f155 --- /dev/null +++ b/doc/user/gra_data @@ -0,0 +1,267 @@ +@Section + @Title { Changing the appearance of the data } + @Tag { data } +@Begin +@PP +The @Code "@Data" symbol has options for controlling the +data. @Index @Code "@Data" +appearance of its data. We have already seen the +@Code "points" option, which controls what is printed at each data +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 } +{ +@Rowa + A { cross } + B { @GraphCross } + C { plus } + D { @GraphPlus } +@Rowa + A { square } + B { @GraphSquare } + C { filledsquare } + D { @GraphFilledSquare } +@Rowa + A { diamond } + B { @GraphDiamond } + C { filleddiamond } + D { @GraphFilledDiamond } +@Rowa + A { circle } + B { @GraphCircle } + C { filledcircle } + D { @GraphFilledCircle } +@Rowa + A { triangle } + B { @GraphTriangle } + C { filledtriangle } + D { @GraphFilledTriangle } +} +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" +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 }" +} +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"}. +@PP +The @Code "@Data" symbol also has a @Code "pairs" option which +pairs. @Index { @Code "pairs" option in 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 +example, +@ID @OneRow @Code { +"@Graph" +" abovecaption { Estimated population of Boston, New York, and Philadelphia }" +"{" +" @Data points { plus } pairs { solid }" +" { 1720 12000 1730 13000 1740 15601 1760 15631 1770 15877 }" +"" +" @Data points { plus } pairs { dashed }" +" { 1720 7000 1730 8622 1740 10451 1750 14255 1760 18000 1770 22667 }" +"" +" @Data points { plus } pairs { dotted }" +" { 1720 10000 1730 11500 1740 12654 1750 18202 1760 23750 1770 34583 }" +"}" +} +produces +@CD @Graph + abovecaption { Estimated population of Boston, New York, and Philadelphia +} +{ + @Data points { plus } pairs { solid } + { 1720 12000 1730 13000 1740 15601 1760 15631 1770 15877 } + + @Data points { plus } pairs { dashed } + { 1720 7000 1730 8622 1740 10451 1750 14255 1760 18000 1770 22667 } + + @Data points { plus } pairs { dotted } + { 1720 10000 1730 11500 1740 12654 1750 18202 1760 23750 1770 34583 } + +} +(R. C. Simmons, @I { The American Colonies }, W. W. Norton, New York, +1981.) We will see in Section {@NumberOf key} how to add an explanatory key to +this graph. If the points have symbols, these connecting lines will stop 1.5 +symbolsizes away from the data points, so as not to overstrike them. If +the points have no symbols and @Code "pairs" is {@Code "dashed"}, the +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 +separation between dots, and a @Code "linewidth" option controls the +width (thickness) of the lines and dots: +@ID @OneRow @Code { +"@Data" +" dashlength { 0.2 ft }" +" linewidth { 0.5 pt }" +"{" +" ..." +"}" +} +This shows the default values, {@Code "0.2 ft"} for @Code "dashlength" +and {@Code "0.5 pt"} (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 +histograms. @Index { histograms } +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 }" +"}" +} +which has result +@CD @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 } +} +Note carefully that one y histogram rectangle occupies the space from +one x value to the next, with height equal to the y value lying between +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"}: +@CD @Graph + hidecaptions { yes } + abovecaption { Computer Science 3 Results (1993) } + leftcaption { Number of +students } + belowcaption { Final mark (%) } + yextra { 0 cm } + ymax { 80 } +{ + @Data + pairs { surfaceyhisto } + { 0 1 10 3 20 2 30 4 40 15 50 60 60 58 70 28 80 15 90 7 100 0 } +} +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 +@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 +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 }" +"}" +} +produces +@CD @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 } +} +(Bryant Robey, Shea O. Rutstein, and Leo Morros: The fertility decline in +developing countries, @I { Scientific American }, December 1993.) Once +again each bar goes from one y value to the next, with its x value +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" +option: +@ID @OneRow @Code { +"@Data" +" colour { blue }" +} +For the complete list of acceptable colour names, see Section +{@NumberOf colour}. The @Code "colour" option's name may also be +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 +@ID @OneRow @Code { +"@Data" +" paint { yes }" +} +The paint colour is determined by the @Code "colour" option just +introduced; it will be @Code "black" if no colour is specified. Paint +(including white paint) hides paint, points, and lines drawn by previous +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 +A @Code "dataformat" option is provided for changing the interpretation +dataformat. @Index { @Code "dataformat" option in 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 { +"@Data" +"{" +" x y x y ... x y" +"}" +} +However, by setting @Code "dataformat" to {@Code "yonly"}, the +interpretation is changed to a sequence of y coordinates only: +@ID @OneRow @Code { +"@Data" +" dataformat { yonly }" +"{" +" y y ... y" +"}" +} +and x values 1, 2, and so on are inserted automatically, just as though +the original input had been +@ID @OneRow @Code { +"@Data" +"{" +" 1 y 2 y ..." +"}" +} +There is also {@Code "xonly"}, which inserts y values 1, 2, and so on. The +default value, {@Code "xandy"}, gives the usual interpretation. 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 new file mode 100644 index 0000000..3c123a3 --- /dev/null +++ b/doc/user/gra_erro @@ -0,0 +1,40 @@ +@Section + @Title { Errors } + @Tag { grerrors } +@Begin +@PP +Lout normally produces output that will print without mishap on +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 +until the file is printed. +@PP +The most likely errors are @I { rangecheck errors}, for example if +an attempt is made to divide by zero or take the square root of a +negative number, and @I { undefined errors }, arising from symbols +misspelt, use of @Code "x" outside an {@Code "xloop"}, etc. Less commonly, +everything may be correct but the graph is too large in some +way: too much data, expression too deeply nested, and so on. +@PP +When an error is detected, @Code "@Graph" arranges for the offending page +to be 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 +If you see @Code VMerror in an error message, it means that the printer +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 }" +"..." +} +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 +several graphs on one page. However, if the graph is nested +inside some other major Lout package, notably {@Code "@Diag"}, this +option could cause PostScript errors in that package. +@End @Section diff --git a/doc/user/gra_func b/doc/user/gra_func new file mode 100644 index 0000000..d30e82c --- /dev/null +++ b/doc/user/gra_func @@ -0,0 +1,179 @@ +@Section + @Title { Mathematical functions, loops, and tests } + @Tag { functions } +@Begin +@PP +@Code "@Graph" offers quite a large selection of 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 +the @Code "objects" option, and within the right parameter of the +@Code "@Data" symbol. For example, +@ID @OneRow @Code { +"@Data" +" pairs { solid }" +"{" +" 0 0 pi sin { pi/2 }" +"}" +} +draws a solid line from @Eq {(0, 0)} to @Eq {(pi, sin(pi "/" 2))}. Section +{@NumberOf grsummary} lists all the functions; they include the four +arithmetical operators @Eq { non + }, @Eq { non - }, @Eq { non * }, and +@Eq { "/" }, as well as {@Code "sin"}, {@Code "cos"}, {@Code "sqrt"}, and +many others. Braces are used for grouping, never parentheses. +@PP +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" +" }" +" }" +"}" +} +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 +result is +@FootNote { Source: Jeffrey H. Kingston, Analysis of tree algorithms +for the simulation event list. @I { Acta Informatica } {@B 22}, +pp. 15--33 (1985). } +@CD -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 + } + } +} +The points are connected by straight line segments as usual, but a +smallish @Code "by" option of about one-twentieth of the range creates +the illusion of a smooth curve quite well. +@PP +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 {}" +"}" +} +This plots the function @Eq { y = 1 "/" x }, skipping points near +zero. Actually the @Code "else" part could be omitted since its default +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 { @ }" +" }" +"}" +} +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 +right to mix @Code "@" and even labels in with numbers, as long as the +final result obeys the rules of Section {@NumberOf ticks}. +@PP +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" +"}" +} +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 }" +" }" +"}" +} +Following is a detailed explanation. +@PP +The first line, {@Code "import @Graph @Data"}, is the import clause. Its +function is to grant the definition access to the three previously defined +functions (symbols) that it uses, namely {@Code "sin"}, {@Code "cos"}, +and {@Code "/"}. These are found within the @Code "@Data" symbol within +{@Code "@Graph"}. +@PP +After the import clause comes the @Code "def" keyword, meaning +`define,' and then the name of the symbol being defined, in this case +@Code "@Tan". We have chosen @Code "@Tan" rather than @Code "tan" +because symbols defined by the user in this way are visible throughout +the document, and we do not want the literal word @Code "tan" to be +taken as a symbol. +@PP +Next comes the symbol's precedence, in this case the same as @Code "sin" and +@Code "cos" (see Section {@NumberOf dia_summ} for the precedence of +each symbol). Next is a list of the formal parameters, in this case +just one, called {@Code "x"}, that is to be passed on the right. +@PP +Finally comes the body of the definition enclosed in braces. When +@Code "@Tan" is invoked, its value will be this body with each occurrence +of the formal parameter @Code "x" replaced by the object following the +@Code "@Tan" symbol. For example, the @Code "do" option of the @Code +"yloop" above becomes +@ID @Code "y sin { y / pi } / cos { y / pi }" +as you would expect. +@End @Section diff --git a/doc/user/gra_intr b/doc/user/gra_intr new file mode 100644 index 0000000..28dfd1b --- /dev/null +++ b/doc/user/gra_intr @@ -0,0 +1,51 @@ +@Section + @Title { Introduction } + @Tag { grintro } +@Begin +@PP +The Lout definitions for graph formatting are kept in a file called +{@Code "graph"}, which you must include at the start of your document if +graph.file @Index { @Code "graph" file } +you want graphs, like this: +@ID @OneRow @Code { +"@SysInclude { graph }" +"@SysInclude { doc }" +"@Doc @Text @Begin" +"..." +"@End @Text" +} +Setup files for specialized packages, such as {@Code "graph"}, should be +included before the main setup file. Once this is done, the @Code "@Graph" +symbol used below will then be available for use anywhere within your document. +@PP +@Code "@Graph" distinguishes between the overall graph, produced by the +@Code "@Graph" symbol itself, and the data sets to be placed within it, +each of which is enclosed by a @Code "@Data" symbol: +@ID @OneRow @Code { +"@CentredDisplay @Graph" +"{" +" @Data points { plus }" +" { 1 1.10 2 1.21 3 1.33 4 1.46 5 1.61 6 1.77 7 1.95 8 2.14 }" +"" +" @Data points { circle }" +" { 1 1.20 2 1.44 3 1.73 4 2.07 5 2.45 6 2.99 7 3.58 8 4.30 }" +"}" +} +Although it is good practice to lay the input data out neatly, layout +has no effect on the result. It is not necessary to have one data point +per line, for example. The result of this example is +@CentredDisplay @Graph +{ + @Data + points { plus } + { 1 1.10 2 1.21 3 1.33 4 1.46 5 1.61 6 1.77 7 1.95 8 2.14 } + + @Data + points { circle } + { 1 1.20 2 1.44 3 1.73 4 2.07 5 2.45 6 2.99 7 3.58 8 4.30 } +} +We have used the @Code "@CentredDisplay" symbol from Section +{@NumberOf displays} to produce a centred display, but the +@Code "@Graph" symbol produces an object which may appear anywhere +at all -- in a figure, for example, or as an entry in a table. +@End @Section diff --git a/doc/user/gra_keys b/doc/user/gra_keys new file mode 100644 index 0000000..089139a --- /dev/null +++ b/doc/user/gra_keys @@ -0,0 +1,104 @@ +@Section + @Title { Adding a key to the graph } + @Tag { key } +@Begin +@PP +A @I key to a graph is an explanation of what each data set +key. @Index { key in graph } +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" +@ID @Tab + @Fmta { @Col @Code A ! @Col B ! @Col @Code C ! @Col D } +{ +@Rowa + A { "@GraphCross" } + B { @GraphCross } + C { "@GraphPlus" } + D { @GraphPlus } +@Rowa + A { "@GraphSquare" } + B { @GraphSquare } + C { "@GraphFilledSquare" } + D { @GraphFilledSquare } +@Rowa + A { "@GraphDiamond" } + B { @GraphDiamond } + C { "@GraphFilledDiamond" } + D { @GraphFilledDiamond } +@Rowa + A { "@GraphCircle" } + B { @GraphCircle } + C { "@GraphFilledCircle" } + D { @GraphFilledCircle } +@Rowa + A { "@GraphTriangle" } + B { @GraphTriangle } + C { "@GraphFilledTriangle" } + D { @GraphFilledTriangle } +@Rowa +@Rowa + A { "@GraphNoLine" } + B { @GraphNoLine } +@Rowa + A { "@GraphSolid" } + B { @GraphSolid } +@Rowa + A { "@GraphDashed" } + B { @GraphDashed } +@Rowa + A { "@GraphDotted" } + B { @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" +"}" +} +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 +from Section {@NumberOf data}, the complete result is +@CD @Graph + rightcaption { +@GraphPlus @GraphSolid @GraphPlus Boston +@GraphPlus @GraphDashed @GraphPlus New York +@GraphPlus @GraphDotted @GraphPlus Philadelphia +} +{ + @Data points { plus } pairs { solid } + { 1720 12000 1730 13000 1740 15601 1760 15631 1770 15877 } + + @Data points { plus } pairs { dashed } + { 1720 7000 1730 8622 1740 10451 1750 14255 1760 18000 1770 22667 } + + @Data points { plus } pairs { dotted } + { 1720 10000 1730 11500 1740 12654 1750 18202 1760 23750 1770 34583 } + +} +The first eight symbols have a @Code "symbolsize" option with the +usual meaning and the usual default value ({@Code "0.15 ft"}). 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"} +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"}. +@End @Section diff --git a/doc/user/gra_over b/doc/user/gra_over new file mode 100644 index 0000000..1b9653a --- /dev/null +++ b/doc/user/gra_over @@ -0,0 +1,179 @@ +@Section + @Title { Changing the overall appearance of the graph } + @Tag { overall } +@Begin +@PP +The overall appearance of the graph is controlled by options to the +@Code "@Graph" symbol. As usual, these options follow the @Code "@Graph" +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" } +axes. @Index { axes in graphs } +graph, whose value may be either {@Code "frame"}, {@Code "none"}, +or {@Code "axes"}. The default value is {@Code "frame"}, and it produces +a frame around the graph with ticks and labels along its left and bottom +edges, as in previous examples. The {@Code "none"} style prints +nothing (no frame, no ticks, no labels), which is useful for producing +graphs that don't look like graphs, as it were. +@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" +" }" +"}" +} +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 +we have used some other options which will be explained shortly. The +resulting graph has an x axis and a y axis instead of a frame, like this: +@CD -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 9.5 2 15.0 3 18.2 4 20.1 5 22.1 7 25.0 + 10 28.3 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 + } +} +The point where the axes cross is ({@Code xorigin}, {@Code yorigin}). +@PP +Although @Code "@Graph" does not provide explicit support for +multiple axes, you can simulate them by overstriking two +separate graphs of equal size. There is an @Code "@OverStrike" +overstrike. @Index @Code "@OverStrike" +symbol which overstrikes two objects, so +@ID @Code "@Graph { ... } @OverStrike @Graph { ... }" +will do the job. Typically one of the graphs would have y ticks, +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 +logarithmic.axes @Index { logarithmic axes in graphs } +logarithmic x and y axes: +@ID @OneRow @Code { +"@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 +to different bases differ only by a constant factor, so the main effect +of different bases is on the choice of ticks and labels. An @Code "xlog" +option will be ignored if there are any negative or zero x data points, +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 +of the total area enclosed: +@ID @OneRow @Code { +"@Graph" +" width { 6.0 cm }" +" height { 4.0 cm }" +"{" +" ..." +"}" +} +This shows the default width and height, six centimetres and four +centimetres. These lengths and others discussed below can be specified +using a variety of units of measurement (see Section {@NumberOf grsummary} +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" +options: +@ID @OneRow @Code { +"@Graph" +" xextra { 0.5 cm }" +" yextra { 0.5 cm }" +"{" +" ..." +"}" +} +Setting @Code "xextra" to @Code "0.5 cm" (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 +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 +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" +" }" +"}" +} +produces +@CD @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 + } +} +The value of @Code "xdecreasing" should be either @Code "no" (the default +value) or {@Code "yes"}. A similar @Code "ydecreasing" option does the same +thing to the y axis. +@End @Section diff --git a/doc/user/gra_plac b/doc/user/gra_plac new file mode 100644 index 0000000..7084eb2 --- /dev/null +++ b/doc/user/gra_plac @@ -0,0 +1,51 @@ +@Section + @Title { Placing arbitrary objects on the graph } + @Tag { arbobj } +@Begin +@PP +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 }" +" }" +} +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"} +and {@Code "4.5 7.0"} respectively. An example result appears in the next +section. +@PP +In addition to {@Code "@CTR"}, there are eight other symbols which may +be used within the @Code "objects" option in the same way: {@Code "@NW"}, +{@Code "@SW"}, {@Code "@SE"}, {@Code "@NE"}, {@Code "@N"}, {@Code "@W"}, +{@Code "@S"}, and {@Code "@E"}. These place the object just to the +northwest of the point, to the southwest, and so on instead of centring +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 }" +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 +The major advantage of the @Code "objects" option over the @Code "@Data" +symbol is that arbitrary Lout objects may be used. The @Code "@Data" +symbol however is able to place many copies of its symbols onto the graph, +and also allow for them when connecting points together with lines. Also, +the points within the @Code "objects" option are not taken into account +when deciding on the permissible range of x and y values, whereas the +points within the @Code "@Data" symbol are. Altogether it seems best +to use the @Code "@Data" symbol for the bulk of the data points, and to +use the @Code "objects" option for adding a small number of labels or +other decorations. +@PP +The @Code "objects" option may contain @Code "@Graph" symbols, but in +that case, owing to a deficiency in the implementation, those symbols +will need to have their @Code save options (Section {@NumberOf grerrors}) +set to {@Code yes}. +@End @Section diff --git a/doc/user/gra_summ b/doc/user/gra_summ new file mode 100644 index 0000000..ea074b9 --- /dev/null +++ b/doc/user/gra_summ @@ -0,0 +1,466 @@ +@Section + @Title { Summary } + @Tag { grsummary } +@Begin +@PP +The options to the @Code "@Graph" symbol, their default values, and +their possible values are: +@ID -2.1px @Break -1p @Font @Tab + hmargin { 0.15c } + @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 { "@Graph" } +@Rowa + A { style } + B { frame } + C { {@Code frame}, {@Code axes}, or {@Code none} } +@Rowa + A { width } + B { 6.0 cm } + C { any @I distance } +@Rowa + A { height } + B { 4.0 cm } + 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"}) } +@Rowa + A { yextra } + B { 0.5 cm } + C { any @I distance ({@Code axes} and {@Code none} default is {@Code "0 cm"}) } +@Rowa + A { xdecreasing } + B { no } + C { @Code yes or @Code no } +@Rowa + A { ydecreasing } + B { no } + C { @Code yes or @Code no } +@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 { 1.5 cm } + C { any @I distance } +@Rowa + A { rightgap } + B { 0.5 cm } + C { any @I distance } +@Rowa + A { abovegap } + B { 0.5 cm } + C { any @I distance } +@Rowa + A { belowgap } + B { 0.5 cm } + C { any @I distance } +@Rowa + A { hidecaptions } + B { yes } + C { @Code yes or @Code no } +@Rowa + A { xorigin } + B { none } + C { {@Code none} or any @I number } +@Rowa + A { yorigin } + B { none } + C { {@Code none} or any @I number } +@Rowa + A { xlog } + B { none } + C { {@Code none} or any @I number greater than 1 } +@Rowa + A { ylog } + B { none } + C { {@Code none} or any @I number greater than 1 } +@Rowa + A { xmin } + B { none } + C { @Code none or any {@I number} } +@Rowa + A { xmax } + B { none } + C { @Code none or any {@I number} } +@Rowa + A { ymin } + B { none } + C { @Code none or any {@I number} } +@Rowa + A { ymax } + B { none } + C { @Code none or any {@I number} } +@Rowa + A { xticksep } + B { none } + C { {@Code none} or any @I number greater than 0 } +@Rowa + A { yticksep } + B { none } + C { {@Code none} or any @I number greater than 0 } +@Rowa + A { rticksep } + B { none } + C { {@Code none} or any @I number greater than 0 } +@Rowa + A { xticks } + B { auto } + C { @I sequence (of numbers and strings), or @Code auto meaning +automatic } +@Rowa + A { yticks } + B { auto } + C { @I sequence (of numbers and strings), or @Code auto meaning +automatic } +@Rowa + A { rticks } + B { } + C { @I sequence (of numbers and strings), or @Code auto meaning +automatic } +@Rowa + A { xticklength } + B { 0.5 ft } + C { any @I distance } +@Rowa + A { yticklength } + B { 0.5 ft } + C { any @I distance } +@Rowa + A { rticklength } + B { 0.5 ft } + C { any @I distance } +@Rowa + A { objects } + B { } + C { sequence of {@Code "@CTR"}, {@Code "@NW"}, {@Code "@SW"}, {@Code "@SE"}, +{@Code "@NE"}, {@Code "@N"}, {@Code "@W"}, {@Code "@S"}, {@Code "@E"} symbols } +@Rowa + A { points } + B { none } + C { {@Code none}, {@Code plus}, {@Code cross}, {@Code square}, +{@Code filledsquare}, {@Code diamond}, {@Code filleddiamond}, +{@Code circle}, {@Code filledcircle}, {@Code triangle}, {@Code filledtriangle} } +@Rowa + A { pairs } + B { none } + C { {@Code none}, {@Code solid}, {@Code dashed}, {@Code dotted}, +{@Code yhisto}, {@Code xhisto}, {@Code filledyhisto}, {@Code filledxhisto}, +{@Code surfaceyhisto}, {@Code surfacexhisto} } +@Rowa + A { "colour/color" } + B { none } + C { {@Code none} or any colour name from Section {@NumberOf colour}} +@Rowa + A { paint } + B { no } + C { {@Code no} or {@Code yes} } +@Rowa + A { dataformat } + B { xandy } + C { {@Code xandy}, {@Code yonly}, {@Code xonly} } +@Rowa + A { dashlength } + B { 0.2 ft } + C { any @I distance } +@Rowa + A { linewidth } + B { 0.5 pt } + C { any @I distance } +@Rowa + A { symbolsize } + B { 0.15 ft } + 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. +@PP +The minimum plottable x value is the minimum of all the x data, +{@Code xticks}, {@Code xorigin}, {@Code xmin}, and {@Code xmax} whenever +these are not {@Code none}. If @Code xticks is {@Code none}, this +minimum may be reduced further to a `round' number. The maximum plottable +x value is the maximum of the same values, and it may be increased further +if {@Code xticks} is {@Code none}. Similar remarks apply to y values. +@PP +The value of the @Code "objects" option is a sequence of zero or more of +the following: +@ID @Tab + vmargin { 0.5vx } + @Fmta { @Col A ! @Col { @Code "at {" @I expression @I expression +@Code "}" } ! @Col @I object } +{ +@Rowa A { @Code "@CTR" } +@Rowa A { @Code "@NW" } +@Rowa A { @Code "@SW" } +@Rowa A { @Code "@SE" } +@Rowa A { @Code "@NE" } +@Rowa A { @Code "@N" } +@Rowa A { @Code "@W" } +@Rowa A { @Code "@S" } +@Rowa A { @Code "@E" } +} +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"}. +@PP +The options to the @Code "@Data" symbol, their default values, and +their possible values are: +@ID 0.85vx @Break @Tab + hmargin { 0.15c } + @Fmta { @Col @Code { " "A } ! @Col @Code "{" ! @Col @I inherited ! + @Col @Code "}" ! @Col ! @Col ! @Col C } + @Fmtb { @Col A ! @Col ! @Col ! @Col ! @Col ! @Col ! @Col } +{ +@Rowb + A { @Code "@Data" } +@Rowa + A { points } + C { {@Code none}, {@Code plus}, {@Code cross}, {@Code square}, +{@Code filledsquare}, {@Code diamond}, {@Code filleddiamond}, +{@Code circle}, {@Code filledcircle}, +{@Code triangle}, {@Code filledtriangle} } +@Rowa + A { pairs } + C { {@Code none}, {@Code solid}, {@Code dashed}, {@Code dotted}, +{@Code yhisto}, {@Code xhisto}, {@Code filledyhisto}, {@Code filledxhisto}, +{@Code surfaceyhisto}, {@Code surfacexhisto} } +@Rowa + A { "colour/color" } + C { {@Code none}, or any colour name from Section {@NumberOf colour} } +@Rowa + A { paint } + C { {@Code no} or {@Code yes} } +@Rowa + A { dataformat } + C { {@Code xandy}, {@Code yonly}, {@Code xonly} } +@Rowa + A { dashlength } + C { any @I distance } +@Rowa + A { linewidth } + C { any @I distance } +@Rowa + A { symbolsize } + C { any @I distance } +@Rowb + A { @Code "{" @I sequence @Code "}" } + C { any @I sequence } +} +@I Inherited means that the default value is taken from the +@Code "@Graph" option with the same name. +@PP +The right parameter of @Code "@Data" contains a @I sequence of zero +or more {@I expressions}. The {@Code xticks}, {@Code yticks}, and +{@Code rticks} options also are sequences, which may contain @Code "@" +and labels as well as expressions. An @I expression is any of the +following (operators are shown in decreasing precedence order, with +the precedence, if relevant, at right): +@ID @Tab + vmargin { 0.5vx } + @Fmta { @Col A ! @Col ! @Col B } +{ +@Rowa + A { @I number } +@Rowa + A { @Code x (within @Code xloop only) } +@Rowa + A { @Code y (within @Code yloop only) } +@Rowa + A { @Code z (within @Code zloop only) } +@Rowa + A { @Code pi } +@Rowa + A { @Code e } +@Rowa + A { @Code "{" @I expression @Code "}" } +@Rowa + A { @Code "sqrt" @I expression } + B { 40 } +@Rowa + A { @Code "abs" @I expression } + B { 40 } +@Rowa + A { @Code "ceiling" @I expression } + B { 40 } +@Rowa + A { @Code "floor" @I expression } + B { 40 } +@Rowa + A { @Code "truncate" @I expression } + B { 40 } +@Rowa + A { @Code "round" @I expression } + B { 40 } +@Rowa + A { @Code "cos" @I expression } + B { 40 } +@Rowa + A { @Code "sin" @I expression } + B { 40 } +@Rowa + A { @I expression @Code "atan" @I expression } + B { 39 } +@Rowa + A { @I expression @Code "exp" @I expression } + B { 38 } +@Rowa + A { @I expression @Code "log" @I expression } + B { 37 } +@Rowa + A { @I expression @Code "rand" @I expression } + B { 36 } +@Rowa + A { @I expression @Eq { non * } @I expression } + B { 35 } +@Rowa + A { @I expression @Code "/" @I expression } + B { 34 } +@Rowa + A { @I expression @Code "idiv" @I expression } + B { 34 } +@Rowa + A { @I expression @Code "mod" @I expression } + B { 34 } +@Rowa + A { @I expression @Eq { non - } @I expression } + B { 33 } +@Rowa + A { @Eq { non - } @I expression } + B { 33 } +@Rowa + A { @I expression @Code "+" @I expression } + B { 32 } +@Rowa + A { @Code "+" @I expression } + B { 32 } +@Rowa + A { @Code "if cond {" @I boolean @Code "} then {" @I expression +@Code "} else {" @I expression @Code "}" } +} +A @Eq { non - } immediately followed by a digit or decimal point is +always taken to be a minus sign, never a subtraction. The left +parameter of @Code "exp" and @Code "log" is the base of the +exponentiation and logarithm respectively; @Code "idiv" is integer +division; and @Code "rand" returns a uniform random integer lying between +its two parameters (inclusive). Now a @I sequence is zero or more of +the following: +@ID @Tab + vmargin { 0.5vx } + @Fmta { @Col A } +{ +@Rowa + A { 2c @Wide "@" (within {@Code xticks}, {@Code yticks}, and {@Code rticks} only) } +@Rowa + A { 2c @Wide { ({@I label}) } (within {@Code xticks}, {@Code yticks}, and {@Code rticks} only) } +@Rowa + A { @I expression } +@Rowa + A { @Code "xloop from {" @I expression @Code "} to {" @I expression +@Code "} by {" @I expression @Code "} do {" @I sequence @Code "}" } +@Rowa + A { @Code "yloop from {" @I expression @Code "} to {" @I expression +@Code "} by {" @I expression @Code "} do {" @I sequence @Code "}" } +@Rowa + A { @Code "zloop from {" @I expression @Code "} to {" @I expression +@Code "} by {" @I expression @Code "} do {" @I sequence @Code "}" } +@Rowa + A { @Code "if cond {" @I boolean @Code "} then {" @I sequence +@Code "} else {" @I sequence @Code "}" } +} +The @Code "by" part of the loop symbols is optional with default +value 1; the @Code "else" part of @Code "if" is optional with +default value equal to the empty sequence. A @I boolean is any one of +the following things, again shown in decreasing precedence order, with +the precedence at right: +@ID @Tab + vmargin { 0.5vx } + @Fmta { @Col A ! @Col ! @Col B } +{ +@Rowa + A { @Code true } +@Rowa + A { @Code false } +@Rowa + A { @Code "{" @I boolean @Code "}" } +@Rowa + A { @I expression @Code = @I expression } + B { 30 } +@Rowa + A { @I expression @Code != @I expression } + B { 30 } +@Rowa + A { @I expression @Code < @I expression } + B { 30 } +@Rowa + A { @I expression @Code <= @I expression } + B { 30 } +@Rowa + A { @I expression @Code > @I expression } + B { 30 } +@Rowa + A { @I expression @Code >= @I expression } + B { 30 } +@Rowa + A { @Code not @I boolean } + B { 25 } +@Rowa + A { @I boolean @Code and @I boolean } + B { 24 } +@Rowa + A { @I boolean @Code xor @I boolean } + B { 23 } +@Rowa + A { @I boolean @Code or @I boolean } + B { 22 } +@Rowa + A { @Code "if cond {" @I boolean @Code "} then {" @I boolean +@Code "} else {" @I boolean @Code "}" } +} +@End @Section diff --git a/doc/user/gra_tick b/doc/user/gra_tick new file mode 100644 index 0000000..f6079cf --- /dev/null +++ b/doc/user/gra_tick @@ -0,0 +1,205 @@ +@Section + @Title { Ticks and labels } + @Tag { ticks } +@Begin +@PP +@I Ticks are the short lines that mark off intervals along the axes, and +ticks.graph @Index { ticks in graphs } +labels.graph @Index { labels 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 +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 +"@Graph". For example, +@ID @OneRow @Code { +"@Graph" +" xmin { 0 }" +" xmax { 5 }" +" xticksep { 0.5 }" +} +specifies that x values in the range 0 to 5 are to be expected, and that +a tick and label is to appear every 0.5 units along the x axis. One or +both of @Code "xmin" and @Code "xmax" may be omitted, in which case +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" } +@ID @OneRow @Code { +"@Graph" +" xticks { 0@ 5 10@ 15 20@ }" +} +specifies that x ticks are to be drawn at 0, 5, 10, 15, and 20. An +@Code "@" following a number indicates that a label is to be printed as +well, so the above example will produce labels at 0, 10, and 20. For +even finer control, @Code "@" may be replaced by a label enclosed +in parentheses: +@ID @OneRow @Code { +"@Graph" +" xticks { 1 (Democrat) 2 (Republican) 3 (Other) }" +} +As this example shows, a label does not have to be a number; it can be +any string of characters, including spaces and balanced parentheses; +but it may not be an arbitrary Lout object. +@PP +The character @Code "^" in a label indicates that the +remainder is to be treated as an exponent: +@ID @OneRow @Code { +"@Graph" +" xlog { 10 }" +" xticks { 1 (1) 10 (10) 100 (10^2) 1000 (10^3) 10000 (10^4) 100000 (10^5) }" +"{" +" @Data points { plus }" +" { 1 2.1 10 3.4 100 4.9 1000 6.1 10000 7.2 100000 7.6 }" +"}" +} +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 } + xlog { 10 } + xticks { 1 (1) 10 (10) 100 (10^2) 1000 (10^3) 10000 (10^4) 100000 (10^5) } +{ + @Data points { plus } + { + 1 2.1 10 3.4 100 4.9 1000 6.1 10000 7.2 100000 7.6 + } +} +Setting @Code "xticks" to empty produces no x ticks (this is not the +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" } +also @Code "xticklength" and @Code "yticklength" options which set +the length of ticks: +@ID @OneRow @Code { +"@Graph" +" xticklength { 0.5 ft }" +" yticklength { 0.5 ft }" +} +shows the default values, half the current font size in both cases. +@PP +There is also an {@Code "rticks"} option which is similar to +{@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 +{@Code "yticks"}, {@Code "rticks"} has empty default value, which is +why you don't usually see r ticks. They are most useful when overstriking +two graphs using @Code "@OverStrike" as explained earlier; one graph will +have y ticks in the usual way, the other will have r ticks and empty +y ticks: +@CD { + +@Graph + style { frame } + width { 6c } + height { 8c } + xextra { 0 cm } + yextra { 0 cm } + rightcaption { -90d @Rotate { Precipitation mm } } + rightgap { 3.0f } + hidecaptions { no } + xmin { 0 } + xmax { 12 } + ymin { 0 } + ymax { 450 } + xticks { } + xticklength { 0 cm } + 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 { 8c } + xextra { 0 cm } + yextra { 0 cm } + 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 { 0 cm } + 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 + } +} + +} +Here the first graph has +@ID @Code { +"rticks { 0@ 50@ 100@ 150@ 200@ 250@ 300@ 350@ 400@ 450@ }" +"yticks {}" +} +for its ticks. +@PP +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 +usually about right; but it does not allow any space for y and r ticks and +labels since it has no idea how wide the labels will be. The discussion +of captions in Section {@NumberOf captions} explains how to use the +@Code "leftgap" and @Code "rightgap" options to work around this deficiency. +@End @Section diff --git a/doc/user/letterbook b/doc/user/letterbook new file mode 100644 index 0000000..269f073 --- /dev/null +++ b/doc/user/letterbook @@ -0,0 +1,356 @@ +############################################################################### +# # +# Lout setup file for books # +# # +# Jeffrey H. Kingston # +# 5 February 1999 # +# # +############################################################################### + + +############################################################################### +# # +# @SysInclude commands for standard packages. # +# # +############################################################################### + + @SysInclude { fontdefs } # font definitions + @SysInclude { langdefs } # language definitions + @SysInclude { bsf } # BasicSetup package + @SysInclude { dsf } # DocumentSetup package + @SysInclude { bookf } # BookSetup extension + + +############################################################################### +# # +# @Include command for reading personal definitions from current directory. # +# # +############################################################################### + + @Include { mydefs } + +############################################################################### +# # +# The @BasicSetup @Use clause - basics, lists, paragraphs, displays. # +# # +# To change the default value of any option, delete the # at the start of # +# its line and change the value between braces. # +# # +############################################################################### + +@Use { @BasicSetup + # @InitialFont { Times Base 12p } # initial font + # @InitialBreak {{adjust 1.2fx hyphen} @OrIfPlain {ragged 1fx nohyphen}} + # @InitialSpace { lout } # initial space style + # @InitialLanguage { English } # initial language + # @InitialColour { black } # initial colour + # @OptimizePages { No } # optimize page breaks? + # @HeadingFont { Bold } # font for @Heading + # @ParaGap { 1.3vx @OrIfPlain 1f } # gap between paragraphs + # @ParaIndent { 2.00f @OrIfPlain 5s } # first-line indent for @PP + # @DisplayGap { 1.00v @OrIfPlain 1f } # gap above, below displays + # @DisplayIndent { 2.00f @OrIfPlain 5s } # @IndentedDisplay indent + # @DefaultIndent { 0.5rt } # @Display indent + # @DisplayNumStyle { (num) } # style of display numbers + # @WideIndent { 4.00f @OrIfPlain 10s } # @WideTaggedList indent + # @VeryWideIndent { 8.00f @OrIfPlain 20s } # @VeryWideTaggedList indent + # @ListGap { 1.00v @OrIfPlain 1f } # gap between list items + # @ListIndent { 0s } # indent of list items + # @ListRightIndent { 0s } # right indent of list items + # @ListLabelWidth { 2.00f @OrIfPlain 5s } # width allowed for list tags + # @NumberSeparator { . } # separates nums like 2.3.7 +} + + +############################################################################### +# # +# The @DocumentSetup @Use clause - page layout plus figures, tables, etc. # +# # +# To change the default value of any option, delete the # at the start of # +# its line and change the value between braces. # +# # +############################################################################### + +@Use { @DocumentSetup + @PageType { Letter @OrIfPlain Other} # page type (width, height) + # @PageWidth { 80s } # page width if type Other + # @PageHeight { 66f } # page height if type Other + # @PageOrientation { Portrait } # Portrait, Landscape, etc. + # @PageBackground { } # background of each page + # @TopMargin { 2.5c @OrIfPlain 6f } # top margin of all pages + # @FootMargin { 2.5c @OrIfPlain 6f } # bottom margin of all pages + # @OddLeftMargin { 2.5c @OrIfPlain 10s } # left margin of odd pages + # @OddRightMargin { 2.5c @OrIfPlain 10s } # right margin of odd pages + # @EvenLeftMargin { 2.5c @OrIfPlain 10s } # left margin of even pages + # @EvenRightMargin { 2.5c @OrIfPlain 10s } # right margin of even pages + # @PageBoxType { None } # None Box CurveBox ShadowBox + # @PageBoxMargin { 1.00c } # page box margin + # @PageBoxLineWidth { } # page box line thickness + # @PageBoxPaint { none } # page box paint + # @PageBoxShadow { 0.60c } # shadow margin if ShadowBox + # @ColumnNumber { 1 } # number of columns (1 to 10) + # @ColumnGap { 1.00c @OrIfPlain 6s } # column gap + # @FigureLocation { PageTop } # default figure location + # @TableLocation { PageTop } # default table location + # @FigureFormat { @CC @Body } # default figure format + # @TableFormat { @CC @Body } # default table format + # @FigureWord { figure } # "Figure" word else anything + # @TableWord { table } # "Table" word else anything + # @FigureNumbers { Arabic } # method of numbering figures + # @TableNumbers { Arabic } # method of numbering tables + # @FigureCaptionPos { Below } # Above or Below + # @TableCaptionPos { Below } # Above or Below + # @CaptionFont { } # figure, table caption font + # @CaptionBreak { } # figure, table caption break + # @CaptionFormat { @B { number @DotSep @OneCol } } # figure, table caption format + # @MakeFigureContents { No } # list of figures at start + # @MakeTableContents { No } # list of tables at start + # @MakeContents { No } # make contents? Yes or No + @MakeContents { Yes } # make contents? Yes or No + # @ContentsGap { 0.20v @OrIfPlain 0f } # extra gap above minor entry + # @ContentsGapAbove { 0.80v @OrIfPlain 1f } # extra gap above major entry + # @ContentsGapBelow { 0.00v @OrIfPlain 0f } # extra gap below major entry + # @ContentsPartGapAbove { 1.00v @OrIfPlain 1f } # extra gap above `part' entry + # @ContentsPartGapBelow { 0.00v @OrIfPlain 0f } # extra gap below `part' entry + # @ContentsFormat { number @DotSep title } # contents entry format + # @ContentsLeader { .. } # leader symbol in contents + # @ContentsLeaderGap { 4s @OrIfPlain 2s } # gap between leaders + # @ContentsRightWidth { 3f @OrIfPlain 6s } # page numbers column width + # @MakeReferences { Yes } # make references? Yes or No + # @RefCiteStyle { [cite] } # citation style + # @RefCiteLabels { @RefNum } # citation items + # @RefNumbers { Arabic } # reference numbers + # @RefListFormat { Labels } # NoLabels, Labels, etc. + # @RefListLabels { [@RefNum] } # ref list label format + # @RefListTitle { references } # title of reference list + # @ChapRefListTitle { references } # title of chapter ref list + # @RefListIndent { 0s } # indent to left of labels + # @RefListRightIndent { 0s } # indent to right of items + # @RefListGap { @ListGap } # gap between ref list items + # @RefListFont { } # font used in reference list + # @RefListBreak { } # break style of ref list + # @RefListLabelWidth { @ListLabelWidth } # Labels column width + # @RefListSortKey { @Tag } # sorting key + # @MakeIndex { No } # make index? Yes or No + @MakeIndex { Yes } # make index? Yes or No + # @IndexFont { } # index entries font + # @IndexBreak { {oragged 1.2fx} @OrIfPlain {oragged 1fx} } # and break + # @IndexColumnNumber { 2 } # index columns (1 to 10) + # @IndexColumnGap { 1.00c @OrIfPlain 6s } # index column gap + # @MakeIndexA { No } # make index A? Yes or No + # @IndexAFont { } # index A entries font + # @IndexABreak { {oragged 1.2fx} @OrIfPlain {oragged 1fx} } # and break + # @IndexAColumnNumber { 2 } # index A columns (1 to 10) + # @IndexAColumnGap { 1.00c @OrIfPlain 6s } # index A column gap + # @MakeIndexB { No } # make index B? Yes or No + # @IndexBFont { } # index B entries font + # @IndexBBreak { {oragged 1.2fx} @OrIfPlain {oragged 1fx} } # and break + # @IndexBColumnNumber { 2 } # index B columns (1 to 10) + # @IndexBColumnGap { 1.00c @OrIfPlain 6s } # index B column gap + # @TopGap { 0.75c @OrIfPlain 2f } # gap between figures + # @MidGap { 0.75c @OrIfPlain 2f } # gap above/below body text + # @FootNoteNumbers { Arabic } # footnote numbers + # @FootNoteThrough { No } # numbered through chapter? + # @FootNoteLocation { ColFoot } # where the footnote appears + # @FootNoteFont { 0.80f } # font for footnotes + # @FootNoteBreak { 1.2fx @OrIfPlain 1fx } # break for footnotes + # @FootLen { 2.00c @OrIfPlain 10s } # length of footnote line + # @FootAboveGap { @DisplayGap } # gap above footnote line + # @FootGap { 0.20c @OrIfPlain 1fx } # gap between footnotes + # @MarginNoteFont { 0.80f } # font of margin notes + # @MarginNoteBreak { ragged 1.10fx } # break style of margin notes + # @MarginNoteHGap { 0.5c } # horizontal gap to notes + # @MarginNoteVGap { @DisplayGap } # min vertical gap between + # @MarginNoteWidth { 1.50c } # width of margin notes + # @EndNoteNumbers { Arabic } # endnote numbers + # @EndNoteFont { 0.80f } # font of endnotes + # @EndNoteBreak { 1.2fx @OrIfPlain 1fx } # break for endnotes + # @EndNoteGap { 0.20c @OrIfPlain 1f } # gap between endnotes + # @TheoremWord { theorem } # "Theorem" word, etc. + # @DefinitionWord { definition } # "Definition" word, etc. + # @ClaimWord { claim } # "Claim" word, etc. + # @PropositionWord { proposition } # "Proposition" word, etc. + # @LemmaWord { lemma } # "Lemma" word, etc. + # @CorollaryWord { corollary } # "Corollary" word, etc. + # @ExampleWord { example } # "Example" word, etc. + # @ProofWord { proof } # "Proof" word, etc. + # @PageHeaders { Simple } # None Simple Titles NoTitles + @PageHeaders { Titles } # None Simple Titles NoTitles + # @PageNumbers { Arabic } # page numbers + # @FirstPageNumber { 1 } # number of first page + # @IntroPageNumbers { Roman } # intro page numbers + # @IntroFirstPageNumber{ 1 } # number of first intro page + # @StructPageNums { No } # make structured page numbers + + # @OddTop { @Centre{- @PageNum -} } # Simple page headers + # @OddFoot { @Null } + # @EvenTop { @Centre{- @PageNum -} } + # @EvenFoot { @Null } + # @StartOddTop { @Null } + # @StartOddFoot { @Null } + # @StartEvenTop { @Null } + # @StartEvenFoot { @Null } + # @IntroOddTop { @Null } + # @IntroOddFoot { @Centre @PageNum } + # @IntroEvenTop { @Null } + # @IntroEvenFoot { @Centre @PageNum } + # @IntroStartOddTop { @Null } + # @IntroStartOddFoot { @Null } + # @IntroStartEvenTop { @Null } + # @IntroStartEvenFoot { @Null } + + # Titles, NoTitles headers + # @RunningOddTop { @I {@MinorNum @DotSep @MinorTitle} @Right @B @PageNum } + # @RunningOddFoot { @Null } + # @RunningEvenTop { @B @PageNum @Right @I {@MajorNum @DotSep @MajorTitle} } + # @RunningEvenFoot { @Null } + # @RunningStartOddTop { @Null } + # @RunningStartOddFoot { @Centre { Bold 0.8f } @Font @PageNum } + # @RunningStartEvenTop { @Null } + # @RunningStartEvenFoot { @Centre { Bold 0.8f } @Font @PageNum } + # @RunningIntroOddTop { @Null } + # @RunningIntroOddFoot { @Right @PageNum } + # @RunningIntroEvenTop { @Null } + # @RunningIntroEvenFoot { @PageNum } + # @RunningIntroStartOddTop { @Null } + # @RunningIntroStartOddFoot { @Null } + # @RunningIntroStartEvenTop { @Null } + # @RunningIntroStartEvenFoot { @Null } +} + + +############################################################################### +# # +# The @BookSetup @Use clause - options specific to books. # +# # +############################################################################### + +@Use { @BookSetup + # @TitlePageFont { Helvetica Base} # title page font (not size) + # @SeparateIntroNumbering { Yes } # separate intro page numbers + # @PrefaceAfterContents { No } # Yes or No + # @ChapterStartPages { Any } # Any, Odd, or Even + # @ReferencesBeforeAppendices { No } # references before appendices + # @PrefaceWord { preface } # word for "Preface" + # @ContentsWord { contents } # word for "Contents" + # @FigureListWord { figurelist } # word for "List of Figures" + # @TableListWord { tablelist } # word for "List of Tables" + # @IntroductionWord { introduction } # word for "Introduction" + # @ChapterWord { chapter } # word for "Chapter" + # @AppendixWord { appendix } # word for "Appendix" + # @IndexWord { index } # word for "Index" + # @IndexAWord { index } # word for "Index" (A) + # @IndexBWord { index } # word for "Index" (B) + # @ChapterNumbers { Arabic } # kind of chapter numbers + # @FirstChapterNumber { 1 } # first chapter number (Arabic) + # @SectionNumbers { Arabic } # kind of section numbers + # @FirstSectionNumber { 1 } # first section number (Arabic) + # @SubSectionNumbers { Arabic } # kind of subsection numbers + # @FirstSubSectionNumber { 1 } # first subsect number (Arabic) + # @SubSubSectionNumbers { Arabic } # kind of sub-subs. numbers + # @FirstSubSubSectionNumber { 1 } # first sub-sub number (Arabic) + # @AppendixNumbers { UCAlpha } # kind of appendix numbers + # @FirstAppendixNumber { 1 } # first appendix num (Arabic) + # @SubAppendixNumbers { Arabic } # kind of subappendix numbers + # @FirstSubAppendixNumber { 1 } # first sub-app num (Arabic) + # @SubSubAppendixNumbers { Arabic } # kind of sub-subapp. numbers + # @FirstSubSubAppendixNumber { 1 } # first sub-sub num (Arabic) + # @PartHeadingFont { Helvetica Base 2.50f } # part head font + # @PartHeadingBreak { clines 1.2fx nohyphen } # part head break + # @PartHeadingFormat { @CD number @DP @CD title } # part head format + # @ChapterHeadingFont { Bold 2.00f } # chapter head font + # @ChapterHeadingBreak { ragged 1.2fx nohyphen } # chapter head break + # @ChapterHeadingFormat { number @DotSep title } # format of chap. head + # @SectionHeadingFont { Bold } # section head font + # @SectionHeadingBreak { ragged 1.2fx nohyphen } # section head break + # @SectionHeadingFormat { number @DotSep title } # section head fmt + # @SubSectionHeadingFont { Bold } # subs. head font + # @SubSectionHeadingBreak { ragged 1.2fx nohyphen } # subs. head break + # @SubSectionHeadingFormat { number @DotSep title } # subs. head fmt + # @SubSubSectionHeadingFont { Slope } # sub-subs. head font + # @SubSubSectionHeadingBreak { ragged 1.2fx nohyphen } # sub-subs. head break + # @SubSubSectionHeadingFormat { number @DotSep title } # sub-subs. head fmt + # @AppendixHeadingFont { Bold 2.00f } # appendix head font + # @AppendixHeadingBreak { ragged 1.2fx nohyphen } # appendix head break + # @AppendixHeadingFormat { number @DotSep title } # appendix head fmt + # @SubAppendixHeadingFont { Bold } # subapp. head font + # @SubAppendixHeadingBreak { ragged 1.2fx nohyphen } # subapp. head break + # @SubAppendixHeadingFormat { number @DotSep title } # subapp. head fmt + # @SubSubAppendixHeadingFont { Slope } # sub-suba. head font + # @SubSubAppendixHeadingBreak { ragged 1.2fx nohyphen } # sub-suba. head break + # @SubSubAppendixHeadingFormat{ number @DotSep title } # sub-suba. head fmt + # @AbovePartGap { 4.00f } # gap above part title + # @AboveChapterGap { 3.00f } # above major titles + # @SectionGap { 2.0v @OrIfPlain 3f } # between sections + # @SubSectionGap { 1.5v @OrIfPlain 2f } # between subsects + # @SubSubSectionGap { 1.5v @OrIfPlain 2f } # between sub-subs. + # @SubAppendixGap { 2.0v @OrIfPlain 3f } # between subappendices + # @SubSubAppendixGap { 1.5v @OrIfPlain 2f } # between sub-subapps + # @IntroductionInContents { Yes } # add introduction to contents + # @PartInContents { Yes } # add parts to contents + # @ChapterInContents { Yes } # add chapters to contents + # @SectionInContents { Yes } # add sections to contents + # @SubSectionInContents { Yes } # add subsections to contents + # @SubSubSectionInContents { No } # add sub-subsects to contents + # @AppendixInContents { Yes } # add appendices to contents + # @SubAppendixInContents { Yes } # add subappendices to contents + # @SubSubAppendixInContents { No } # add sub-subapps to contents + # @ReferencesInContents { Yes } # add ref. section to contents + # @IndexInContents { Yes } # add index to contents + # @IndexAInContents { Yes } # add index A to contents + # @IndexBInContents { Yes } # add index B to contents + # @PartContentsIndent { 0.5rt } # indent of part contents entry + # @ChapterNumInTheorems { Yes } # theorem num has chapter num + # @SectionNumInTheorems { No } # theorem num has section num + # @SubSectionNumInTheorems { No } # theorem num has subsect num + # @SubSubSectionNumInTheorems { No } # theorem num has sub-ss. num + # @AppendixNumInTheorems { Yes } # theorem num has appendix num + # @SubAppendixNumInTheorems { No } # theorem num has sub-app num + # @SubSubAppendixNumInTheorems{ No } # theorem num has sub-sa. num + # @ChapterNumInDisplays { Yes } # display num has chapter num + # @SectionNumInDisplays { Yes } # display num has section num + # @SubSectionNumInDisplays { No } # display num has subsect num + # @SubSubSectionNumInDisplays { No } # display num has sub-ss. num + # @AppendixNumInDisplays { Yes } # display num has appendix num + # @SubAppendixNumInDisplays { Yes } # display num has sub-app num + # @SubSubAppendixNumInDisplays{ No } # display num has sub-sa. num + # @ChapterNumInFigures { Yes } # figure num has chapter num + # @SectionNumInFigures { No } # figure num has section num + # @SubSectionNumInFigures { No } # figure num has subsect num + # @SubSubSectionNumInFigures { No } # figure num has sub-ss. num + # @AppendixNumInFigures { Yes } # figure num has appendix num + # @SubAppendixNumInFigures { No } # figure num has sub-app num + # @SubSubAppendixNumInFigures { No } # figure num has sub-sa. num + # @ChapterNumInTables { Yes } # table num has chapter num + # @SectionNumInTables { No } # table num has section num + # @SubSectionNumInTables { No } # table num has subsect num + # @SubSubSectionNumInTables { No } # table num has sub-ss. num + # @AppendixNumInTables { Yes } # table num has appendix num + # @SubAppendixNumInTables { No } # table num has sub-app num + # @SubSubAppendixNumInTables { No } # table num has sub-sa. num + # @SectionNumInRunners { Yes } # runners have section num + # @SubSectionNumInRunners { No } # runners have subsect num + # @SubSubSectionNumInRunners { No } # runners have sub-ss. num + # @SubAppendixNumInRunners { Yes } # runners have sub-app num + # @SubSubAppendixNumInRunners { No } # runners have sub-sa. num + # @PrefacePrefix { } # for structured page nums + # @ContentsPrefix { } # for structured page nums + # @FigureContentsPrefix { } # for structured page nums + # @TableContentsPrefix { } # for structured page nums + # @IntroductionPrefix { } # for structured page nums + # @ChapterPrefix { } # for structured page nums + # @AppendixPrefix { } # for structured page nums + # @ReferencesPrefix { } # for structured page nums + # @IndexPrefix { } # for structured page nums + # @IndexAPrefix { } # for structured page nums + # @IndexBPrefix { } # for structured page nums +} + + +############################################################################### +# # +# @Database (and @SysDatabase) clauses go here. # +# # +############################################################################### + +@SysDatabase @RefStyle { refstyle } # reference printing styles diff --git a/doc/user/mydefs b/doc/user/mydefs new file mode 100644 index 0000000..2ef9639 --- /dev/null +++ b/doc/user/mydefs @@ -0,0 +1,203 @@ + + ################################################### + # # + # Lout keywords and @Code symbol. # + # # + ################################################### + + def @Code right x + { { Helvetica Base -1p } @Font lines @Break x } + + def @@BackEnd { @Code "@BackEnd" } + def @@Begin { @Code "@Begin" } + def @@Break { @Code "@Break" } + def @@Case { @Code "@Case" } + def @@Database { @Code "@Database" } + def @@End { @Code "@End" } + def @@Font { @Code "@Font" } + def @@Char { @Code "@Char" } + def @@Galley { @Code "@Galley" } + def @@Graphic { @Code "@Graphic" } + def @@HAdjust { @Code "@HAdjust" } + def @@HContract { @Code "@HContract" } + def @@HCover { @Code "@HCover" } + def @@HExpand { @Code "@HExpand" } + def @@HScale { @Code "@HScale" } + def @@High { @Code "@High" } + def @@HShift { @Code "@HShift" } + def @@Include { @Code "@Include" } + def @@Insert { @Code "@Insert " } + def @@IncludeGraphic { @Code "@IncludeGraphic" } + def @@Key { @Code "@Key" } + def @@LClos { @Code "@LClos" } + def @@LEnv { @Code "@LEnv" } + def @@LInput { @Code "@LInput" } + def @@LVis { @Code "@LVis" } + def @@Moment { @Code "@Moment" } + def @@Next { @Code "@Next" } + def @@Null { @Code "@Null" } + def @@OneCol { @Code "@OneCol" } + def @@OneRow { @Code "@OneRow" } + def @@Open { @Code "@Open" } + def @@PAdjust { @Code "@PAdjust" } + def @@PrependGraphic { @Code "@PrependGraphic" } + def @@Rotate { @Code "@Rotate" } + def @@Scale { @Code "@Scale" } + def @@SetColor { @Code "@SetColor" } + def @@SetColour { @Code "@SetColour" } + def @@Language { @Code "@Language" } + def @@CurrLang { @Code "@CurrLang" } + def @@Space { @Code "@Space" } + def @@SysDatabase { @Code "@SysDatabase" } + def @@SysInclude { @Code "@SysInclude" } + def @@SysIncludeGraphic { @Code "@SysIncludeGraphic" } + def @@SysPrependGraphic { @Code "@SysPrependGraphic" } + def @@Tag { @Code "@Tag" } + def @@Tagged { @Code "@Tagged" } + def @@Use { @Code "@Use" } + def @@VAdjust { @Code "@VAdjust" } + def @@VContract { @Code "@VContract" } + def @@VCover { @Code "@VCover" } + def @@VExpand { @Code "@VExpand" } + def @@VScale { @Code "@VScale" } + def @@VShift { @Code "@VShift" } + def @@Wide { @Code "@Wide" } + def @@Yield { @Code "@Yield" } + + + ################################################### + # # + # Miscellaneous symbols used in the guide. # + # # + ################################################### + + def @TeX + { @OneCol { T &0.4fo {-0.2f @VShift E} &0.45fo X } + } + + def @LaTeX + { @OneCol { L &0.3fo { +0.1f @VShift 0.8f @Font A } &0.4fo @TeX } + } + + import @BasicSetup + def @Batlow { Batlow Food Distributors Pty. Ltd. } + + import @BasicSetup + def @GreyBox right x { @Box paint { lightgrey } x } + + import @BasicSetup + def @HeadingBox left x right y + { + @Box { @CentredDisplay @Heading x y } + } + + def @FilledBox + { + @BackEnd @Case { + PostScript @Yield { + { "0 0 moveto xsize 0 lineto xsize ysize lineto 0 ysize lineto" + "closepath fill" + } @Graphic { 0.6f @High ^/ 0.4f @High 4f @Wide } + } + PDF @Yield { + { "0 0 m __xsize 0 l __xsize __ysize l 0 __ysize l h f" + } @Graphic { 0.6f @High ^/ 0.4f @High 4f @Wide } + } + } + } + + import @Eq + def epi { p sub i ` log sub 2 ` p sub i } + + import @Eq + def ep right x { p sub x ` log sub 2 ` p sub x } + + def @Dbl left x right y + { 1.95i @Wide + { 1.25i @Wide { |1rt @Code x } |0.2i @Eq {non y} } + } + + import @Eq + def @ExA { 1 over sqrt { 1 - 4 x sup 2 } } + + def @@Diag { @Code "@Diag" } + + extend @DiagSetup @Diag + macro @MyNode { + @Node + outline { + LR:: { xsize 0 } + LR:< 0d + UL:: { 0 ysize } + UL:< 270d + 0 0 LR UL 0 0 + } + } + + extend @DiagSetup @Diag + macro @MyLink { + @Link + path { + FROM:: from + TO:: to + FROM TO + } + } + + def @ShowHMark + named linewidth { 0.015 cm } + named linestyle { dashed } + named dashlength { 0.15 cm } + named paint { light } + 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 + } + } + + def @ZeroWidth right x { @OneCol { |0io x |0io } } + + def @SomeText + { +Johnson suddenly uttered, in a strong determined tone, an apophegm, at +which many will start: `Patriotism is the last refuge of a scoundrel.' + } + + import @DiagSetup + def @OpenCircle { @Diag { @Circle margin { 0.2f } } } + + import @DiagSetup + def @ClosedCircle { @Diag { @Circle paint { black } margin { 0.2f } } } + + import @TblSetup @BasicSetup + def @AmberLight + { + @OneRow @Tbl + aformat { @Cell A } + marginhorizontal { 0i } + marginvertical { 0i } + strut { no } + rule { no } + paint { no } + { + @Rowa A { @OpenCircle } + @MarkRowa A { @ClosedCircle } + @Rowa A { @OpenCircle } + } + } diff --git a/doc/user/pascal b/doc/user/pascal new file mode 100644 index 0000000..41376df --- /dev/null +++ b/doc/user/pascal @@ -0,0 +1,162 @@ +@Chapter + @Title { Pascal and Modula-2 Programs } +@Begin +@LP +There is a @Code "@Pas" symbol for printing Pascal programs +pascal @Index { Pascal programs } +pas. @Index @Code "@Pas" +@Cite { $jensen1975pascal }. No attempt is made to follow any +particular printing standard; the design simply reflects this author's +taste. To use {@Code "@Pas"}, place @Code "@SysInclude { pas }" at the +start of your document in the usual way. A Pascal program or program +fragment is entered like this: +@ID @Code { +"@ID @Pas {" +"procedure PriDelete(x: PriEntry; var Q: PriorityQueue);" +" var i: integer;" +"begin" +" with Q^ do begin" +" size := size - 1;" +" if x^.back <= size then" +" begin" +" i := x^.back;" +" A[i] := A[size + 1];" +" A[i]^.back := i;" +" PriAddRoot(i, Q);" +" PriAddLeaf(i, Q)" +" end" +" end" +"end;" +"}" +} +This produces +@ID @Pas { +procedure PriDelete(x: PriEntry; var Q: PriorityQueue); + var i: integer; +begin + with Q^ do begin + size := size - 1; + if x^.back <= size then + begin + i := x^.back; + A[i] := A[size + 1]; + A[i]^.back := i; + PriAddRoot(i, Q); + PriAddLeaf(i, Q) + end + end +end; +} +Blank lines, line breaks, indents and spaces in the input are respected, +with a tab being considered equal to eight spaces. @Code "@Pas" can also +be used within a paragraph to produce a fragment like +@OneCol @Pas { A[i..j] }. Use @Code "@OneCol @Pas { ... }" to prevent the +result from breaking over two lines. +@PP +@Code "@Pas" does not attempt to rearrange the program in any way. Each +item is simply printed according to the following plan: +@ID { +7c @Wide { + @Code and |2.5ct @Pas { and } +//1vx @Code array |2.5ct @Pas { array } +//1vx @Code begin |2.5ct @Pas { begin } +//1vx @Code case |2.5ct @Pas { case } +//1vx @Code const |2.5ct @Pas { const } +//1vx @Code div |2.5ct @Pas { div } +//1vx @Code do |2.5ct @Pas { do } +//1vx @Code downto |2.5ct @Pas { downto } +//1vx @Code else |2.5ct @Pas { else } +//1vx @Code end |2.5ct @Pas { end } +//1vx @Code file |2.5ct @Pas { file } +//1vx @Code for |2.5ct @Pas { for } +//1vx @Code forward |2.5ct @Pas { forward } +//1vx @Code function |2.5ct @Pas { function } +//1vx @Code goto |2.5ct @Pas { goto } +//1vx @Code if |2.5ct @Pas { if } +//1vx @Code in |2.5ct @Pas { in } +//1vx @Code label |2.5ct @Pas { label } +//1vx @Code mod |2.5ct @Pas { mod } +//1vx @Code nil |2.5ct @Pas { nil } +//1vx @Code not |2.5ct @Pas { not } +//1vx @Code of |2.5ct @Pas { of } +//1vx @Code or |2.5ct @Pas { or } +//1vx @Code otherwise |2.5ct @Pas { otherwise } +//1vx @Code packed |2.5ct @Pas { packed } +//1vx @Code procedure |2.5ct @Pas { procedure } +//1vx @Code program |2.5ct @Pas { program } +//1vx @Code record |2.5ct @Pas { record } +//1vx @Code repeat |2.5ct @Pas { repeat } +//1vx @Code set |2.5ct @Pas { set } +//1vx @Code then |2.5ct @Pas { then } +//1vx @Code to |2.5ct @Pas { to } +//1vx @Code type |2.5ct @Pas { type } +//1vx @Code until |2.5ct @Pas { until } +//1vx @Code var |2.5ct @Pas { var } +//1vx @Code while |2.5ct @Pas { while } +//1vx @Code with |2.5ct @Pas { with } +} | 7c @Wide { + @Code "0" |2.5ct @Pas { 0 } +//1vx @Code "1" |2.5ct @Pas { 1 } +//1vx @Code "2" |2.5ct @Pas { 2 } +//1vx @Code "3" |2.5ct @Pas { 3 } +//1vx @Code "4" |2.5ct @Pas { 4 } +//1vx @Code "5" |2.5ct @Pas { 5 } +//1vx @Code "6" |2.5ct @Pas { 6 } +//1vx @Code "7" |2.5ct @Pas { 7 } +//1vx @Code "8" |2.5ct @Pas { 8 } +//1vx @Code "9" |2.5ct @Pas { 9 } +//1vx @Code "." |2.5ct @Pas { . } +//1vx @Code "," |2.5ct @Pas { , } +//1vx @Code ":" |2.5ct @Pas { : } +//1vx @Code ";" |2.5ct @Pas { ; } +//1vx @Code "'" |2.5ct @Pas { ' } +//1vx @Code "`" |2.5ct @Pas { ` } +//1vx @Code "+" |2.5ct @Pas { + } +//1vx @Code "-" |2.5ct @Pas { - } +//1vx @Code "*" |2.5ct @Pas { * } +//1vx @Code "/" |2.5ct @Pas { / } +//1vx @Code "(" |2.5ct @Pas { ( } +//1vx @Code ")" |2.5ct @Pas { ) } +//1vx @Code "[" |2.5ct @Pas { [ } +//1vx @Code "]" |2.5ct @Pas { ] } +//1vx @Code "^" |2.5ct @Pas { ^ } +//1vx @Code ".." |2.5ct @Pas { .. } +//1vx @Code "=" |2.5ct @Pas { = } +//1vx @Code "<" |2.5ct @Pas { < } +//1vx @Code ">" |2.5ct @Pas { > } +//1vx @Code "<>" |2.5ct @Pas { <> } +//1vx @Code "<=" |2.5ct @Pas { <= } +//1vx @Code ">=" |2.5ct @Pas { >= } +//1vx @Code ":=" |2.5ct @Pas { := } +} +} +Anything not mentioned here will appear in italic font. +@PP +Unlike the @Code "@CP" symbol from the previous chapter, the @Code "@Pas" +symbol is a quick-and-dirty production which does not offer you any options, +or indeed attempt to solve every problem of Pascal formatting. In +particular, Pascal strings need attention before formatting by +{@Code "@Pas"}. Their interiors are best enclosed in double quotes to +prevent the above transformations from occurring inside them. Any +@Code "\\" or @Code "\"" characters inside strings will need to be +replaced by @Code "\\\\" and @Code "\\\"" respectively, and the opening +quote should be replaced by {@Code "`"}. +@PP +Similar remarks apply to Pascal comments; don't forget that @Code "{" +and @Code "}" must be enclosed in double quotes. Alternatively, a +@Code "@Com" symbol can be placed in front of a comment enclosed +in braces. It will add literal braces: +@ID @Code { +"@Com { A Pascal comment }" +} +has result +@ID @Pas { +@Com { A Pascal comment } +} +It may still be necessary to enclose the interior in double quotes. +@PP +There is a @Code "@Modula" symbol which allows you to format Modula-2 +programs in the same way as @Code "@Pas" does for Pascal. You get it +via {@Code "@SysInclude { modula }"}, and once again it is a quick-and-dirty +production. +@End @Chapter diff --git a/doc/user/preface b/doc/user/preface new file mode 100644 index 0000000..eada554 --- /dev/null +++ b/doc/user/preface @@ -0,0 +1,66 @@ +@Preface @Begin +@LP +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 +@PP +There are three other documents describing Lout: the Expert's Guide +@Cite { $kingston1995lout.expert }, which you need if you want to add +new features to Lout; a journal paper on the design and implementation +of Lout @Cite { $kingston1993lout.design }; and a set of overhead +transparencies @Cite { $kingston1994lout.overheads } that cover much +the same ground as this Guide. These documents are all distributed +with the software. +@PP +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.cs.su.oz.au/jeff/lout" +in which may be found a gzipped tar file containing the main distribution +(currently {@Code "lout-3.17.tar.gz"}), and various other things including +a PostScript version of this guide. The distribution contains source code, +libraries, documentation, license, and installation instructions. +@PP +A mailing list has been set up for discussion of all topics related to +Lout. To subscribe, send email to @Code "lout-request@ptc.spbu.ru" +containing the word @Code "subscribe" in the Subject line. To post an +item, send email to {@Code "lout@ptc.spbu.ru"}; it will be forwarded to +all subscribers via email. To unsubscribe, send email to +@Code "lout-request@ptc.spbu.ru" containing the word @Code "unsubscribe" +in the Subject line. +@PP +Lout began in 1984 as a research project into the design of a high-level +language for document formatting. At that time my name for the subject +was `document layout,' and this terminology survives in the name +`Lout'. The initial design +was strongly influenced by Brian W. Kernighan and Lorinda L. Cherry's eqn +kernighan @Index { Kernighan, Brian W. } +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.influence @SubIndex { influence on Lout } +reid.b @Index { Reid, Brian K. } +research phase ended in October 1991 with the first public release of Lout. +@PP +Since then the system has been steadily improved and extended. Optimal +paragraph breaking and automatic hyphenation were copied from Donald +knuth @Index { Knuth, D. E. } +tex. @Index { @TeX } +E. Knuth's @TeX system @Cite { $knuth1984tex }, and the optimal paragraph +breaking algorithm was applied to the problem of producing optimal page +breaks. The first implementations of horizontal galleys and optimal +page breaking were by my student Gabor Inokai. Vincent Tan contributed +the PDF back end. The strongest influence during this period has come from +Lout's users; indeed the number of people who have offered comments and +suggestions is so great that it is quite out of my power to acknowledge them +individually. I hope that seeing their ideas adopted will be thanks enough. +@DP +@RLD lines @Break { +Jeffrey H. Kingston +Basser Department of Computer Science +The University of Sydney 2006, Australia +@Code "jeff@cs.usyd.edu.au" +} +@End @Preface diff --git a/doc/user/ref b/doc/user/ref new file mode 100644 index 0000000..6ea5782 --- /dev/null +++ b/doc/user/ref @@ -0,0 +1,31 @@ +@Chapter + @Title { References } + @Tag { biblio } +@Begin +@LP +The simple way to make a list of references is to put them in a numbered +references. @Index { references } +or tagged list at the end of your document. If you use references only +rarely, that is probably the best way, but if you use them frequently this +chapter will save you hours of work in the long run. +@PP +Some good general principles and many examples have been given by van Leunen +van.leunen. @Index { van Leunen, Mary-Claire } +@Cite { $vanleunen1992handbook }. Broadly speaking Lout follows her +recommendations, with some unification and scaling back as is inevitable +with software. Scribe @Cite { $reid1980scribe } +latex. @Index @LaTeX +scribe. @RawIndex Scribe +scribe.reference @SubIndex { reference formatting } +and @LaTeX @Cite { $lamport1986latex } followed the first edition of the +same source, so translation from Scribe and @LaTeX references is +fairly straightforward. +@BeginSections +@Include { ref_sett } +@Include { ref_cite } +@Include { ref_labe } +@Include { ref_entr } +@Include { ref_chan } +@Include { ref_crea } +@EndSections +@End @Chapter diff --git a/doc/user/ref_chan b/doc/user/ref_chan new file mode 100644 index 0000000..f7114fb --- /dev/null +++ b/doc/user/ref_chan @@ -0,0 +1,200 @@ +@Section + @Title { Changing the appearance of citations and the reference list } + @Tag { changeref } +@Begin +@PP +By default, citations appear like this @Cite { $kingston1995lout.expert }, +and the reference list appears like the one at the end of this +document, with the entries numbered, and sorted by their @Code "@Tag" +options. This section explains how to change all this, by setting +options in the setup file. +@PP +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 }" +} +makereferences.sym @Index { @Code "@MakeReferences" } +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" } +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 +example, the default value shown above encloses each citation in +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" } +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 +{@NumberOf entries}: +@ID @OneRow @Tab + @Fmta { @Col @Code A ! @Col B } +{ +@Rowa + A { "@RefCiteLabels { @RefNum }" } + B { [3] } +@Rowa + A { "@RefCiteLabels { @Label }" } + B { [Kin93] } +@Rowa + A { "@RefCiteLabels { @Author, @Year }" } + B { [Jeffrey H. Kingston, 1993] } +} +The value of @Code "@RefCiteLabels" may be any object. The @Code "@Label" +symbol will produce the @Code "label" option of @Code "$" or @Code "@Ref" +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" } +@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 +usual for numbering in Lout. If you don't use {@Code "@RefNum"}, +@Code "@RefNumbers" has no effect. +@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" } +determines the overall format of the list. Here is what its four +@NoCite { $strunk1979style } possible values do: +@ID @Tab + @Fmta { @Col @Code A ! @Col @OneCol B } + vmargin { 0.3v } +{ +@Rowa + A { "@RefListFormat { NoLabels }" } + B { @RefPrint strunk1979style } +@Rowa +@Rowa + A { "@RefListFormat { Labels }" } + B { 2f @Wide {{@NumberOf strunk1979style}.} | @RefPrint strunk1979style } +@Rowa +@Rowa + A { "@RefListFormat { DropLabels }" } + B { {@NumberOf strunk1979style}. //1vx + 2f @Wide {} | @RefPrint strunk1979style + } +@Rowa +@Rowa + A { "@RefListFormat { InLabels }" } + B { {@NumberOf strunk1979style}. &2s @RefPrint strunk1979style } +} +@Code "@RefListFormat" is not concerned with the appearance of the +labels and references, only with where they appear. +@PP +@Code "@RefListLabels" determines the appearance of the labels in the +reflistlabels.sym @Index { @Code "@RefListLabels" } +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 +options of @Code "@Reference" within it. The default value, +@ID @Code "@RefListLabels { @RefNum. }" +produces a numbered reference list in the style of +{@Code "@NumberedList"}. Another useful value is +@ID @Code "@RefListLabels { [@Label] }" +which produces the @Code "@Label" option of the reference, or the +@Code "label" option of the citation if there is one, enclosed in +brackets. If you do switch to non-numeric labels you will need to +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" } +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" } +{@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" } +{@Code "@RefListGap"} determine the left indent, right indent, and gap +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 +@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 }" +} +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" } +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 +{@Code "InLabels"}). This is different to {@Code "@RefListIndent"}, +which determines the distance from the edge of the column to the +left edge of the item. +@PP +Particular care is needed when @Code "@RefListFormat" +is @Code Labels and the labels are non-numeric, for then if the +labels are too wide they will overstrike the references. The default +value, {@Code 2.00f}, is twice the current font size. It may be +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 +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; the other popular 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 +to the citation if there is one. There is no way to sort by order of +first appearance in the document. +@PP +@Code "@RefListSortKey" may be any sequence of words +and options from the @Code "@Reference" symbol, but not @Code "@RefNum" +for obvious reasons. A possible more elaborate sorting key is +@ID @Code "@RefListSortKey { @Author:@Year:@Tag }" +sorting first by author, then by year within each author, and finally +by tag. However you +are supposed to choose tags which have this effect, and that is more +reliable since the modern practice is to put the authors' surnames +after their given names. There seems to be little practical use for +sorting keys other than {@Code "@Tag"} and {@Code "@Label"}. +@PP +A colon within the @Code "@RefListSortKey" option is converted by Lout +into a character smaller than any printable character, which ensures that +the sorting is carried out separately on the three fields. It is essential +that the sort key uniquely identify the reference, because if two sort +keys are equal only one of the references will be printed. The easiest +way to ensure this is to always include @Code "@Tag" in the sort key. +@End @Section diff --git a/doc/user/ref_cite b/doc/user/ref_cite new file mode 100644 index 0000000..89958b9 --- /dev/null +++ b/doc/user/ref_cite @@ -0,0 +1,90 @@ +@Section + @Title { Citation } + @Tag { citation } +@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 }." +} +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 +special meaning: it causes a citation to be made of the reference whose +@Code "@Tag" option is the word following the @Code "$" symbol: +@ID { +This feature is beyond our scope @Cite { $kingston1995lout.expert, page 97 }. +} +The reference itself will appear automatically in a reference list at +the end of the document, and the citation(s) will be enclosed in brackets +as shown. There is no need to write @Code "${kingston1995lout.expert}," +as would normally be the case, because within @Code "@Cite" special +arrangements are made to prevent commas and semicolons from being a +nuisance. +@PP +A reference may be cited many times, but it will appear in the +reference list only once. The references will ordinarily be sorted by +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" +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. +@PP +It is quite all right to cite a reference from within a footnote, figure, +table, or index entry. The reference will appear in the closest +reference list following the citation point in the final printed document, +or if there is no such list, the closest preceding reference list. This +is fine in documents with just one reference list; but when using +@Code "@ChapCite" in books, if the citation point appears after the intended +reference list (because the footnote or figure has floated past the reference +list at the end of the chapter), the reference will come out in the wrong list. +@PP +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" +@ID @Code { +"... our scope @NoCite { $kingston1995lout.expert, $kingston1993lout.design }." +} +produces +@ID { +... our scope @NoCite { $kingston1995lout.expert, $kingston1993lout.design }. +} +with the @Code "@NoCite" symbol and any preceding space removed. The +references will nevertheless appear in the reference list as usual. There +is a @Code "@NoChapCite" symbol that combines @Code "@NoCite" and +no.chap.cite @Index @Code "@NoChapCite" +{@Code "@ChapCite"}. For compatibility with previous versions of Lout, +there is a @Code "@Ref" symbol: +ref. @Index @Code "@Ref" +@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" +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 } +@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" +} +might appear in someone's resume. +@End @Section diff --git a/doc/user/ref_crea b/doc/user/ref_crea new file mode 100644 index 0000000..994f8d3 --- /dev/null +++ b/doc/user/ref_crea @@ -0,0 +1,139 @@ +@Section + @Title { Creating your own entry types and formats } + @Tag { refstyles } +@Begin +@PP +Although the set of options to the @Code "@Reference" symbol +({@Code "@Tag"}, {@Code "@Type"}, {@Code "@Author"}, etc.) is fixed, you +can add your own reference types and change the formatting of existing types. +@PP +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" +@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" +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} +which is where all the standard databases are kept. To change the +formatting of a reference type, or to add your own types, you need to +create your own reference styles database file by copying and modifying +{@Code "refstyle.ld"}. +@PP +To find out the name of the Lout system database directory, type the +Unix command +@ID @Code "lout -V" +Then, supposing that the Lout system database directory is +{@Code "/usr/lout/data"}, type +@ID @Code "cp /usr/lout/data/refstyle.ld mystyle.ld" +to place a copy of the @Code "refstyle.ld" database file in your +mystyle.ld.file @Index { @Code "mystyle.ld" file} +directory, renaming it {@Code "mystyle.ld"}. Since @Code "refstyle.ld" +is read-only, you may also need to change the mode of @Code "mystyle.ld" +to be writable (by @Code "chmod +w mystyle.ld" in Unix). Now replace +@ID @Code "@SysDatabase @RefStyle { refstyle }" +at the end of your setup file by +@ID @Code "@Database @RefStyle { mystyle }" +and Lout will read its reference styles from @Code "mystyle.ld" instead +of {@Code "refstyle.ld"}. Since the two are at +present identical, this has changed nothing so far; but now any changes +you make to @Code "mystyle.ld" will affect your document. Changing +@Code "@SysDatabase" to @Code "@Database" makes Lout search your +current directory for {@Code "mystyle.ld"}, whereas @Code "@SysDatabase" +searches only the system directory. +@PP +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\" }" +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." +" }" +" }" +"}" +} +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 +defines how references of type @Code Book will be printed. Fortunately, +apart from this one word these two lines are the same in every +reference style entry so you don't need to understand them. The +important part is in the middle: +@ID @Code "@Author. @I @Title. @Publisher, @Year." +The meaning should be clear: first print the author option and a full +stop, then the title option and another full stop in italics, and so +on. To change the formatting of books, change this object. To create +a new reference type, copy the entire database entry, change @Code Book +to a new name of your choice, and change the middle part. Don't forget +to delete the index file @Code "mystyle.li" afterwards, if there is one, +so that Lout knows to generate it afresh. +@PP +Although the entry shown above is perfectly viable, the real entry for +@Code Book is much more complicated, in part because there are more +options than those basic four, but mainly because the real entry goes +to great lengths to do the right thing when options are omitted: +@ID @Tab + vmargin { 0.45vx } + @Fmta { @Col @Code A ! @Col @Code B } +{ +@Rowa A { "{ Book @RefStyle @Style" } +@Rowa A { " { @Reference&&reftag @Open" } +@Rowa A { " {" } +@Rowa A { " { @Author. {}" } B { "} @If @Author" } +@Rowa A { " { @I @Title" } B { "} @If @Title" } +@Rowa A { " { @Word&¬itle" } B { "} @If @Not @Title" } +@Rowa A { " { , @Pinpoint" } B { "} @If @Pinpoint" } +@Rowa A { " { , @Word&&pages @NumSep @Pages" } B { "} @If @Pages" } +@Rowa A { " { , @Word&&page @NumSep @Page" } B { "} @If @Page" } +@Rowa A { " { . @TitleNote" } B { "} @If @TitleNote" } +@Rowa A { " { . @HowPublished" } B { "} @If @HowPublished" } +@Rowa A { " { . @Publisher" } B { "} @If @Publisher" } +@Rowa A { " { . @Organization" } B { "} @If @Organization" } +@Rowa A { " { . @Institution" } B { "} @If @Institution" } +@Rowa A { " { , @Address" } B { "} @If @Address" } +@Rowa A { " { . @Edition" } B { "} @If @Edition" } +@Rowa A { " { , @Month @Year" } B { "} @If @Year @And @Month" } +@Rowa A { " { , @Year " } B { "} @If @Year @And @Not @Month" } +@Rowa A { " { ." } B { "} @If @True" } +@Rowa A { " { {} URL @URL." } B { "} @If @URL" } +@Rowa A { " { {} @Note" } B { "} @If @Note" } +@Rowa A { " }" } +@Rowa A { " }" } +@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 +complexity of the whole setup. +@PP +The objects subject to @Code "@If" are printed with no space preceding +them; any space in the final print will be the result of space within +them, not between them. This is why @Code "@If @True" is not redundant. +@PP +The object @Code "@Word&¬itle" produces @Code "No title" in the +current language; @Code "@Word&&pages" produces {@Code pages} in the +current language, and so on. Consult database @Code "standard.ld" for +standard.ld.file @Index { @Code "standard.ld" file } +other standard words and phrases, and page {@PageOf numsep} for +{@Code "@NumSep"}. +@End @Section diff --git a/doc/user/ref_entr b/doc/user/ref_entr new file mode 100644 index 0000000..63516b2 --- /dev/null +++ b/doc/user/ref_entr @@ -0,0 +1,293 @@ +@Section + @Title { Constructing database entries } + @Tag { entries } +@Begin +@PP +Here is the complete, fixed list of options that you may give to the +@Code "@Reference" symbol: +@ID @Tab + vmargin { 0.5vx } + @Fmta { @Col @Code A ! @Col B } +{ +@Rowa + A { "{ @Reference" } +@Rowa + A { " @Tag {}" } + B { Used to cite this reference } +@Rowa + A { " @Type {}" } + B { The type of reference, for example {@Code Book}, {@Code Article} } +@Rowa + A { " @Abstract {}" } + B { Not used, intended to hold an abstract } +@Rowa + A { " @Address {}" } + B { The address of a publisher, organization, or institution } +@Rowa + A { " @Annote {}" } + B { Not used, intended for annotations } +@Rowa + A { " @Author {}" } + B { The author(s) or editor(s) } +@Rowa + A { " @Day {}" } + B { The day of the month, for newspaper articles } +@Rowa + A { " @Edition {}" } + B { The edition, for example @Code "Second Edition" } +@Rowa + A { " @HowPublished {}" } + B { How something strange has been published } +@Rowa + A { " @InAuthor {}" } + B { The author of the work that the cited work appears within } +@Rowa + A { " @InTitle {}" } + B { The title of the work that the cited work appears within } +@Rowa + A { " @Institution {}" } + B { The institution or school } +@Rowa + A { " @Journal {}" } + B { The journal name } +@Rowa + A { " @Keywords {}" } + B { Not used, intended to hold keywords } +@Rowa + A { " @Label {}" } + B { The label of a labelled reference } +@Rowa + A { " @Month {}" } + B { The month of publication or writing } +@Rowa + A { " @Note {}" } + B { Any additional helpful information } +@Rowa + A { " @Number {}" } + B { The number of a technical report } +@Rowa + A { " @Organization {}" } + B { The organization sponsoring the work } +@Rowa + A { " @Page {}" } + B { Page number if only one, for example @Code "23" } +@Rowa + A { " @Pages {}" } + B { Page numbers if more than one, for example @Code "23--47" } +@Rowa + A { " @Pinpoint {}" } + B { A point or part of the work, for example @Code "Chapter VI" } +@Rowa + A { " @Publisher {}" } + B { The publisher of the work } +@Rowa + A { " @Title {}" } + B { The title of the work } +@Rowa + A { " @TitleNote {}" } + B { Additional title information (series, editor, etc.) } +@Rowa + A { " @TRType {}" } + B { The type of a technical report, for example @Code "Research Note" } +@Rowa + A { " @URL {}" } + B { The URL of the reference } +@Rowa + A { " @Volume {}" } + B { The volume of a journal } +@Rowa + A { " @Year {}" } + B { The year of publication or writing } +@Rowa + A { "}" } +} +Every reference may contain any of these options, although, depending +on the {@Code "@Type"} option, only some will be printed. You can't give +an option twice; in particular, multiple authors must be placed +within one @Code "@Author" option, arranged as you want them to appear. Here +is the complete set of values that you may give to the @Code "@Type" option: +@ID @Tab + vmargin { 0.5vx } + @Fmta { @Col @Code A ! @Col @Code B ! @Col @Code C ! @Col @Code D } +{ + @Rowa + A { Book } + B { TechReport } + C { Article } + D { InBook } + @Rowa + A { Proceedings } + B { MastersThesis } + C {} + D { InProceedings } + @Rowa + A { PhDThesis } + B { Misc } + C {} + D {} +} +Each column represents one broad category of reference type: the first +contains large works; the second contains small works not appearing +within anything else (although possibly part of a series); the third +contains small works appearing within an ongoing forum for such works; +and the fourth contains small works appearing within large works. In each +case, the reference may be to the work as a whole, or to one point or part +of it (known as pinpointing). +@PP +Some care is needed when choosing the @Code "@Tag" option, since references +are both cited and sorted by tag. It is best to choose a three-part +tag consisting of the first author's surname and possibly initial, the +year of publication, and a brief reminder of the contents: +@ID @Code "@Tag { kingston1995lout.expert }" +Keep to lower-case letters, since mixed cases confuse the sorting, and +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 "~" +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 +be able to break lines at @Code "/" characters, which is very useful +since URLs tend to be long and prone to causing bad line breaks. +@PP +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. }" +"}" +} +And here is what it produces: +@ID @RefPrint homer.odyssey +The only compulsory options are {@Code "@Tag"}, {@Code "@Type"}, and +{@Code "@Title"}, and Lout will carefully adjust the formatting to the +right thing when you omit others. A basic book would have just +{@Code "@Tag"}, {@Code "@Type"}, {@Code "@Author"}, {@Code "@Title"}, +{@Code "@Publisher"}, and {@Code "@Year"} options. +@PP +@Code Proceedings is similar, except you +proceedings.ref.type @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: +@ID @Code "@Author { P. W. Lamb, 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 } +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 }" +"}" +} +Here is the result: +@ID @RefPrint christofides1976tsp +The two novelties here are the @Code "@Number" option, which is the +number of the report, and the `Tech. Rep.' phrase. If you +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 } +{@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 }" +"}" +} +The result of this is +@ID @RefPrint kingston1993lout.design +All are optional, as usual. Notice that @Code "@Pages" and @Code "@Page" +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 } +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 }" +"}" +} +@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 } +similar to {@Code InBook}. +@PP +A database usually has a long life, and some day it might find itself +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 }" +"}" +} +(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 +reference appears. +@End @Section diff --git a/doc/user/ref_labe b/doc/user/ref_labe new file mode 100644 index 0000000..1b8cc54 --- /dev/null +++ b/doc/user/ref_labe @@ -0,0 +1,65 @@ +@Section + @Title { Labelled (as opposed to numbered) references } + @RunningTitle { Labelled references } + @Tag { labelled } +@Begin +@PP +Lout ordinarily assigns a number to each reference, and prints this +labelled.refs @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 }" +} +Then make sure that every reference you cite has a {@Code "@Label"} option: +@ID @OneRow @Code { +"{ @Reference" +" @Tag { kingston1995lout.expert }" +" @Type { TechReport }" +" @Label { Kin94 }" +" ..." +"}" +} +@Code "@Label" may contain several words, and even font changes, but not +an arbitrary object. +@PP +The effect of these changes is that your references will now be labelled +with their @Code "@Label" options instead of with numbers, and they will +be sorted by label instead of by tag. However, tags are still used when +citing. +@PP +The big problem with labels is that they vary from document to +document, either because of a change of style or because the usual +first few letters of the authors' names plus year has to be augmented +with {@Code a}, {@Code b}, {@Code c} etc. to distinguish publications +by the same authors in the same year. To help you overcome these +problems, the @Code "$" symbol has a @Code "label" option: +@ID @Code { +"@Cite { $ label { Kin94a } kingston1995lout.expert, ... }" +} +The @Code "@Ref" and @Code "@ChapRef" symbols also have a @Code label +option. If you use this option, it will be used to label the reference +instead of the @Code "@Label" option from the @Code "@Reference" symbol +(indeed, the @Code "@Reference" symbol need have no @Code "@Label" option +in this case). But note that using @Code "label" does not itself give +you labelled references; you get them with the setup file options as +explained above. +@PP +If your labels turn out to be too wide for the space allowed for them +in the reference list, you have two alternatives. One is to increase +the @Code "@RefListLabelWidth" setup file option shown above, since it +determines this space. The other is to change the @Code "@RefListFormat" +setup file option to {@Code "DropLabels"}, which produces drop items: +@ID @OneRow { +@RawTaggedList +@DTI { Kin94a. } @RefPrint kingston1995lout.expert +@RawEndList +} +Then it won't matter how wide your labels are. +@End @Section diff --git a/doc/user/ref_sett b/doc/user/ref_sett new file mode 100644 index 0000000..283cb11 --- /dev/null +++ b/doc/user/ref_sett @@ -0,0 +1,95 @@ +@Section + @Title { Setting up a bibliographic database } + @Tag { databases } +@Begin +@PP +The basic idea is to store your references in a separate +database.file @Index { database file } +@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 }" +"}" +} +reference. @Index @Code "@Reference" +@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 +giving its tag, there must be one. The @Code "@Type" option is also +type. @Index { @Code "@Type" option } +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 +by Lout, and Section {@NumberOf refstyles} explains how to add your own. +@PP +Lout database file names must end in {@Code ".ld"}, so now suppose that +you have made one called +ld.file @Index { @Code ".ld" file } +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" +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 +you might be referring to @Code "@Reference" symbols in database +@Code "refs" (that is, in file {@Code "refs.ld"}). +@PP +If you want to maintain a central database, used by many documents, you +won't want it in the same directory as any one of them. A Unix +pathname will be more appropriate: +@ID @Code "@Database @Reference { \"/usr/jeff/lib/refs\" }" +or whatever. Quotes are needed because of the @Code "/" characters. +@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 +database.index.file @Index { database index file } +index.file @Index { index file } +database is used, Lout will create an @I { index file } whose purpose +is to speed up the retrieval of your references. Thanks to this file +you can have hundreds or even thousands of references in your database, +without slowing Lout down very much. However, whenever you change your +database file @I { you must remove its corresponding index file }, so +that Lout knows to create it afresh. +@FootNote { +Depending on how it was installed on your system, Lout may be able to +use the time of last modification of the database file and its index +file to determine automatically whether the index file needs to be +created afresh, thus saving you the trouble of removing it. You can +find out whether this is true of your system by typing the command +{@Code "lout -V"}. +} + The index file is stored in the +same directory as the database file, and it has the same name except +that it ends in @Code ".li" rather than @Code ".ld" (e.g. +li.file @Index { @Code ".li" file } +{@Code "refs.li"}). +@PP +If a separate database file is not convenient for some reason, perhaps +because you need a self-contained document in a single file, the +@Code "@Reference" symbols may be incorporated into the document +itself, anywhere that ordinary text may appear. Nothing will appear +where they are typed in, but Lout will notice them and treat them as if +they had come from a database file. In this case no @Code "@Database" +symbol is needed unless you are referring to a database as well. +@PP +You may have multiple databases, like this: +@ID @OneRow @Code { +"@Database @Reference { myrefs }" +"@Database @Reference { \"/usr/pub/refs/theoryrefs\" }" +} +Lout will search the databases in the order you list them. +@End @Section diff --git a/doc/user/str b/doc/user/str new file mode 100644 index 0000000..0312dfb --- /dev/null +++ b/doc/user/str @@ -0,0 +1,19 @@ +@Chapter + @Title { Adding Structure to Documents } + @Tag { structure } +@Begin +@BeginSections +@Include { str_disp } +@Include { str_list } +@Include { str_foot } +@Include { str_marg } +@Include { str_theo } +@Include { str_figs } +@Include { str_larg } +@Include { str_cros } +@Include { str_cont } +@Include { str_indx } +@Include { str_colu } +@Include { str_defs } +@EndSections +@End @Chapter diff --git a/doc/user/str_colu b/doc/user/str_colu new file mode 100644 index 0000000..b54a404 --- /dev/null +++ b/doc/user/str_colu @@ -0,0 +1,40 @@ +@Section + @Title { Multiple columns } + @Tag { columns } +@Begin +@PP +You can change the number of columns of text per page, and the width of +columns. @Index columns +multiple.columns @Index { multiple columns } +the gap between the columns, by changing these two setup file options: +columnnumber. @Index @Code "@ColumnNumber" +columngap. @Index @Code "@ColumnGap" +@ID @OneRow @Code { +"@ColumnNumber { 1 }" +"@ColumnGap { 1.00c }" +} +If you are using your own setup file (Section {@NumberOf setup}), you can +find and change them there. If not, @Code "@ColumnNumber" may be changed +at the beginning of your document (Section {@NumberOf ordinary}). +@PP +@Code "@ColumnNumber" may be any number between 1 and 10, with default +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 } +using the obvious formula +@ID @Eq { columnwidth = { pagewidth - margins - +({@Code "@ColumnNumber"} - 1) times {@Code "@ColumnGap"} } +over @Code "@ColumnNumber" +} +You must ensure that this comes to something reasonable. +@PP +These two options do not apply to pages containing an index. For them +there are similar setup file options called @Code "@IndexColumnNumber" +and @Code "@IndexColumnGap" (Section {@NumberOf indexes}). +@PP +Most document types permit you to have multiple columns, but certain +things will be kept full width regardless of the @Code "@ColumnNumber" +option: figures and tables, chapter headings, and so on. The details +vary with the document type, so are deferred to Chapter {@NumberOf types}. +@End @Section diff --git a/doc/user/str_cont b/doc/user/str_cont new file mode 100644 index 0000000..148447e --- /dev/null +++ b/doc/user/str_cont @@ -0,0 +1,83 @@ +@Section + @Title { Tables of contents } + @Tag { contents } +@Begin +@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 } +(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 +nothing. +@PP +Some details of the appearance of the table of contents, including +whether to make one or not, are controlled by options in the setup +file. The default setting is to make one in books but not to in +other types of documents, but by changing the setup file you can have +a table of contents in any type of document. +@PP +Section @NumberOf setup describes setup files in general and how to +change the options within them. The options relevant to tables of +contents and their default values are: +@ID @OneRow @Code { +"@MakeContents { No }" +"@ContentsGap { 0.20v }" +"@ContentsGapAbove { 0.80v }" +"@ContentsGapBelow { 0.00v }" +"@ContentsLeader { .. }" +"@ContentsLeaderGap { 4s }" +"@ContentsRightWidth { 3f }" +} +The @Code "@MakeContents" option may be @Code Yes or {@Code No}, and +makecontents. @Index @Code "@MakeContents" +determines whether a table of contents is made or not. Its default +value is @Code No but it is set to @Code Yes in the @Code book setup +file. +@PP +@Code "@ContentsGap" determines how much vertical space to leave +contentsgap. @Index @Code "@ContentsGap" +above each line of the table of contents, in addition to the usual +single line spacing; its value may be any length (Section +{@NumberOf objects}). The default value, {@Code "0.20v"}, is twenty +percent of the current inter-line spacing. +@PP +Some entries, such as those for chapters and appendices in books, are +more important than others. @Code "@ContentsGap" does not apply to these +entries; instead, @Code "@ContentsGapAbove" and @Code "@ContentsGapBelow" +contentsgapabove. @Index @Code "@ContentsGapAbove" +contentsgapbelow. @Index @Code "@ContentsGapBelow" +are used above and below each of them, again in addition to the usual +single line spacing. +@PP +@Code "@ContentsLeader" is the object which is repeated across the page +contentsleader. @Index @Code "@ContentsLeader" +to connect each entry with its page number; popular values are @Code ".." +and @Code "." and the empty object. @Code "@ContentsLeaderGap" determines +contentsleadergap. @Index @Code "@ContentsLeaderGap" +how far apart these objects are; the default value, {@Code "4s"}, is +four times the width of a space character. @Code "@ContentsLeaderGap" +may be {@Code "0s"}, but only if @Code "@ContentsLeader" is non-empty. +@PP +@Code "@ContentsRightWidth" reserves some +contentsrightwidth. @Index @Code "@ContentsRightWidth" +space at the far right for page numbers. Any entry wide enough to +intrude into this space is broken into two or more lines to keep it +clear. +@PP +In addition to these options, each document type has options that +determine which large-scale structure symbols will be listed in the +table of contents. For example, among the options to the +@Code "@BookSetup" symbol in the @Code book setup file are these: +@ID @OneRow @Code { +"@ChapterInContents { Yes }" +"@SectionInContents { Yes }" +"@SubSectionInContents { Yes }" +"@SubSubSectionInContents { No }" +"@AppendixInContents { Yes }" +"@SubAppendixInContents { Yes }" +"@SubSubAppendixInContents { No }" +} +Each may be either {@Code "Yes"} or {@Code "No"}; these default values +produce entries for everything except sub-subsections and sub-subappendices. +@End @Section diff --git a/doc/user/str_cros b/doc/user/str_cros new file mode 100644 index 0000000..7eb74c3 --- /dev/null +++ b/doc/user/str_cros @@ -0,0 +1,112 @@ +@Section + @Title { Cross references } + @Tag { cross } +@Begin +@PP +Cross references are a useful feature of documents, but they are a +cross.ref @Index { cross references } +problem for authors. Suppose that at one point of your document +you have +@ID @OneRow @Code { +"We hold these truths to be self-evident, that all men are created equal," +"that they are endowed by their Creator with certain inalienable Rights," +"that among these are Life, Liberty, and the pursuit of Happiness..." +} +and that at some other point, earlier or later, you have +@ID @OneRow @Code { +"The anti-slavery cause, founded as it was on the Declaration" +"of Independence (page 181), could appeal to patriotic as" +"well as moral sentiments..." +} +This is a @I { cross reference }, and the problem is that as the document +is revised, the Declaration of Independence might move to page 185, and +the cross reference must be found and changed. +@PP +Lout has a simple solution to this problem. Instead of writing the +pageof. @Index @Code "@PageOf" +page number, write +@ID @OneRow @Code { +"The anti-slavery cause, founded as it was on the Declaration" +"of Independence (page @PageOf { decl.of.ind }), could appeal to" +"patriotic as well as moral sentiments..." +} +instead, and at the point referred to, write +pagemark. @Index @Code "@PageMark" +@ID @OneRow @Code { +"We @PageMark decl.of.ind hold these truths to be self-evident, that..." +} +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 +characters in the tag. +@PP +One tag called @Code "last.page" is created automatically +"last.page.tag" @Index { @Code "last.page" tag } +for you. @Code "@PageOf last.page" gives the number of the last page +of the document. For example, the result for this document is +{@PageOf last.page}. +@PP +Cross referencing also applies to large-scale structure symbols such as +@Code "@Chapter" and @Code "@Section" (any symbol with a @Code "@Title" +option), as well as @Code { "@FootNote" }, @Code { "@EndNote" }, +@Code { "@Figure" }, @Code { "@Table" }, the numbered display +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" +@ID @OneRow @Code { +"@Section" +" @Title { Cross references }" +" @Tag { cross }" +"@Begin" +"@PP" +"Cross references are a useful ..." +} +Now you can use the @Code "@PageOf" symbol to find the +number of the page on which the symbol's result begins, and the +@Code "@NumberOf" symbol to find its number: +numberof. @Index @Code "@NumberOf" +@ID @OneRow @Code { +"For further information on this point, please consult" +"Section @NumberOf cross (page @PageOf { cross })." +} +produces +@QD { +For further information on this point, please consult +Section @NumberOf cross (page @PageOf { cross }). +} +Like all tags, the value of the @Code "@Tag" option should be a simple +word (although Lout does accept multi-word tags). Cross referencing of +list items yields just the number of the item, in Arabic, Roman, or +whatever; it does not include the surrounding parentheses or other +decorations introducted by the list's @Code "style" option. +@PP +To work cross references out, Lout has to process your document more +multiple.runs @Index { multiple runs, why needed } +than once, storing information between runs in special files it +creates whose names end in @Code ".li" and {@Code ".ld"}. A complex +document like this Guide requires five runs, but since every run +produces a perfectly good PostScript file suitable for proof reading, +in fact you need two runs to start with and one run per cycle of +revision thereafter, only one more than would have been necessary +in any case. +@PP +The cross referencing system assumes that each Unix directory contains +directories @Index { directories, Lout files and } +only one Lout document (possibly spread over many files). If you keep +several documents in one directory you can turn off the cross referencing +with the @Code "-s" flag: +@ID @Code "lout -s simple > simple.ps" +Since this will cause question marks to replace footnote and section +numbers, and other products of cross referencing, it is only feasible +for simple documents. Alternatively, you can reset cross referencing +when switching from one document to another, by removing file +lout.li @Index { @Code lout.li file } +{@Code "lout.li"}. You should also remove this file if your document +changes radically -- from a report to a book, say. +@End @Section diff --git a/doc/user/str_defs b/doc/user/str_defs new file mode 100644 index 0000000..71bd71e --- /dev/null +++ b/doc/user/str_defs @@ -0,0 +1,134 @@ +@Section + @Title { Defining new symbols } + @Tag { definitions } +@Begin +@PP +Whenever you find yourself typing the same thing repeatedly, you can +definitions. @Index definitions +save a lot of time by defining your own personal symbol to stand for that +thing. For example, suppose you type your company's name, @Batlow, +frequently. You can define your own symbol, {@Code "@Batlow"} say, +so that +@ID @Code { +"Concerning your crate supply contract with @Batlow, @Batlow wishes to ..." +} +produces +@ID { +Concerning your crate supply contract with @Batlow, @Batlow wishes to ... +} +You will never have to type @Batlow again. +@PP +The method is to create a file called @Code "mydefs" in your current +mydefs.file @Index { @Code mydefs file } +directory, containing definitions like this: +@ID @OneRow @Code { +"import @BasicSetup" +"def @Batlow { Batlow Food Distributors Pty. Ltd. }" +} +The meaning of the first line, {@Code "import @BasicSetup"}, will +be explained shortly. After that comes @Code "def" for `define,' +then the name of the symbol being defined, then its value between +braces. So this example defines a symbol called @Code "@Batlow" to +stand for the object following it between braces. Lout will read this +file during its setup phase (Section {@NumberOf setup}). +@PP +Your symbols may have any names you wish made from letters and +{@Code "@"}. However, it is good practice to have exactly one +{@Code "@"}, at the start, and to choose distinctive names that +have no chance of being the same as the name of any existing +symbol. @Code "@Batlow" is a good choice, for example. +@PP +The object between braces is quite arbitrary; in particular, it may +contain symbols. For example, suppose you frequently need a small grey box: +@ID @OneRow @Code { +"import @BasicSetup" +"def @GreyBox { @Box paint { lightgrey } {} }" +} +This defines a @Code "@GreyBox" symbol that produces {@GreyBox}. Most +of the symbols in this guide are from the @I {BasicSetup package}, +import. @Index @Code import +which is why @Code "import @BasicSetup" is required: it makes +these symbols available to the definition, and can actually be omitted +before definitions like the one for @Code "@Batlow" which do not use +any symbols. However it does no harm, so we place it in front of every +definition as a matter of course. +@FootNote { +Later chapters of this guide introduce specialized symbols for producing +tables, equations, diagrams, graphs, and computer programs. You need a +different @Code "import" clause when using those symbols within a +definition, because they are not from the BasicSetup package. Examples +may be found in the chapters concerned. +} +@PP +Now suppose you frequently need a grey box, but enclosing different +things: @GreyBox ENTRY one moment, @GreyBox EXIT the next. You could +try omitting the @Code "{}" from the definition above, but that does +not work, because Lout notices the missing object while reading the +definition, and inserts an empty object in the usual way (Section +{@NumberOf empty}). +@PP +However, there is a way to define a @Code "@GreyBox" symbol so that +@Code "@GreyBox ENTRY" produces {@GreyBox ENTRY}, @Code "@GreyBox EXIT" +produces {@GreyBox EXIT}, and so on: +@ID @OneRow @Code { +"import @BasicSetup" +"def @GreyBox right x { @Box paint { lightgrey } x }" +} +The addition of @Code "right x" immediately after the symbol's name +places @Code "@GreyBox" into that class of symbols, like {@Code "@I"} +and @Code {"@Box"}, which consume and transform the object to their +right. The @Code "x" in @Code "right x" means that the object to the +right will be referred to as @Code "x" within the definition. So in +@ID @Code "@GreyBox { Hello world }" +@Code "@GreyBox" consumes the following object, which becomes +{@Code "x"}, so that the value is +@ID @Code "@Box paint { lightgrey } { Hello world }" +which produces @GreyBox { Hello world }. +@PP +It is a good principle to choose symbol names that refer to what the symbol +is for, rather than how it does what it does. Here is a good example: +@ID @OneRow @Code { +"import @BasicSetup" +"def @Poetry right x { lines @Break @I x }" +} +This kind of name is very pleasant to use, since it allows you to +forget about what is going on behind the scenes: +@ID @OneRow @Code { +"@IndentedDisplay @Poetry {" +"Teach me to hear Mermaides singing," +"Or to keep off envies stinging," +" And finde" +" What winde" +"Serves to'advance an honest minde." +"}" +} +Most of Lout's symbols follow this principle. +@PP +You can define symbols that consume the object to their left as well +as the object to their right, as the {@Code "@Font"}, {@Code "@Break"}, +and {@Code "@Colour"} symbols do: +@ID @OneRow @Code { +"import @BasicSetup" +"def @HeadingBox left x right y" +"{ @Box { @CentredDisplay @Heading x y }" +"}" +} +This definition occupies several lines only because it is long; as +usual, end of line is the same as one space. Now +@ID @OneRow @Code { +"Cheating @HeadingBox {" +"The Department uses assignments ... of that student alone." +"}" +} +is much easier to type than the equivalent example in Section +{@NumberOf boxes}. The result is the same: +@QD Cheating @HeadingBox { +The Department uses assignments both as a teaching device and as a +major component of its assessment of each student. It therefore +requires that all programs, exercises etc. handed in bearing an +individual student's name be the work of that student alone. +} +Do not use a paragraph, display, or list symbol at the beginning or end +of a definition, since the result is not what people who do it are +hoping for. +@End @Section diff --git a/doc/user/str_disp b/doc/user/str_disp new file mode 100644 index 0000000..4634103 --- /dev/null +++ b/doc/user/str_disp @@ -0,0 +1,94 @@ +@Section + @Title { Displays } + @Tag { displays } +@Begin +@PP +The @Code "@Display" symbol displays the following object in the centre +displays. @Index displays +display. @Index @Code "@Display" +of the page or column: +@ID @Code "@Display @I { Invitation to Afternoon Tea }" +has result +@Display @I { Invitation to Afternoon Tea } +Space is inserted automatically above and below the display; no +paragraph symbols are needed. +@PP +To make the display appear at the left margin instead of centred, use +leftdisplay. @Index @Code "@LeftDisplay" +{@Code "@LeftDisplay"} instead of {@Code "@Display"}. To make an indented +display, use {@Code "@IndentedDisplay"} or {@Code "@QuotedDisplay"}; +indenteddisplay. @Index @Code "@IndentedDisplay" +quoteddisplay. @Index @Code "@QuotedDisplay" +the latter indents at the right margin as well as at the left. There are +also @Code "@CentredDisplay" and @Code "@CenteredDisplay" symbols which +centreddisplay. @Index @Code "@CentredDisplay" +centereddisplay. @Index @Code "@CenteredDisplay" +centre the display just like {@Code "@Display"} does, and +rightdisplay. @Index @Code "@RightDisplay" +@Code "@RightDisplay" which right-justifies the display. +@PP +If you use displays frequently you might prefer abbreviated forms of +their names. These are made from @Code "@" and the capital letters of +d. @Index @Code "@D" +ld. @Index @Code "@LD" +id. @Index @Code "@ID" +qd. @Index @Code "@QD" +cd. @Index @Code "@CD" +the full name: {@Code "@D"}, {@Code "@LD"}, {@Code "@ID"}, {@Code "@QD"}, +and {@Code "@CD"}. Owing to a clash with the name of another symbol, +{@Code "@RightDisplay"} has no abbreviation. +@PP +Displays often need to be set using a different font, paragraph +breaking style, and so on to the surrounding text. It's best to set +out such displays like this: +@ID @OneRow @Code { +"@CentredDisplay @I clines @Break {" +"Invitation to Afternoon Tea" +"with" +"Mr. and Mrs. Gilbert Newington-Smith" +"}" +} +You can have as many of these symbols as you like, including specialized +ones like {@Code "@CurveBox"} and {@Code "@Tbl"}. The only rule is that +the display symbol must come first: @Code "@I @Display ..." is wrong. +@PP +It's not a good idea to have one display immediately followed by +another one, because there will be too much vertical space between +them. Use a list instead (Section {@NumberOf lists}). Displays +at the ends of paragraphs look awkward and are best avoided. +@PP +A display may come out partly on one page or column and partly on +the next, if it has places where it obviously can be broken in two. For +example, a display which is an ordinary paragraph of text might be +broken in two between any two lines. To force a display to keep +together on one page or column, use the @Code "@OneRow" symbol like +this: @Code "@Display @OneRow { ... }". +@PP +Other display symbols produce aligned and numbered displays, and raw +displays (i.e. without vertical space). Although these can display any +object as usual, in practice they are used for mathematics, so they are +described in Section {@NumberOf mathdisplays}. +@PP +Three setup file options control the appearance of displays. (For a +general introduction to setup files and their options, consult +Section {@NumberOf setup}.) Here they are with their default values: +@ID @OneRow @Code { +"@DisplayGap { 1.00v }" +"@DefaultIndent { 0.5rt }" +"@DisplayIndent { 2.00f }" +} +@Code "@DisplayGap" is the amount of vertical space inserted before and +display.gap. @Index @Code "@DisplayGap" +after displays, and may be any length (Section {@NumberOf objects}). The +default value, @Code {"1.00v"}, is equal to the current inter-line spacing. +@PP +@Code "@DefaultIndent" is the indent produced by +default.indent @Index @Code "@DefaultIndent" +{@Code "@Display"}; {@Code "0.5rt"} produces centring, although why it does +so is beyond our scope +@Cite { $kingston1995lout.expert }. @Code "@DisplayIndent" is the +display.indent. @Index @Code "@DisplayIndent" +indent for {@Code "@IndentedDisplay"}, and used at both margins by +{@Code "@QuotedDisplay"}. Its default value, {@Code "2.00f"}, is twice +the current font size. +@End @Section diff --git a/doc/user/str_figs b/doc/user/str_figs new file mode 100644 index 0000000..285e097 --- /dev/null +++ b/doc/user/str_figs @@ -0,0 +1,270 @@ +@Section + @Title { Figures and tables } + @Tag { figures } +@Begin +@PP +Figures are created in a similar way to footnotes: +figures. @Index { figures } +@ID @OneRow @Code { +"@Figure" +" @Caption { Basser Lout }" +"@Diag vstrut { yes } treehsep { 1c } {" +" @HTree { @Box Lout @FirstSub arrow { yes } @Box PostScript }" +"}" +} +The @Code "@Figure" symbol places the following object (which in this example is +figure. @Index @Code "@Figure" +created using the advanced graphics features of Chapter {@NumberOf diagrams}) +at the top of the following column or page, +@Figure + @Tag { figex } + @Caption { Basser Lout } +@Diag vstrut { yes } treehsep { 1c } { + @HTree { @Box Lout @FirstSub arrow { yes } @Box PostScript } +} +labelled by the @Code "@Caption" option and automatically numbered. You +captions. @RawIndex { captions } +captions.figures @SubIndex { in @Code "@Figure" and @Code "@Table" } +can see this example at the top of page {@PageOf figex}. Tables are +table. @Index @Code "@Table" +obtained in the same way using {@Code "@Table"} instead of {@Code "@Figure"}. +@PP +@Code "@Figure" and @Code "@Table" each have an @Code "@InitialLanguage" +option which determines the language of the figure or table. If this is +omitted, the language of the document as a whole will be used, not the +language where the figure or table occurs. +@PP +The two symbols also have a @Code "@CaptionPos" option, which determines +whether the caption appears above or below the figure or table. The +default is {@Code "Below"}, the alternative is {@Code "Above"}. +@PP +The question of what is a suitable running header to print on pages +containing figures and tables (possibly from different sections) is a +rather awkward one. On any page with a figure or table at the top, Lout +uses whatever running header was appropriate for the text on the previous +page. In practice it seems to work quite well. +@PP +If your document contains many figures, large figures, or multi-page +figures, you are likely to encounter cases where Lout's assignment of +figures to pages is not pleasing. In that case, you can improve things +by moving the figures around within the body text, and by using the +@Code "@Location" option of the @Code "@Figure" symbol, which determines +location. @Index @Code "@Location" +where the figure will appear. Its possible values are +@DP @Tab + @Fmta { @Col @Code A ! @Col B } +{ +@FirstRowa + A { PageTop } + B { The figure will appear at the top of the following page, occupying +the full page width; or, if there is insufficient space there (owing to other +figures already present), at the top of the first subsequent page with +sufficient space. } +@Rowa + 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. } +@Rowa + A { FullPage } + B { Like {@Code PageTop} except that nothing else will appear on the +same page as the figure except the usual running headers and footers, and +possibly other @Code FullPage figures and tables. +@FootNote { This location replaces the @Code "@FullPage" option of +earlier versions of Lout, which has been withdrawn. } +} +@Rowa + A { EvenFullPage } + B { Like {@Code FullPage} except that the first page of the figure +or table will be an even-numbered (left-hand or verso) page, like +{@Code EvenPageTop}. +} +@Rowa + A { PageFoot } + B { The figure will appear at the foot of the current page, occupying +the full page width; or, if there is insufficient space there, at the top +of the following page and so on as for {@Code PageTop}. } +@Rowa + A { ColTop } + B { The figure will appear at the top of the following column, +occupying the column width; or, if there is insufficient space there, +at the top of the first subsequent column with sufficient space. This +is different from @Code PageTop only in multi-column documents. } +@Rowa + A { ColFoot } + B { The figure will appear at the foot of the current column, +occupying the column width; or, if there is insufficient space there, at +the top of the following column as for {@Code ColTop}. This differs +from @Code PageFoot only in multi-column documents. } +@Rowa + A { ColEnd } + B { The figure will appear in a column at the end of the document +(or chapter, appendix etc. in the case of books). There is no +@Code PageEnd value corresponding to {@Code ColEnd}. } +@Rowa + A { AfterLine } + B { The figure will appear as a column-width display immediately after +the line in the final printed document in which it occurs. } +@Rowa + A { TryAfterLine } + B { The same as @Code {AfterLine} unless there is insufficient space +in the current column to hold the displayed figure, in which case it +switches to @Code {ColTop} instead. } +@Rowa + A { Display } + B { The figure will appear as a display at the point it occurs. There +is no @Code TryDisplay value corresponding to {@Code Display}. } +@Rowa + A { Raw } + B { The figure will appear as an object, with no extra spacing, at +the point it occurs. This is useful, for example, for getting two figures +side by side in one display: use a displayed table containing two raw +figures. } +} +@DP +The @Code "@Table" symbol also has this option. The default location is +{@Code "PageTop"}, but this can be changed by changing the +figurelocation. @Index @Code "@FigureLocation" +tablelocation. @Index @Code "@TableLocation" +@Code "@FigureLocation" and @Code "@TableLocation" setup file options. +@PP +The numbers assigned to figures and tables, and their ordering in any list +of figures or tables, is based on where they appear in the final printed +document, not on where they appear in the source files. This is better for +the reader in the unusual case of a fixed figure being overtaken by a +floating one. If a section number is printed as part of a figure number, +and the figure floats forward from one section into another, the figure +number will reflect the later section, not the earlier one as it should. +You can fix this problem by moving the figure to an earlier point in +the section, or by not having section numbers in figures (see below). +@PP +@Code "@Figure" and @Code "@Table" each have a @Code "@OnePage" option, +whose value may be @Code "Yes" or {@Code No}. Setting @Code "@OnePage" +to @Code Yes causes the figure or table and its caption to be kept +together on one page or column (enclosing the body of the figure or table +in @Code "@OneRow" would have the same effect except that it would not +incorporate the caption, hence the need for this option). You need to be +certain that the whole assembly will fit on one page when setting +@Code "@OnePage" to {@Code "Yes"}. +@PP +The @I default value of the @Code "@OnePage" option for each figure or +table depends on the value of its @Code "@Location" option as follows: +@ID @Tab + @Fmta { @Col @Code A ! @Col ! @Col @Code B } +{ +@Rowa + A { No } + B { PageTop ColTop ColEnd Raw } +@Rowa + A { Yes } + B { PageFoot ColFoot Display AfterLine TryAfterLine } +} +These choices represent a guess that figures that the user is happy to +see at the page foot or in a display are probably going to be small enough +to keep on one page, but that other figures may not be. In any case, these +are only default values and you may set @Code "@OnePage" as you wish. +@PP +By default, the body of the figure will be centred, and this usually looks +best, at least for small figures. @Code "@Figure" and @Code "@Table" each +have a @Code "@Format" option which controls this format: +@ID @Code { +"@Figure" +" @Format { @CurveBox @HExpand @CC @Body }" +} +Within the @Code "@Format" option, the @Code "@Body" symbol stands for the +body of the figure or table; it must appear exactly once. Display symbols +such as @Code "@CentredDisplay" may not be applied to the {@Code "@Body"} +symbol; instead, there are {@Code "@II"}, {@Code "@QQ"}, {@Code "@CC"}, and +{@Code "@RR"}, which indent, quote, centre, or right-justify the following +object. The example just given centres the figure inside a @Code "@CurveBox" +which is horizontally expanded (by the @Code "@HExpand" symbol, which is not +specific to figures) to occupy the full width of the page or column, rather +than fitting snugly around the figure. +@PP +The @Code "@Format" option applies to just the body of the figure, not to +its caption. It applies to each page or column of a multi-page or +multi-column figure; for example, the above format will draw a box around +each page of a multi-page figure, and each page will be separately centred. +@Code "ColEnd" and @Code "Raw" figures are exceptions to this rule: they +always apply the format to the figure as a whole. This means that you cannot +box multi-page figures of these two types, since the result would be an +unbreakable object too large to fit on one page. +@PP +There are setup file options for controlling the appearance of figures and +tables. Only those for figures will be given here, since the ones for tables +are identical except that @Code Table replaces @Code Figure in their +names. Here they all are: +@FootNote { These are as of Version 3.15 and above. Prior to that +there were {@Code "@CaptionFont"}, {@Code "@CaptionBreak"}, and +{@Code "@CaptionFormat"} options, and {@Code "@CaptionFormat"} +took values that did not include the @Code "caption" symbol. } +@ID @OneCol @Code { +"@FigureLocation { PageTop }" +"@FigureFormat { @CC @Body }" +"@FigureWord { figure }" +"@FigureNumbers { Arabic }" +"@FigureCaptionPos { Below }" +"@FigureCaptionFont { }" +"@FigureCaptionBreak { }" +"@FigureCaptionFormat { @B { word @NumSep number. &2s } @Insert caption }" +"@MakeFigureContents { No }" +"@FigureListWord { figurelist }" +} +@Code "@FigureLocation" is the default value of the @Code "@Location" +option of figures. Changing it, for example to +{@Code "FullPage"}, changes the location of all figures at +once. You may still override this location for any individual figure, +however, by giving that figure a @Code "@Location" option. In a similar way, +figureformat. @Index @Code "@FigureFormat" +tableformat. @Index @Code "@TableFormat" +@Code "@FigureFormat" is the default value of the @Code "@Format" +option (this shows why figures are centred by default) and +figurecaptionpos. @Index @Code "@FigureCaptionPos" +tablecaptionpos. @Index @Code "@TableCaptionPos" +@Code "@FigureCaptionPos" is the default value of {@Code "@CaptionPos"}. +@PP +@Code "@FigureWord" determines the word that is part of the figure +number. The default value, {@Code figure}, produces `Figure' or its +equivalent in the current language; any other value produces itself. +@PP +@Code "@FigureNumbers" +figurenumbers. @Index @Code "@FigureNumbers" +tablenumbers. @Index @Code "@TableNumbers" +determines whether figures are +numbered automatically or not; the choices are +{@Code "None"}, {@Code "Arabic"}, {@Code "Roman"}, {@Code "UCRoman"}, +{@Code "Alpha"}, and {@Code "UCAlpha"}. Depending on the document +type and where the figure or table occurs, the number might include +a chapter number as well. This is determined by options in the +setup file for your document type; for example, +@ID @Code "@SectionNumInFigures { No }" +appears in the @Code "report" setup file, and means that a section +number will not appear in the figure number (unless you change the +option to {@Code Yes}). +@PP +@Code "@FigureCaptionFont" and @Code "@FigureCaptionBreak" determine the +font and paragraph breaking style used in the captions of figures. Their +default values are empty, meaning to use the initial font and break styles; +but, for example, you could have +@ID @Code "@FigureCaptionFont { -2p }" +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 +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 +gap of two spaces into the first paragraph of the caption. If you +don't use the @Code "@Insert" symbol you'll run into problems with +multi-paragraph captions. +@PP +You can get a list of figures at the start of your document by setting +the @Code "@MakeFigureContents" setup file option to {@Code Yes}. The +format of these lists will follow the format of tables of contents. These +lists are only available in books (Section {@NumberOf books}). The +title printed above the list of figures is determined by the +@Code "@FigureListWord" option; the default value, {@Code "figurelist"}, +produces `List of Figures' or its equivalent in the current language; any +other value produces itself. +@End @Section diff --git a/doc/user/str_foot b/doc/user/str_foot new file mode 100644 index 0000000..70e50a2 --- /dev/null +++ b/doc/user/str_foot @@ -0,0 +1,150 @@ +@Section + @Title { Footnotes and endnotes } + @Tag { footnotes } +@Begin +@PP +A footnote is created by typing +footnote. @Index @Code "@FootNote" +@ID @Code "@FootNote { Like this. }" +after the word that the footnote refers to. It will be numbered +automatically and placed at the foot of the page or column; +@FootNote { Like this. } +or, if space there is insufficient, it may start on or run onto the +following page or column. The footnote must be enclosed in braces. +@PP +The @Code "@FootNote" symbol has a @Code "@Location" option which +determines where it goes: +@ID @Code { +"@FootNote" +" @Location { ColFoot }" +"{ ... }" +} +places the footnote at the bottom of the column, and +@ID @Code { +"@FootNote" +" @Location { PageFoot }" +"{ ... }" +} +places it at the bottom of the current page, occupying the full page +width even in a multi-column document (this is occasionally +useful for footnotes to headings). Of course, in a single-column +document there is no difference anyway. The default value of the +@Code "@Location" option is {@Code "ColFoot"}. +@PP +Endnotes work in exactly the same way as footnotes, except that the +endnote. @Index @Code "@EndNote" +symbol to use is @Code "@EndNote" and they appear either at the end +of the document or at the end of some major part of it, depending on +the type of document (Chapter {@NumberOf types}). Endnotes are +always column width and so have no @Code "@Location" option. +@PP +Footnotes are usually labelled with consecutive Arabic numberals, but +you can tell Lout to label a footnote (not an endnote) with something +else, like this: +@ID @OneRow @Code @Verbatim { +@FootNote + @Label { @Dagger } +{ This footnote will be labelled with a dagger, not a number. } +} +whose result should appear at the bottom of this page. +@FootNote + @Label { @Dagger } +{ This footnote will be labelled with a dagger, not a number. } +Symbols commonly used for footnote labels include @Code "@Dagger" (@Dagger), +@Code "@DaggerDbl" (@DaggerDbl), @Code "@Star" (@Star), +@Code "@SectSym" (@SectSym), and @Code "@ParSym" (@ParSym), +but you can use any object. If you want no label at all, +use an empty object like this: +@ID @OneRow @Code @Verbatim { +@FootNote + @Label {} +} +Footnotes with a @Code "@Label" option are excluded from the automatic +numbering that applies to other footnotes. +@PP +The language of a footnote or endnote will be the language of the +document as a whole. This is not necessarily the same as the +current language at the point where the footnote or endnote occurs, +or even the language of the enclosing large-scale structure symbol. It +may be necessary to enclose the body of the footnote in a language +symbol, like this: +@ID @Code "@FootNote { French @Language { ... } }" +Doing it the other way ({@Code "French @Language @FootNote ..."}) is +not effective. +@PP +A footnote attached to the very last line of a chapter or appendix of +a book occasionally runs onto the first page of the following chapter +or appendix, and this looks very poor. If this happens, the solution +is to place an @Code "@LP" after the last line (including the footnote). +@PP +In the rare case where more than one footnote is attached to one word, +use @Code "@AnotherFootNote" for the second and subsequent footnotes: +anotherfootnote. @Index @Code "@AnotherFootNote" +@ID @Code { +"something or other." +"@FootNote { The first footnote. }" +"@AnotherFootNote { The second footnote. }" +} +This ensures that the superscripts will be separated by +commas, as convention demands. +@PP +The setup file contains a number of options for controlling the +appearance of footnotes. (See Section @NumberOf setup for a general +introduction to setup files and their options.) Here are all the +options, with their default values: +@ID @OneRow @Code { +"@FootNoteThrough { No }" +"@FootNoteLocation { ColFoot }" +"@FootNoteNumbers { Arabic }" +"@FootNoteFont { 0.80f }" +"@FootNoteBreak { 1.20fx }" +"@FootNoteFormat { { number &0.05f } @Insert body }" +"@FootLen { 2.00c }" +"@FootAboveGap { 1.00v }" +"@FootGap { 0.20c }" +} +There are also setup file options for controlling endnotes. Since +they are quite similar to the ones for footnotes, we won't say any +more about them here. +@PP +@Code "@FootNoteThrough" may be @Code "Yes" or @Code { "No" }; +footnotethrough. @Index @Code "@FootNoteThrough" +@Code "Yes" means that the footnotes are numbered continuously +through the document (or through each chapter in the case of books); +@Code "No" means that the numbering begins afresh on each +page. @Code "@FootNoteLocation" determines the default value of +footnotelocatin. @Index @Code "@FootNoteLocation" +the @Code "@Location" option mentioned above; it may be either +@Code "ColFoot" or {@Code "PageFoot"}. @Code "@FootNoteNumbers" +determines how the footnotes are numbered; +footnotenumbers. @Index @Code "@FootNoteNumbers" +it may be {@Code Arabic}, {@Code Roman}, {@Code UCRoman}, {@Code Alpha}, +or {@Code UCAlpha}. +@PP +@Code "@FootNoteFont" and @Code "@FootNoteBreak" determine the +footnotefont. @Index @Code "@FootNoteFont" +footnotebreak. @Index @Code "@FootNoteBreak" +font and paragraph breaking style of footnotes. The default value +of @Code "@FootNoteFont" produces the same font family and face as the +bulk of the document, but reduced to 0.8 times the original size. +@PP +@Code "@FootNoteFormat" determines the format of the footnote. The +@Code number symbol within it must appear exactly once, and is replaced +by the number of the footnote (if numbered). The @Code body symbol is +replaced by the body (that is, the content) of the footnote. The default +value shown uses symbols from raw Lout to add a small space at the right of +the number, then insert it at the beginning of the first paragraph of +the body. Another suitable value might be +@ID @Code "@FootNoteFormat { number |1fx body }" +which places the body in a separate column to the number, one +font width to the right of the left edge of the number. +@PP +@Code "@FootLen" determines the length of the small horizontal line +footlen. @Index @Code "@FootLen" +drawn above the footnotes; +@Code "@FootAboveGap" determines the minimum space to be left clear +footabovegap. @Index @Code "@FootAboveGap" +above this line; and @Code "@FootGap" determines the +footgap. @Index @Code "@FootGap" +vertical separation between footnotes. All three may be any length. +@End @Section diff --git a/doc/user/str_indx b/doc/user/str_indx new file mode 100644 index 0000000..c9ea2de --- /dev/null +++ b/doc/user/str_indx @@ -0,0 +1,314 @@ +@Section + @Title { Indexes } + @Tag { indexes } +@Begin +@PP +Although Lout is not clever enough to guess what entries should go in +indexes. @Index { indexes } +your index, it will do almost everything else for you: sort the +entries and attach the correct page numbers automatically. As for +tables of contents, the default setting is to have an index in +books but not in other types of documents. This and a few aspects of +the appearance of the index can be changed by changing the setup file, +as explained at the end of this section. +@PP +Now, suppose you are discussing Galileo and you want his name in your +index. Let's be ambitious and say that you want the index to contain +something like this: +@ID @OneRow lines @Break { +Galileo Galilei + life of, 201 + telescope, his use of, 201--203 + trial of, 205--211, 242, 395 +} +Each line shows off one of Lout's four tricks: the first is a +@I { raw entry } (no page number attached); the second is a +@I sub-entry (indented); the third has a @I { page number range } +instead of a single page number; and the fourth is a @I { merged entry } +(several page numbers or ranges within one entry). +@PP +We'll take each of them in turn in a moment, but first, let's see how +to get a basic entry, like this one: +@ID { Galileo Galilei, 201 } +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 +the index, with a comma and the correct page number appended +automatically. +@PP +The object preceding the @Code "@Index" symbol is a compulsory key +which is used for sorting the index entries, +@FootNote { +The collating sequence used to decide what comes after what is the +collating sequence used by the @Code "memcmp()" library routine (just +the underlying binary character codes). Alternatively, the version +of Lout installed on your system may use the @Code "strcoll()" +collating sequence, which understands accented characters and whose +effect depends on your locale. To find out whether @Code "strcoll()" +is in use or not, type @Code "lout -V" which prints out several lines +of this and similar information. +@PP +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 +if @Code "strcoll()" gets the sorting right for one language, there still +remains the problem of sorting multilingual indexes. +@PP +Lout's database mechanism assumes that the @I tab character is collated +before any character that could appear in a sorting key. It seems that +there are a few collating sequences in existence which do not satisfy this +condition, and in these cases Lout will fail to produce the correct index. +} +but which is not itself printed anywhere. It is best to construct these +sorting keys from lower-case letters and the . character only, beginning +with a letter, although multi-word keys are allowed. These sorting keys +do not have to be distinct from the tags used in cross referencing; +however, they do have to be distinct from each other, unless you want +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 +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 +produced by +@ID @Code "galileo.life @SubIndex { life of }" +You should always give sub-entries the same sorting key as their +corresponding main entries, plus a . and another word, because then +you can be certain that the sorting will place sub-entries directly +after their main entries. There is a @Code "@SubSubIndex" symbol that +produces a double indent, and there are @Code "@RawSubIndex" and +@Code "@RawSubSubIndex" symbols. +@PP +For our third trick, page number ranges, we use the @Code "to" option +of the {@Code "@Index"}, {@Code "@SubIndex"}, and {@Code "@SubSubIndex"} +symbols. For example, to produce the sub-entry +@ID { telescope, his use of, 201--203 } +put +@ID @Code { + "galileo.telescope @SubIndex to { gt.end } { telescope, his use of }" +} +at the beginning of the range, and +@ID @Code "@PageMark { gt.end }" +at the end. You can use any tag you like inside the @Code "to" option, +as long as it differs from every other tag (notice that sorting keys +do not have to differ from tags, but @Code "to" options do: this +is because @Code "to" options go into @Code "@PageMark" like other +tags do, and if two tags are the same we would have an ambiguous +result of {@Code "@PageOf"}). If both ends of the range fall on the +same page, the @Code "to" option is ignored: you will never get +201--201. +@PP +Our fourth and final trick is the merged entry: +@ID { trial of, 205--211, 242, 395 } +The main thing to grasp is that this merged entry was originally three +separate entries (sub-entries in this case): +@ID @OneRow lines @Break { +trial of, 205--211 +trial of, 242 +trial of, 395 +} +We already know how to produce these three entries, using three +@Code "@SubIndex" symbols, one with a @Code "to" option. Now we have +discovered that Lout is able to merge several entries into one +entry. This raises two questions: how does Lout know which entries +to merge? and given those entries, what does the merging produce? +@PP +The answer to the first question is that Lout merges entries whose +sorting keys are equal. The merged entry above is produced by these +three entries, placed in the appropriate places: +@ID @OneRow @Code { +"galileo.trial @SubIndex to { gtrial.end } { trial of }" +"galileo.trial @SubIndex { trial of }" +"galileo.trial @SubIndex { trial of }" +} +The entries are merged because they have the same sorting key +({@Code "galileo.trial"}), not because they happen to have the +same content ({@Code "trial of"}). In fact, once the page numbers are +added the content is not the same at all. +@PP +Now, having decided that the three entries +@ID @OneRow lines @Break { +trial of, 205--211 +trial of, 242 +trial of, 395 +} +must be merged, what does Lout do? It takes the second entry, discards +any initial part that is the same as the first entry ({@Code "trial of,"} +in this case), and, if anything remains, it adds a comma, a space, and +the remainder to the first entry, producing +@ID { trial of, 205--211, 242 } +in this case. This process is repeated on this and the third entry, +producing +@ID { trial of, 205--211, 242, 395 } +in this case, and so on. The entries are merged in the order in which +their points of origin appear in the final printed document. +@PP +If nothing remains after discarding the common initial part, nothing is +added to the growing merged entry; in effect, the entry that could +contribute nothing new is deleted. With this in mind, let us return to +our initial, ambitious example: +@ID @OneRow lines @Break { +Galileo Galilei + life of, 201 + telescope, his use of, 201--203 + trial of, 205--211, 242, 395 +} +We now know how to produce all four of these entries, but one problem +of some practical importance remains. Suppose we delete the section on +the life of Galileo. If we had put the entry that produces `Galileo +Galilei' in that section, we might inadvertently delete it, and the +other two sub-entries will lose their main entry. Before deleting +anything, we must hunt through it for index entries and ponder their +significance, an error-prone and time-wasting thing to do. +@PP +The solution is as follows. When an index entry has sub-entries, make +it raw, and repeat it just before each of its sub-entries: +@ID @OneRow @Code { +"galileo @RawIndex { Galileo Galilei }" +"galileo.life @SubIndex { life of }" +} +at the first place, +@ID @OneRow @Code { +"galileo @RawIndex { Galileo Galilei }" +"galileo.telescope @SubIndex { telescope, his use of }" +} +at the second, and so on. Now it is easy to verify that every +sub-entry has a main entry; and when deleting a sub-entry we can and +should delete the adjacent main entry. After sorting, our index +entries will be +@ID @Tab + @Fmta { @Col @Code A ! @Col B } +{ +@Rowa + A { galileo } + B { Galileo Galilei } +@Rowa + A { galileo } + B { Galileo Galilei } +@Rowa + A { galileo } + B { Galileo Galilei } +@Rowa + A { galileo } + B { Galileo Galilei } +@Rowa + A { galileo } + B { Galileo Galilei } +@Rowa + A { galileo.life } + B { {} life of, 201 } +@Rowa + A { galileo.telescope } + B { {} telescope, his use of, 201--203 } +@Rowa + A { galileo.trial } + B { {} trial of, 205--211 } +@Rowa + A { galileo.trial } + B { {} trial of, 242 } +@Rowa + A { galileo.trial } + B { {} trial of, 395 } +} +The first five entries have the same sorting key, and will be merged +as required. +@PP +The language of the index entry will be the initial language of the +document as a whole, which is not necessarily the language at the point +where the index entry occurs. To get the correct language you will need a +@Code "@Language" symbol following the @Code "@Index" symbol: +@ID @Code "galileo. @Index French @Language { Galileo Galilei }" +or whatever. If you don't do this your index entry might be hyphenated +incorrectly. +@PP +Although the page numbers in index entries will be kept up to date +automatically as the document changes, as all cross references are, +it is best to refrain from inserting index entries until the document +is complete and an overall plan of the structure of the index can +be made. +@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 five setup file options for the index. Here they are with +their default values: +@ID @OneRow @Code { +"@MakeIndex { No }" +"@IndexFont { }" +"@IndexBreak { oragged 1.2fx }" +"@IndexColumnNumber { 2 }" +"@IndexColumnGap { 1.00c }" +} +The @Code "@MakeIndex" option, which may be @Code Yes or {@Code No}, +makeindex. @Index @Code "@MakeIndex" +determines whether to produce an index or not. Although the default +value is {@Code No}, any type of document may be given an index just +by changing it to {@Code Yes}. This has already been done in the +@Code book setup file, but not in the others. +@PP +@Code "@IndexFont" determines the font and font size of index entries +indexfont. @Index @Code "@IndexFont" +(e.g. {@Code "Times Base 12p"}). Leaving it empty as above produces +the same font as the rest of the document. @Code "@IndexBreak" is the +indexbreak. @Index @Code "@IndexBreak" +paragraph breaking style applied to index entries; @Code oragged is the +traditional and best way. +@PP +@Code "@IndexColumnNumber" and @Code "@IndexColumnGap" determine the +indexcolumnnumber. @Index @Code "@IndexColumnNumber" +indexcolumngap. @Index @Code "@IndexColumnGap" +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 +Lout offers the possibility of having up to three independent indexes +(useful for glossaries, 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, +@ID @Code "smith.j @IndexA { Smith, John }" +will insert an index entry to index A, and @Code "@IndexBBlanks" +will insert the usual 25 blank entries into index B. +@PP +In large projects it might help to rename the @Code "@IndexA" symbol +to something else, such as {@Code "@AuthorIndex"}. This can +be done by placing +@ID @Code { +"import @DocumentSetup" +"macro @AuthorIndex { @IndexA }" +} +in the @Code mydefs file. See Section {@NumberOf definitions} for +an introduction to the @Code "mydefs" file; the word @Code macro +is needed here instead of @Code "def" because we are introducing +a new name for an existing symbol, not defining a new symbol. +@End @Section diff --git a/doc/user/str_larg b/doc/user/str_larg new file mode 100644 index 0000000..618e69f --- /dev/null +++ b/doc/user/str_larg @@ -0,0 +1,177 @@ +@Section + @Title { Large-scale structure: chapters, sections, etc. } + @RunningTitle { Large-scale structure } + @Tag { largescale } +@Begin +@PP +Lout's large-scale structure symbols vary with the type of document +large.scale. @Index { large-scale structure } +({@Code "@Chapter"} for books, @Code "@Overhead" for overhead +transparencies, etc.), but they all work in the same way. Here is a +typical example, {@Code "@Section"}, as it would actually be used: +@ID @OneRow @Code { +"@Section" +" @Title { Allocation of teachers }" +"@Begin" +"@PP" +"Apart from the usual need to avoid clashes, the allocation of teachers must" +"ensure that no teacher teaches more than seven periods per day, or ..." +"@End @Section" +} +First comes the symbol itself, then any options in the usual way, and +then the following object, enclosed in @Code "@Begin" and +{@Code "@End @Section"}. The following object, also called the body +of the section, may contain paragraphs, displays, and all the other +features as usual. The body should begin with a paragraph symbol, +which may be @Code "@PP" or @Code "@LP" as you prefer. The result is +a section like the present one, automatically numbered, with the +@Code "@Title" option for its heading, preceded by a conditional new +title. @Index @Code "@Title" +page symbol (Section {@NumberOf paragraphs}). +@PP +When @Code "@Section" symbols are used within an ordinary document, they +must be bracketed by @Code "@BeginSections" and @Code "@EndSections" +symbols, like this: +@ID @OneRow @Code { +"@SysInclude { doc }" +"@Doc @Text @Begin" +"preceding text" +"@BeginSections" +"@Section ... @End @Section" +"@Section ... @End @Section" +"..." +"@Section ... @End @Section" +"@EndSections" +"@End @Text" +} +This arrangement is reminiscent of the one for lists, and, as for +lists, there may be no paragraph or new page symbols before, between, +or after the sections. To change the gap between sections, you need +to change the @Code "@SectionGap" option in the setup file, as explained +in Chapter {@NumberOf types}. +@PP +The @Code "@Begin ... @End @Section" that brackets the body of each +section may be abbreviated to {@Code "{ ... }"}. However, the long +form is recommended because it helps Lout to detect missing or extra +braces within the body of the section. +@PP +All large-scale structure symbols have a @Code "@Tag" option, whose +use is explained in Section {@NumberOf cross}, and a @Code "@RunningTitle" +runningtitle. @Index @Code "@RunningTitle" +option. If running page headers have been requested, @Code "@RunningTitle" +will be used if it is given, otherwise @Code "@Title" will be used for the +running header. For example, the present section begins like this: +@ID @OneRow @Code { +"@Section" +" @Title { Large-scale structure: chapters, sections, etc. }" +" @RunningTitle { Large-scale structure }" +" @Tag { largescale }" +"@Begin" +"..." +} +The point is that the section title is rather long for a running +title, and so we use @Code "@RunningTitle" to get an abbreviated +version of it. +@PP +Section titles typically appear in Bold face in the section heading, +but in Roman face in tables of contents and running page headers. So +if part of your title is in italics, enclose it in @Code "@II" rather +than just @Code "@I" to ensure that you get the right kind of italics +in both contexts. +@PP +All large-scale structure symbols also have an @Code "@InitialLanguage" +option which sets the current language for the duration of that +symbol. However, footnotes, endnotes, figures, tables, references, +and index entries are set in the initial language of the document as +a whole, unless you change their language explicitly using the +@Code "@Language" symbol. +@PP +The remainder of this section describes the setup file options for +controlling the appearance of large-scale structure symbols. (For an +introduction to setup files, consult Section {@NumberOf setup}.) These +options mainly appear in the third @Code "@Use" clause, since exactly which +large-scale structure symbols exist depends on the type of document. For +example, here are the setup file options from the @Code "doc" setup file +relating to appendices: +@ID @OneRow @Code { +"@AppendixWord { appendix }" +"@AppendixNumbers { UCAlpha }" +"@FirstAppendixNumber { 1 }" +"@AppendixHeadingFont { Bold }" +"@AppendixHeadingBreak { ragged 1.2fx nohyphen }" +"@AppendixHeadingFormat { number @DotSep title }" +"@AppendixGap { 2.0v @OrIfPlain 2f }" +"@AppendixInContents { Yes }" +"@AppendixNumInTheorems { No }" +"@AppendixNumInDisplays { Yes }" +"@AppendixNumInFigures { No }" +"@AppendixNumInTables { No }" +"@AppendixPrefix { }" +} +There are similar options for each large-scale structure symbol. Here is +a brief explanation. +@PP +@Code "@AppendixWord" contains the word that is to be prefixed to the +appendix number in full headings. The special value @Code appendix +produces Appendix or its equivalent translated into the current +language. Any other value produces itself. +@PP +@Code "@AppendixNumbers" determines the style of numbering of appendices, +and may be {@Code Arabic}, {@Code Roman}, {@Code UCRoman}, {@Code Alpha}, +{@Code UCAlpha}, or {@Code None} meaning unnumbered. Most common is +{@Code Arabic}, but appendices traditionally use upper-case +letters, hence the value {@Code UCAlpha} given above. +@PP +@Code "@FirstAppendixNumber { 1 }" is the number (always in Arabic) to +assign to the first appendix. It is almost always 1, but a few people +like to start their numbering from 0; this is only possible if the +style of numbering specified by @Code "@AppendixNumbers" is {@Code Arabic}. +@PP +@Code "@AppendixHeadingFont" and @Code "@AppendixHeadingBreak" specify +the font and paragraph breaking style to be applied to the appendix +heading (relative to {@Code "@InitialFont"} and {@Code "@InitialBreak"}); +the default values shown above produce Bold in the current font family +and size, and ragged breaking without hyphenation. +@PP +@Code "@AppendixHeadingFormat" defines the format of the appendix +heading. Within it, the symbols @Code number and @Code title stand for the +appendix number (including the appendix word) and title respectively. The +@Code "@DotSep" symbol produces a dot and two spaces, except when there is +no number, when it produces nothing. For example, to draw a full-width +rule under the heading, change this option to +@ID @Code "@AppendixHeadingFormat { number @DotSep title @LP @FullWidthRule }" +Arbitrary formats are acceptable. +@PP +@Code "@AppendixGap" determines the vertical space to leave between +appendices; the default above leaves {@Code 2v}, except that when plain +text output is in effect it leaves @Code 2f instead. To get a new page +between appendices, use the magic value {@Code 2b}, which is raw Lout for +new page. In books, the major components (preface, introduction, tables +of contents, parts, chapters, appendices, and indexes) always start on a +new page and there is nothing you can do to change that. +@PP +@Code "@AppendixInContents" determines whether the appendix will be listed +in the table of contents, and may be @Code "Yes" or {@Code No}. The +next few options determine whether an appendix number will be included +in the numbers assigned to theorems etc., numbered displays, figures, +and tables. +@PP +There is a @Code "@StructPageNums" setup file option which determines +whether page numbers will include the numbers of large-scale structure +symbols. If it is {@Code "Yes"}, @Code "@AppendixPrefix" is prefixed +to all page numbers of pages containing appendices. For example, setting +@Code "@AppendixPrefix" to @Code { APP- } produces page +numbers APP-A-1, APP-A-2, and so on. The object separating each element +of such compound numbers is determined by the @Code "@NumberSeparator" +numberseparator. @Index @Code "@NumberSeparator" +setup file option, which has default value @Code "." but which can easily +be set to @Code "-" or @Code "--" if desired. +@PP +Running page headers above appendices always include the title of +the appendix, so there is no option for specifying whether to do so or +not. But for subappendices and other such smaller units, the choice of +whether to mention them in running headers is left to the user: +@ID @Code "@SubAppendixNumInRunners { Yes }" +Despite the misleading name, this option determines whether the entire +subappendix @I title as well as number will be used as a running header. +@End @Section diff --git a/doc/user/str_list b/doc/user/str_list new file mode 100644 index 0000000..0654ca6 --- /dev/null +++ b/doc/user/str_list @@ -0,0 +1,392 @@ +@Section + @Title { Lists } + @Tag { lists } +@Begin +@PP +The @Code "@List" symbol introduces a sequence of items to be +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" +} +After the initial @Code "@List" symbol, each item is introduced by +list.item. @Index @Code "@ListItem" +li. @Index @Code "@LI" +{@Code "@ListItem"}, and the list ends with {@Code "@EndList"}. The +end.list. @Index @Code "@EndList" +el. @Index @Code "@EL" +result here is +@ID @OneRow { +preceding text +@List +@ListItem @I Emma +@ListItem @I { Mansfield Park } +@EndList +following text +} +with space inserted automatically before, between, and after +the items. +@PP +As the example shows, the @Code "@List" symbol causes the items to be +indented. Also available are {@Code "@LeftList"}, {@Code "@IndentedList"}, +leftlist. @Index @Code "@LeftList" +ll. @Index @Code "@LL" +indentedlist. @Index @Code "@IndentedList" +il. @Index @Code "@IL" +{@Code "@QuotedList"}, {@Code "@CentredList"}, and {@Code "@CenteredList"}, +quotedlist. @Index @Code "@QuotedList" +ql. @Index @Code "@QL" +centredlist. @Index @Code "@CentredList" +centeredlist. @Index @Code "@CenteredList" +cl. @Index @Code "@CL" +which format the items like the corresponding display symbols do. +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" +} +has result +@ID @OneRow { +@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? } +@RawEndList +} +The generated labels are added at the left margin. Here is the full set +of label-generating list symbols, showing the first label produced by each: +parennumberedlist. @Index @Code "@ParenNumberedList" +pnl. @Index @Code "@PNL" +romanlist. @Index @Code "@RomanList" +rl. @Index @Code "@RL" +parenromanlist. @Index @Code "@ParenRomanList" +prl. @Index @Code "@PRL" +ucromanlist. @Index @Code "@UCRomanList" +ucrl. @Index @Code "@UCRL" +parenucromanlist. @Index @Code "@ParenUCRomanList" +pucrl. @Index @Code "@PUCRL" +alphalist. @Index @Code "@AlphaList" +al. @Index @Code "@AL" +parenalphalist. @Index @Code "@ParenAlphaList" +pal. @Index @Code "@PAL" +ucalphalist. @Index @Code "@UCAlphaList" +ucal. @Index @Code "@UCAL" +parenucalphalist. @Index @Code "@ParenUCAlphaList" +pucal. @Index @Code "@PUCAL" +bulletlist. @Index @Code "@BulletList" +bl. @Index @Code "@BL" +starlist. @Index @Code "@StarList" +sl. @Index @Code "@SL" +dashlist. @Index @Code "@DashList" +dl. @Index @Code "@DL" +@ID @Tab + @Fmta { @Col @CC A ! @Col @Code B ! @Col ! @Col @CC C ! @Col @Code D } +{ +@Rowa + A { 1. } + B { "@NumberedList" } + C { (1) } + D { "@ParenNumberedList" } +@Rowa + A { i. } + B { "@RomanList" } + C { (i) } + D { "@ParenRomanList" } +@Rowa + A { I. } + B { "@UCRomanList" } + C { (I) } + D { "@ParenUCRomanList" } +@Rowa + A { a. } + B { "@AlphaList" } + C { (a) } + D { "@ParenAlphaList" } +@Rowa + A { A. } + B { "@UCAlphaList" } + C { (A) } + D { "@ParenUCAlphaList" } +@Rowa + A { @Bullet } + B { "@BulletList" } +@Rowa + A { @Star } + B { "@StarList" } +@Rowa + A { -- } + B { "@DashList" } +} +roman @Index { Roman numerals } +The Roman numerals end at cc (200), but ordinary decimal numbers have +no limit. The labels produced by the four alphabetical list symbols are +determined by the current language; in English they start at @Code "a" +and end at {@Code "z"}. +@PP +You may also supply your own labels using the @Code "@TaggedList" +taggedlist @Index @Code "@TaggedList" +tl. @Index @Code "@TL" +symbol. Each item is introduced by @Code "@TagItem" instead of +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" +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" +} +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 +enclosing braces must be there. The result here is +@ID @OneRow { +@RawWideTaggedList +@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.' } +@RawEndList +} +An alternative way to accommodate wide labels is the `drop item,' +drop.item @Index { drop items } +which looks like this: +@ID @OneRow { +@RawTaggedList +@DTI { 10 a.m. } { Prof. A. Smith speaks on `The Wealth of Nations.' } +@RawEndList +} +Individual items are dropped in this way by using @Code "@DropTagItem" +drop.tag.item @Index @Code "@DropTagItem" +dti. @Index @Code "@DTI" +instead of {@Code "@TagItem"}. There is also a @Code "@DropListItem" +drop.list.item @Index @Code "@DropListItem" +dli. @Index @Code "@DLI" +symbol corresponding to {@Code "@ListItem"}, but it is very rarely +needed. Lout is not able to decide for itself whether a label is wide +enough to require a drop item. +@PP +Each list has a `raw' version which omits the preceding space, and +raw.lists @Index { raw lists } +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" +} +produces +@ID @OneRow { +@RawParenNumberedList +@ListItem { + @RawParenRomanList + @ListItem { MV Nominees, +hereinafter called the vendor, ... } + @RawEndList +} +@RawEndList +} +If @Code "@ParenRomanList" had been used instead of +{@Code "@RawParenRomanList"}, (1) and (i) would have appeared on +different lines; or if @Code "@EndList" had been used instead of +{@Code "@RawEndList"}, there would have been too much space following +the list. +@PP +A list item may come out partly on one page or column and partly on +the next, if it has places where it obviously can be broken in two. For +example, a list item which is an ordinary paragraph of text might be +broken in two between any two lines. To force a list item to keep +together on one page or column, use the @Code "@OneRow" symbol like +this: @Code "@ListItem @OneRow { ... }". +@PP +Occasionally it is desirable to start a new page or column between +two list items. This cannot be done by inserting @Code "@NP" +between them, because the space between two list items is a kind +of no-man's land where nothing is allowed to be. Instead, the +@Code "@ListNewPage" symbol is used: it is permitted only between +two list items, and its effect is to make the following list item +appear at the top of the next page or column. It may be used within +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" +} +produces +@ID @OneRow { +@RawNumberedList +@ListItem { This is the first list item. } +@ListInterruptItem { This is an interruption to the list. } +@ListItem { This is the second list item. } +@RawEndList +} +Although @Code "@ListInterruptItem" is written like a list item, the +result appears to be an interruption to the list. It may be used +in any kind of list. +@PP +Every symbol introduced in this section has an abbreviated form +consisting of @Code "@" followed by its capital letters only. For +example, @Code "@RawNumberedList" abbreviates to {@Code "@RNL"}, +and @Code "@ListItem" to {@Code "@LI"}. The sole exception is +{@Code "@RawList"}, which has no abbreviation because @Code "@RL" +is the abbreviation for {@Code "@RomanList"}. +@PP +list.symbol.options @Index { list symbol options } +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 }" +} +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" +with {@Code "@CentredList"} or @Code "style" with {@Code "@BulletList"}, +since the list symbol has clearly already set the option. +@PP +The @Code "type" option determines the type of numbering (Arabic, Roman, +etc.) and is not intended for ordinary use, since there are distinct +symbols for each type, as we have seen. The @Code "style" option +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) }" +} +and @Code "@BulletList" is just +@ID @OneRow @Code { +"@List" +" style { @Bullet }" +} +with @Code "num" not mentioned since no number is wanted. The +@Code "@TaggedList" symbol and its variants also have the +@Code "style" option; in their case, the @Code "num" symbol within +it must be mentioned exactly once, and its value is set to produce +the label supplied by the author. +@PP +The @Code "labelwidth" option determines the width set aside for the labels; +this is where @Code "@WideTaggedList" and @Code "@VeryWideTaggedList" differ +from {@Code "@TaggedList"}. The @Code "indent" and @Code "rightindent" +options determine the space left blank at the left and right margins. The +value given to these three options may be any length, for example +@Code "0.5i" (half an inch), or @Code "0.5f" (half the current font +size). Section {@NumberOf objects} describes lengths in general. There +are also three useful symbols denoting lengths: @Code "@DisplayIndent" +is the amount by which indented and quoted displays are indented; +@Code "@WideIndent" and @Code "@VeryWideIndent" are the indents used by +@Code "@WideTaggedList" and {@Code "@VeryWideTaggedList"}. Using these +symbols helps to keep documents consistent. +@PP +The @Code "gap" option determines the vertical space inserted between +items. Once again this must be a length, although since it is +vertical rather than horizontal, somewhat different kinds of lengths +are appropriate: @Code "1.5v" for 1.5 times the current vertical space +between lines, or the default value, {@Code "@DisplayGap"}, which produces +the amount of vertical space used before and after displays. Owing to +problems behind the scenes, there is no list option for the space before or after +the list as a whole. To change this space in one list, use a raw list and +insert your own paragraph symbols; to change it in every list there is a +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 }" +} +looks strange, but it is the correct way to number the first +item (xxv). +@PP +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" +} +The result is +@ID @OneRow { +preceding text +@List + style { @I {Item num}: } + indent { @DisplayIndent } + rightindent { @DisplayIndent } + labelwidth { @WideIndent } + start { 10 } +@ListItem { +The vendor will not be liable for any injury caused by the escape of +radiation or radioactive materials from the facility, nor for the +costs of repair of any property damaged by nuclear blast or fallout +in the case of accident. +} +@ListItem { +The vendor will not be liable for any injury caused by radioactive +materials being transported to or from the facility, nor for injury +caused by radioactive materials stored adjacent to the facility. +} +@EndList +following text +} +You can change the @I default values of the {@Code "labelwidth"}, +{@Code "indent"}, {@Code "rightindent"}, and {@Code "gap"} options, +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. +@End @Section diff --git a/doc/user/str_marg b/doc/user/str_marg new file mode 100644 index 0000000..0f9f75d --- /dev/null +++ b/doc/user/str_marg @@ -0,0 +1,156 @@ +@Section + @Title { Margin notes and arbitrary placement } + @Tag { marginnotes } +@Begin +@PP +A note can be placed in the left margin by typing +leftnote. @Index @Code "@LeftNote" +marginnote. @Index { margin notes } +@ID { +@Code "@LeftNote { A left note. }" +@LeftNote { A left note. } +} +after the word that the note refers to. The note will appear in the +margin at the same height on the page as that word, unless that would +cause it to overlap a previous margin note, in which case it will be +shifted downwards (but never onto the next page). The note may be an +arbitrary Lout object; for example, you might type +@ID { +@Code "@LeftNote @I { A left note. }" +@LeftNote @I { A left note. } +} +to make your note come out in italics. +@PP +You can get a note in the right margin by using @Code "@RightNote" +@RightNote { A right note. } +rightnote. @Index @Code "@RightNote" +instead of {@Code "@LeftNote"}. To get a note in the outer margin +(left on even pages, right on odd pages), use {@Code "@OuterNote"}; +@OuterNote { An outer note. } +outernote. @Index @Code "@OuterNote" +and for the opposite, use {@Code "@InnerNote"}. +@InnerNote { An inner note. } +@PP +By default, Lout produces margins that are 2.5 centimetres wide, which +is not really enough to accommodate reasonable margin notes. To +change these margins, you need to change options in the setup file, as +explained in Section {@NumberOf margins}. +@PP +The appearance of the margin notes themselves is also determined by +options in the setup file (for a general introduction to setup files +and their options, consult Section {@NumberOf setup}). Here are +the options and their default values: +@ID @OneRow @Code { +"@MarginNoteFont { 0.80f }" +"@MarginNoteBreak { ragged 1.10fx }" +"@MarginNoteHGap { 0.5c }" +"@MarginNoteVGap { 1.00v }" +"@MarginNoteWidth { 1.50c }" +} +@Code "@MarginNoteFont" determines the font; the default value +produces the current font scaled to 0.8 times the current size. +@Code "Slope 0.80f" would yield italic notes, and so +on. @Code "@MarginNoteBreak" is the paragraph breaking style, +similar to the @Code "@InitialBreak" setup file option. +@PP +@Code "@MarginNoteHGap" determines how far away from the +adjacent text column the margin note will appear; the default +value is 0.5 centimetres. @Code "@MarginNoteVGap" is the minimum +vertical separation between margin notes (i.e. it determines how +far downwards a note will be shifted to avoid the previous +one). @Code "@MarginNoteWidth" determines the width of the column +in which margin notes (both left and right) are set; the default +value of 1.5 centimetres is suited to the 2.5 centimetre page margins +that are the default, but if you widen the page margins you will be +able to increase @Code "@MarginNoteWidth" too. +@PP +Left notes extend into the left margin a total distance of +@Code "@MarginNoteHGap" plus {@Code "@MarginNoteWidth"}, and it is +up to you to make sure that this does not put them off +the page. Similar remarks apply to right notes. And since notes +are never shifted to the next page, only downwards, there is also +a risk that a note will be shifted off the bottom of the page, if +it is very long or if preceding notes obstruct it. Again, it is +up to you to avoid this problem by keeping your notes small and not +too close together. +@PP +Margin notes inside footnotes, figures and tables work well. Margin +notes in multi-column documents are disastrous unless used very +sparingly. Margin notes do not appear in plain text output +(Section {@NumberOf plain}). +@PP +A more radical way to place objects at arbitrary points on the current +place. @Index @Code "@Place" +page is provided by the @Code "@Place" symbol: +@ID @OneRow @Code { +"@Place" +" x { right - 1 cm - xsize }" +" y { { foot + top } / 2 }" +"{" +" @Box { Hello }" +"}" +} +The placed object may be any object. This particular example produces a +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 } + 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 +may be used inside the @Code "x" and @Code "y" options: +@ID @Tab + @Fmta { @Col @Code A ! @Col B } +{ +@Rowa + A { left } + B { The left edge of the page } +@Rowa + A { right } + B { The right edge of the page } +@Rowa + A { foot } + B { The foot edge of the page } +@Rowa + A { top } + B { The top edge of the page } +@Rowa + A { "+" } + B { Addition (positive is to the right and up) } +@Rowa + A { "-" } + B { Subtraction (negative is to the left and down) } +@Rowa + A { "*" } + B { Multiplication } +@Rowa + A { "/" } + B { Division } +@Rowa + A { "xsize" } + B { The width of the object being placed } +@Rowa + A { "xmark" } + B { The column mark of the object being placed (for expert users) } +@Rowa + A { "ysize" } + B { The height of the object being placed } +@Rowa + A { "ymark" } + B { The row mark of the object being placed (for expert users) } +} +The usual precedences and associativities apply to the mathematical +operators; braces (not parentheses) may be used for grouping. It is +best to give values to @Code "x" and @Code y that do not depend on +any assumptions about where the coordinate system's origin is; this +is true of the examples above. At the point where @Code "@Place" occurs, +the result is an empty object. As with margin notes, Lout does not know +what is happening and will not lay out the rest of the page around the +placed object. +@End @Section diff --git a/doc/user/str_theo b/doc/user/str_theo new file mode 100644 index 0000000..5d85c37 --- /dev/null +++ b/doc/user/str_theo @@ -0,0 +1,108 @@ +@Section + @Title { Theorems, lemmas, corollaries, definitions, propositions, +examples, and claims } + @RunningTitle { Theorems, lemmas, etc. } + @Tag { theorems } +@Begin +@PP +theorem. @Index @Code "@Theorem" +A theorem is created like this: +@ID @OneRow @Code { +"@LD @Theorem" +" @Title { Fermat's Last Theorem }" +"{" +"@Eq { a sup n + b sup n != c sup n } for all positive integers @Eq { a }," +"@Eq { b }, @Eq { c } and @Eq { n } when @Eq { n > 2 }." +"@LP" +"@Proof I have a proof of this theorem, but the margin" +"is too small to contain it. @EndProof" +"}" +} +where we have used the @Code "@LD" `left display' symbol from +Section {@NumberOf displays} to get a left-justified display, +and the @Code "@Eq" symbol from Chapter {@NumberOf equations} +for the equations. The result is +@ID @Theorem + @Title { Fermat's Last Theorem } +{ +@Eq { a sup n + b sup n != c sup n } for all positive integers @Eq { a }, +@Eq { b }, @Eq { c } and @Eq { n } when @Eq { n > 2 }. +@LP +@Proof I have a proof of this theorem, but the margin +is too small to contain it. @EndProof +} +The @Code "@Theorem" symbol produces an object with no adjacent +vertical space, hence it needs to be used in conjuction with +display or paragraph symbols. The theorem is numbered automatically, +with the title and number inserted at the start of the first +paragraph. @Code "@Title" may be omitted. +@PP +@Code "@Proof" produces @Proof @Null +proof. @Index @Code "@Proof" +with the appropriate following space, and @Code "@EndProof" produces +endproof. @Index @Code "@EndProof" +a box at the end of the line. They may be used anywhere, not +just within theorems. +@FootNote { Occasionally @Code "@EndProof" does not +appear as far to the right as it should. This problem can be fixed by using +{@Code "@LD @HExpand @Theorem"}, which instructs Lout to make sure +that as much horizontal space as possible is allocated to the theorem. } +@PP +There are seven symbols that produce independently numbered sequences +in this way. They are {@Code "@Theorem"}, {@Code "@Definition"}, +definition. @Index @Code "@Definition" +claim. @Index @Code "@Claim" +proposition. @Index @Code "@Proposition" +lemma. @Index @Code "@Lemma" +corollary. @Index @Code "@Corollary" +example. @Index @Code "@Example" +{@Code "@Claim"}, {@Code "@Proposition"}, {@Code "@Lemma"}, +{@Code "@Corollary"}, and {@Code "@Example"}. +@PP +The setup file contains options which determine whether the theorem +numbers include a chapter number ({@Code "@ChapterNumInTheorems"}), +or a section number ({@Code "@SectionNumInTheorems"}), and so on. A +section number automatically includes a chapter number, etc. There +are also options to change the word printed. For example, if you +need a sequence of conjectures, change the @Code "@ClaimWord" setup +file option to +@ID @Code "@ClaimWord { Conjecture }" +and use the @Code "@Claim" symbol for your conjectures. You can even put +@ID @Code { +"import @DocumentSetup" +"macro @Conjecture { @Claim }" +} +into your @Code mydefs file (Section {@NumberOf definitions}) if you wish, +so that you can write @Code "@Conjecture" in your documents instead of +{@Code "@Claim"}. +@PP +The setup file also contains two options which control the format of +the theorem (claims and so on have corresponding options). Here they +are with their default values: +@ID @Code { +"@TheoremTitleFormat { (title) }" +"@TheoremFormat { { @B { word @NumSep number title: } &2s } @Insert body }" +} +The first option is used only when a @Code "@Title" is given to the +theorem, and it determines how the title is formatted: the @Code title +symbol within the option stands for the @Code "@Title" option. The default +value shown places parentheses around the title. The second option +determines the format of the entire theorem. Within it, @Code word +stands for the value of {@Code "@TheoremWord"}; +@Code "number" is the number of the theorem; @Code "title" is the title +of the theorem after formatting by {@Code "@TheoremFormat"} (if there +is a title; otherwise @Code title is {@Code "@Null"}, which prints as +nothing and even deletes the preceding space as required); and +@Code body is the body of the theorem. The default value prints the +word, number and title with a colon in bold, and inserts them and two +spaces into the first paragraph of the body; another value might be +@ID @Code { "@TheoremFormat { @B { word @NumSep number title } @LP body }" } +which places the header in bold on a line by itself, separated from the +body by a paragraph break. For @Code "@NumSep" see page {@PageOf numsep}. +@PP +Owing to problems behind the scenes, the @Code "@Theorem" symbol and its +companions have a potential efficiency problem: although all numbers are +finalized on the second run, it takes Lout time proportional to the square +of the highest theorem number to do this. So large numbers of theorems +numbered together might be slow. +@End @Section diff --git a/doc/user/su_crest.eps b/doc/user/su_crest.eps new file mode 100644 index 0000000..95bc0f9 --- /dev/null +++ b/doc/user/su_crest.eps @@ -0,0 +1,1156 @@ +%!PS-Adobe-3.0 EPSF-3.0 +%%BoundingBox: 0 0 60 53 +%%Pages: 1 +%%Title: Crest for The University of Sydney +%%Creator: jaa@cs.su.oz.au encapsulated by rex@cs.su.oz.au +%%+ Converted for colour and bug fixes by Rex. +%%CreationDate: Wed May 13 18:02:34 EST 1992 +%%+ Converted for colour: Tue Jul 7 20:06:30 EST 1992 +%%DocumentNeededResources: font Times-Bold +%%EndComments +%%BeginProlog +%%EndProlog +%%BeginSetup +%%EndSetup + +% PMS colours +% red - 185 +% blue - 286 +% gold - 871 +gsave +.01 dup scale +-1988 -1050 translate +/colour 1 def % set to one if colour +/pathtextdict 27 dict def + +/pathtext + { pathtextdict begin + /spacing exch def + /offset exch def + /str exch def + /pathdist 0 def + /offset offset str 0 1 getinterval stringwidth pop 2 div add def + /setdist offset def + /charcount 0 def + gsave flattenpath + {movetoproc} {linetoproc} {} {closepathproc} pathforall + grestore + newpath + end } def + +pathtextdict begin + +/movetoproc + { /newy exch def /newx exch def + /firstx newx def /firsty newy def + /ovr setdist pathdist sub def + newx newy transform + /cpy exch def /cpx exch def } def + +/linetoproc + { /oldx newx def /oldy newy def + /newy exch def /newx exch def + /dx newx oldx sub def + /dy newy oldy sub def + /dist dx dup mul dy dup mul add sqrt def + dist 0 ne + { /dsx dx dist div ovr mul def + /dsy dy dist div ovr mul def + oldx dsx add oldy dsy add transform + /cpy exch def /cpx exch def + /pathdist pathdist dist add def + { setdist pathdist le + { charcount str length lt + {setchar} {exit} ifelse } + { /ovr setdist pathdist sub def + exit } + ifelse } loop } if } def + +/closepathproc + { firstx firsty linetoproc + firstx firsty movetoproc } def + +/setchar + { /char str charcount 1 getinterval def + /charcount charcount 1 add def + /charwidth char stringwidth pop def + gsave + cpx cpy itransform translate + dy dx atan rotate + charwidth -2 div 0 moveto char show + /charwidth str length charcount gt + { str charcount 1 getinterval stringwidth pop } + { 0 } ifelse charwidth add 2 div def + charwidth 0 moveto + currentpoint transform + /cpy exch def /cpx exch def + grestore + /setdist setdist charwidth spacing add add def } def +end +/gold_colour { + colour 0 ne + { 0.9453 0.6206 0.004 setrgbcolor } + { 1 setgray } + ifelse +} def +/blue_colour { + colour 0 ne +% { 0.0 0.0 0.0 setrgbcolor } +% { 1.0 1.0 1.0 setrgbcolor } + { 0.0599 0.0526 0.5493 setrgbcolor } + { 1 setgray } + ifelse +} def +/red_colour { + colour 0 ne + { 0.9375 0.0 0.0 setrgbcolor } + { 1 setgray } + ifelse +} def +/c { curveto } def +/m { moveto } def +/l { lineto } def + +/sym1 { 5000 1939 m +4974 2006 4971 2065 4924 2119 c +4909 2137 4893 2152 4870 2153 c +4845 2154 4824 2141 4811 2120 c +4791 2089 4771 2068 4740 2047 c +4722 2079 4713 2105 4706 2141 c +4659 2111 4624 2091 4580 2057 c +4555 2116 4561 2178 4597 2232 c +4570 2236 4551 2242 4525 2242 c +4543 2280 4564 2305 4598 2329 c +4572 2345 4553 2358 4528 2375 c +4432 2284 4332 2235 4201 2226 c +3989 2210 3846 2323 3636 2356 c +3596 2363 3565 2353 3525 2362 c +3478 2372 3444 2415 3441 2463 c +3358 2444 3304 2395 3250 2329 c +3222 2365 3205 2402 3211 2447 c +3179 2445 3148 2437 3135 2408 c +3122 2378 3135 2351 3144 2320 c +3092 2351 3046 2396 3050 2457 c +3053 2509 3097 2544 3146 2563 c +3104 2574 3073 2584 3030 2587 c +3053 2628 3079 2655 3119 2679 c +3070 2703 3031 2726 3003 2773 c +3033 2798 3059 2811 3095 2827 c +3062 2842 3035 2852 2999 2850 c +2961 2846 2934 2826 2909 2798 c +2897 2844 2904 2890 2936 2925 c +2999 2992 3096 2968 3185 2949 c +3143 3062 3116 3145 3080 3260 c +3056 3248 3037 3240 3012 3228 c +3009 3255 3008 3275 3004 3303 c +2954 3263 2914 3228 2851 3218 c +2792 3210 2733 3215 2694 3260 c +2657 3302 2652 3361 2676 3411 c +2698 3457 2745 3480 2796 3479 c +2848 3478 2888 3433 2900 3382 c +2976 3532 2884 3672 2865 3839 c +2853 3951 2882 4059 2972 4127 c +3035 4175 3120 4184 3186 4141 c +3233 4110 3249 4047 3232 3993 c +3306 4030 3338 4126 3312 4204 c +3286 4278 3221 4333 3143 4334 c +3082 4335 3030 4290 3012 4231 c +2987 4270 2970 4307 2979 4352 c +2991 4411 3040 4445 3096 4466 c +3052 4496 3012 4518 2959 4515 c +2915 4512 2887 4486 2857 4455 c +2857 4526 2870 4594 2928 4636 c } def +/sym2 { 3004 4693 3106 4680 3188 4630 c +3195 4668 3210 4699 3241 4721 c +3280 4749 3325 4751 3370 4734 c +3324 4681 3347 4603 3386 4544 c +3428 4480 3447 4422 3454 4346 c +3491 4560 3479 4786 3309 4922 c +3309 4871 3298 4821 3255 4794 c +3200 4760 3143 4771 3080 4784 c +2987 4804 2933 4885 2837 4880 c +2806 4878 2771 4868 2762 4837 c +2750 4800 2777 4768 2801 4737 c +2736 4747 2662 4782 2659 4848 c +2657 4904 2696 4947 2744 4976 c +2706 4986 2676 4992 2637 4986 c +2650 5022 2666 5051 2700 5067 c +2751 5090 2798 5075 2851 5060 c +2854 5126 2881 5190 2942 5213 c +2997 5235 3049 5211 3099 5180 c +3043 5175 2983 5150 2972 5095 c +2960 5029 2985 4969 3033 4922 c +3045 4972 3068 5004 3102 5043 c +3175 5126 3245 5203 3235 5313 c +3228 5402 3182 5463 3122 5528 c +3096 5557 3073 5580 3067 5618 c +3059 5671 3076 5722 3118 5756 c +3174 5801 3245 5811 3313 5787 c +3350 5775 3378 5745 3382 5707 c +3387 5660 3355 5625 3320 5594 c +3378 5596 3424 5615 3465 5657 c +3488 5680 3500 5709 3492 5741 c +3479 5789 3422 5808 3372 5807 c +3398 5849 3436 5877 3485 5879 c +3540 5881 3582 5851 3621 5812 c +3626 5868 3617 5910 3633 5965 c +3647 6015 3678 6046 3720 6077 c +3728 6032 3736 5996 3761 5957 c +3793 6007 3828 6041 3883 6062 c +3939 6083 3991 6081 4047 6060 c +3996 6024 3964 5988 3935 5934 c +3967 5942 3991 5948 4021 5962 c +4016 5935 4014 5915 4008 5889 c +4103 5911 4184 5919 4273 5880 c +4323 5858 4354 5820 4374 5768 c +4396 5801 4407 5829 4419 5867 c +4426 5890 4435 5908 4453 5924 c +4487 5953 4511 5975 4544 6004 c +4556 5978 4563 5960 4575 5935 c +4629 5971 4670 5993 4721 6033 c +4730 5997 4739 5972 4751 5937 c +4775 5951 4795 5964 4806 5990 c +4816 6013 4815 6039 4797 6057 c +4771 6083 4733 6075 4696 6068 c +4704 6112 4719 6149 4757 6172 c +4799 6198 4847 6189 4892 6169 c +4896 6198 4905 6220 4923 6243 c +4942 6267 4969 6275 5000 6276 c +closepath 0 setgray fill } def +/sym3 { 5000 6214 m +4943 6214 4937 6122 4950 6067 c +4900 6113 4830 6146 4770 6114 c +4809 6102 4847 6083 4855 6044 c +4876 5953 4780 5890 4699 5844 c +4690 5859 4685 5870 4676 5885 c +4687 5894 4695 5900 4705 5908 c +4700 5925 4697 5938 4692 5955 c +4663 5938 4642 5927 4615 5910 c +4588 5893 4579 5868 4565 5840 c +4549 5838 4538 5837 4522 5836 c +4531 5867 4536 5892 4530 5924 c +4495 5894 4471 5865 4457 5821 c +4444 5776 4425 5744 4391 5712 c +4388 5697 4383 5687 4376 5673 c +4469 5733 4547 5769 4656 5786 c +4818 5811 4930 5924 5000 6072 c +closepath gold_colour fill +5000 2189 m +4938 2287 4857 2343 4746 2376 c +4678 2396 4629 2419 4570 2459 c +4567 2441 4563 2427 4557 2410 c +4614 2373 4657 2348 4717 2315 c +4676 2303 4642 2301 4606 2277 c +4637 2276 4659 2271 4688 2262 c +4643 2233 4615 2195 4602 2143 c +4652 2176 4692 2196 4748 2215 c +4749 2183 4753 2160 4763 2130 c +4787 2168 4816 2203 4861 2204 c +4925 2205 4976 2156 5000 2096 c +closepath gold_colour fill +4392 2432 m +4408 2444 4419 2476 4402 2484 c +4390 2489 4373 2482 4371 2469 c +4368 2450 4354 2439 4337 2430 c +4322 2422 4305 2425 4292 2436 c +4269 2456 4267 2491 4281 2518 c +4302 2562 4346 2582 4395 2588 c +4443 2593 4494 2578 4515 2534 c +4533 2497 4520 2455 4494 2422 c +4429 2336 4347 2292 4241 2272 c +4078 2243 3955 2308 3798 2362 c +3712 2391 3644 2402 3552 2403 c +3526 2403 3502 2415 3489 2438 c } def +/sym4 { 3478 2458 3480 2484 3496 2500 c +3511 2515 3533 2519 3552 2510 c +3577 2498 3586 2477 3603 2454 c +3616 2466 3627 2472 3641 2482 c +3611 2524 3575 2566 3524 2561 c +3489 2558 3459 2538 3448 2505 c +3371 2498 3317 2460 3262 2407 c +3251 2431 3260 2453 3265 2479 c +3203 2492 3143 2480 3097 2436 c +3096 2455 3095 2471 3107 2487 c +3142 2535 3198 2539 3256 2554 c +3211 2591 3168 2607 3111 2619 c +3127 2634 3139 2645 3158 2654 c +3250 2647 3315 2628 3406 2609 c +3408 2621 3408 2631 3410 2643 c +3340 2669 3285 2680 3211 2689 c +3152 2696 3112 2723 3063 2756 c +3103 2781 3140 2795 3187 2788 c +3134 2861 3054 2899 2965 2890 c +3045 2966 3170 2921 3265 2864 c +3251 2897 3248 2926 3254 2962 c +3340 2893 3343 2793 3410 2707 c +3422 2716 3431 2723 3443 2732 c +3372 2844 3351 2965 3233 3026 c +3227 3016 3223 3008 3218 2997 c +3175 3107 3141 3187 3116 3302 c +3124 3313 3128 3322 3135 3333 c +3160 3280 3179 3241 3192 3184 c +3252 3221 3277 3279 3291 3349 c +3355 3062 3431 2842 3621 2618 c +3809 2396 4163 2253 4392 2432 c +closepath gold_colour fill +3039 4863 m +2983 4908 2943 4954 2927 5024 c +2915 5080 2929 5128 2960 5175 c +2899 5138 2888 5055 2909 4986 c +2847 5018 2791 5045 2724 5028 c +2766 5018 2795 4995 2820 4959 c +2781 4942 2744 4934 2720 4898 c +2705 4875 2705 4845 2720 4822 c +2727 4875 2775 4915 2829 4920 c +2912 4928 2966 4873 3045 4844 c +3043 4851 3042 4856 3039 4863 c +closepath gold_colour } def +/sym5 { 3771 5716 m +3765 5719 3760 5721 3754 5724 c +3770 5759 3789 5787 3823 5803 c +3878 5829 3926 5846 3959 5896 c +3928 5887 3906 5879 3877 5866 c +3878 5934 3908 5984 3952 6036 c +3868 6021 3814 5962 3770 5888 c +3735 5918 3714 5947 3698 5990 c +3657 5925 3671 5860 3657 5785 c +3646 5724 3605 5682 3549 5656 c +3576 5689 3603 5723 3592 5765 c +3578 5817 3517 5835 3463 5835 c +3513 5807 3554 5753 3539 5697 c +3504 5571 3311 5510 3202 5581 c +3175 5599 3155 5628 3162 5659 c +3170 5697 3216 5709 3255 5709 c +3264 5709 3272 5699 3272 5690 c +3272 5682 3266 5673 3258 5672 c +3242 5672 3219 5667 3219 5650 c +3219 5634 3234 5620 3250 5619 c +3283 5618 3311 5638 3327 5667 c +3340 5692 3331 5728 3306 5741 c +3261 5764 3210 5761 3167 5733 c +3130 5710 3107 5670 3114 5627 c +3125 5558 3186 5514 3254 5498 c +3369 5471 3464 5510 3568 5565 c +3734 5651 3855 5715 4032 5775 c +4106 5801 4192 5825 4246 5767 c +4264 5748 4269 5713 4249 5695 c +4238 5684 4222 5684 4207 5688 c +4197 5690 4189 5710 4198 5714 c +4205 5717 4213 5722 4212 5729 c +4210 5738 4203 5742 4196 5747 c +4180 5756 4160 5757 4145 5747 c +4128 5736 4119 5718 4119 5698 c +4119 5657 4151 5616 4192 5612 c +4242 5608 4293 5626 4316 5670 c +4339 5715 4335 5769 4301 5806 c +4259 5852 4200 5860 4138 5854 c +4067 5848 4018 5824 3948 5818 c +3890 5771 3825 5768 3771 5716 c +closepath gold_colour fill +3351 3504 m +3316 3561 3252 3571 3187 3584 c +3110 3600 3060 3641 3004 3697 c +3016 3707 3025 3713 3037 3724 c +3101 3660 3167 3625 3257 3613 c +3312 3606 3361 3640 3388 3688 c +3411 3731 3408 3781 3382 3822 c +3364 3849 3334 3858 3302 3859 c +3271 3861 3242 3842 3231 3813 c +3222 3791 3221 3763 3240 3749 c +3253 3739 3284 3740 3285 3757 c +3286 3768 3301 3773 3312 3771 c +3322 3769 3329 3757 3326 3747 c +3322 3727 3305 3714 3284 3708 c +3256 3700 3230 3704 3203 3718 c +3115 3764 3064 3837 3037 3933 c +3113 3879 3205 3865 3289 3905 c +3595 4053 3667 4488 3532 4801 c +3477 4929 3390 5011 3265 5073 c +3297 5102 3328 5121 3371 5123 c } def +/sym6 { 3413 5125 3443 5105 3479 5084 c +3476 5132 3466 5167 3451 5214 c +3527 5188 3578 5153 3638 5100 c +3632 5179 3602 5235 3556 5299 c +3590 5327 3613 5351 3634 5389 c +3530 5370 3412 5363 3351 5450 c +3310 5451 3280 5452 3240 5461 c +3287 5354 3297 5242 3236 5142 c +3194 5074 3147 5036 3101 4970 c +3075 4931 3081 4876 3115 4844 c +3144 4817 3187 4810 3223 4827 c +3260 4844 3270 4889 3265 4928 c +3262 4944 3246 4954 3230 4952 c +3215 4951 3195 4943 3196 4927 c +3198 4910 3191 4886 3174 4887 c +3140 4888 3147 4960 3174 4980 c +3197 4996 3221 5002 3248 4995 c +3457 4941 3527 4682 3509 4467 c +3501 4375 3484 4302 3429 4228 c +3414 4238 3403 4244 3389 4254 c +3422 4339 3411 4425 3360 4500 c +3318 4562 3278 4620 3293 4695 c +3239 4664 3226 4599 3234 4538 c +3175 4590 3117 4626 3039 4626 c +2987 4625 2949 4593 2920 4550 c +3017 4578 3119 4523 3169 4436 c +3099 4425 3027 4388 3017 4318 c +3072 4363 3134 4389 3203 4373 c +3269 4357 3316 4315 3344 4253 c +3384 4164 3381 4054 3308 3990 c +3269 3956 3220 3939 3171 3956 c +3138 3948 3102 3956 3083 3984 c +3070 4003 3072 4027 3084 4047 c +3094 4064 3113 4077 3132 4073 c +3145 4070 3154 4057 3153 4044 c +3152 4035 3146 4027 3137 4025 c +3130 4024 3125 4024 3119 4026 c +3114 4015 3122 4001 3134 3997 c +3152 3992 3170 4004 3181 4019 c +3192 4037 3190 4058 3182 4078 c +3173 4098 3158 4113 3137 4118 c +3063 4138 2984 4100 2947 4034 c +2887 3928 2905 3819 2938 3702 c +2978 3561 2993 3351 2852 3312 c +2826 3305 2798 3300 2778 3318 c +2760 3335 2756 3368 2774 3386 c +2782 3395 2797 3400 2806 3392 c +2813 3385 2815 3372 2808 3364 c +2804 3358 2809 3347 2816 3347 c +2833 3346 2851 3352 2857 3367 c +2865 3390 2850 3414 2830 3427 c +2803 3444 2768 3445 2742 3426 c +2715 3406 2703 3372 2710 3338 c +2719 3293 2759 3258 2805 3257 c +2904 3254 2972 3321 3034 3397 c +3040 3365 3047 3342 3053 3310 c +3088 3343 3108 3375 3125 3420 c +3173 3371 3193 3321 3214 3256 c +3249 3322 3255 3386 3240 3459 c +3283 3440 3321 3428 3368 3437 c +3376 3438 3379 3449 3376 3457 c +3370 3475 3361 3487 3351 3504 c +closepath gold_colour fill } def + +/sym7 { +%main interior +5000 2313 m +4955 2385 4880 2430 4730 2470 c +4670 2490 4630 2538 4621 2553 c +4641 2530 4630 2538 4621 2553 c +4585 2613 4538 2650 4472 2670 c +4397 2694 4326 2682 4259 2639 c +4193 2598 4169 2523 4172 2445 c +3789 2440 3543 2822 3392 3344 c +3431 3350 3458 3359 3495 3371 c +3490 3425 3475 3465 3415 3578 c +3530 3685 3540 3805 3441 3896 c +3632 4058 3686 4286 3678 4536 c +3673 4730 3650 4830 3573 4935 c +3573 5041 l +3596 5023 3630 4992 3667 4942 c +3740 5075 3732 5205 3670 5295 c +3713 5352 3745 5410 3780 5495 c +3692 5468 3608 5445 3533 5440 c +4026 5680 l +4040 5593 4125 5530 4250 5530 c +4310 5530 4415 5580 4453 5616 c +4514 5658 4607 5693 4661 5699 c +4823 5717 4930 5780 5000 5890 c +closepath 1 setgray fill } def +/sym8 { +% Banner outside +5000 1556 m +4862 1556 4759 1613 4651 1699 c +4509 1814 4423 1918 4279 2033 c +4149 2137 4015 2173 3848 2182 c +3697 2189 3587 2175 3436 2165 c +3273 2154 3136 2138 2993 2218 c +2923 2257 2875 2297 2823 2359 c +2818 2365 2826 2373 2832 2378 c +2864 2398 2887 2412 2919 2433 c +2954 2455 2947 2512 2922 2545 c +2881 2600 2850 2641 2823 2703 c +2793 2771 2795 2830 2758 2894 c +2745 2916 2720 2935 2696 2927 c +2647 2911 2610 2902 2561 2886 c +2557 2885 2552 2889 2550 2894 c +2530 2941 2515 2976 2502 3027 c +2500 3032 2505 3038 2510 3040 c +2546 3054 2573 3062 2609 3075 c +2626 3081 2638 3091 2645 3108 c +2652 3125 2651 3142 2643 3159 c +2619 3213 2586 3244 2561 3297 c +2538 3350 2530 3393 2511 3448 c +2500 3481 2452 3494 2421 3478 c +2291 3413 2194 3370 2064 3305 c +2034 3289 2015 3267 2004 3236 c +1988 3194 2014 3153 2048 3124 c +2053 3119 2059 3111 2065 3115 c +2075 3120 2082 3124 2092 3130 c +2102 3135 2116 3133 2121 3123 c +2134 3092 2150 3073 2169 3046 c +2174 3040 2177 3030 2171 3026 c +2144 3007 2124 2995 2097 2977 c +2081 2966 2072 2948 2074 2928 c +2078 2872 2082 2830 2101 2778 c +2125 2717 2157 2677 2203 2631 c +2210 2624 2219 2620 2228 2623 c +2254 2631 2274 2637 2300 2646 c +2307 2648 2315 2644 2318 2638 c +2330 2616 2332 2597 2339 2574 c +2340 2568 2336 2562 2330 2558 c +2303 2539 2280 2531 2251 2515 c +2240 2509 2234 2497 2237 2484 c +2293 2264 2369 2102 2522 1934 c +2640 1804 2769 1740 2940 1699 c +3122 1655 3264 1689 3451 1705 c +3631 1720 3776 1743 3942 1673 c +4083 1613 4148 1508 4263 1408 c +4485 1215 4706 1090 5000 1090 c +closepath 0 setgray fill } def + +/sym9 { 5000 1502 m +4722 1503 4558 1710 4353 1898 c +4199 2039 4042 2129 3833 2132 c +3632 2136 3486 2109 3286 2101 c +3149 2096 3040 2122 2923 2194 c +2745 2303 2674 2468 2599 2664 c +2500 2600 2426 2557 2324 2497 c +2385 2294 2456 2143 2606 1994 c +2761 1838 2945 1768 3165 1777 c +3357 1784 3497 1797 3689 1807 c +3873 1817 4023 1758 4161 1638 c +4301 1516 4393 1411 4554 1319 c +4703 1234 4828 1178 5000 1177 c +closepath 1 setgray fill +2660 2661 m +2695 2563 2727 2492 2784 2405 c +2798 2413 2808 2420 2822 2430 c +2771 2508 2758 2578 2721 2663 c +2712 2683 2692 2706 2671 2697 c +2658 2692 2655 2674 2660 2661 c +closepath 1 setgray fill +2608 2857 m +2597 2853 2589 2851 2577 2847 c +2586 2839 2592 2833 2602 2826 c +2606 2837 2606 2846 2608 2857 c +closepath 1 setgray fill +2390 2680 m +2403 2655 2407 2634 2412 2607 c +2482 2651 2535 2679 2607 2721 c +2633 2736 2659 2747 2688 2739 c +2726 2728 2751 2702 2766 2665 c +2795 2595 2806 2539 2845 2474 c +2853 2460 2869 2447 2883 2454 c +2901 2463 2894 2490 2885 2508 c +2851 2572 2813 2612 2784 2679 c +2758 2740 2752 2789 2729 2851 c +2722 2870 2709 2890 2689 2888 c +2670 2887 2663 2864 2662 2845 c +2660 2803 2625 2773 2586 2757 c +2514 2728 2462 2707 2390 2680 c +closepath 1 setgray fill +2481 3136 m +2479 3113 2479 3094 2486 3072 c +2500 3078 2510 3082 2524 3088 c +2512 3108 2500 3121 2481 3136 c +closepath 1 setgray fill } def +/syma { +2429 3113 m +2333 3058 2261 3021 2166 2965 c +2173 2856 2202 2775 2261 2684 c +2368 2725 2447 2754 2553 2799 c +2482 2901 2455 2992 2429 3113 c +closepath 1 setgray fill +2472 3422 m +2469 3434 2457 3445 2445 3441 c +2434 3436 2427 3423 2430 3411 c +2438 3381 2452 3362 2471 3338 c +2373 3280 2300 3241 2200 3186 c +2219 3144 2234 3114 2259 3077 c +2326 3114 2374 3141 2441 3178 c +2466 3191 2497 3200 2518 3182 c +2549 3156 2567 3134 2593 3105 c +2600 3136 2599 3166 2579 3190 c +2552 3224 2532 3250 2514 3289 c +2493 3336 2484 3372 2472 3422 c +closepath 1 setgray fill +2380 3392 m +2379 3400 2368 3406 2361 3402 c +2269 3354 2202 3321 2112 3270 c +2093 3260 2096 3233 2102 3212 c +2103 3210 2105 3206 2107 3208 c +2210 3264 2288 3301 2391 3358 c +2386 3370 2383 3380 2380 3392 c +closepath 1 setgray fill } def +/symb_colour { +% cross in 'azure' blue +blue_colour +5000 2313 m +4955 2385 4880 2430 4730 2470 c +4670 2490 l +4670 3220 l +3430 3220 l +3392 3344 l +3431 3350 3458 3359 3495 3371 c +3490 3425 3475 3465 3415 3578 c +3530 3685 3500 3805 3490 3813 c +4670 3813 l +4670 4582 l +5000 4582 l +closepath fill +% Chief Gules +red_colour +5000 4582 m +3675 4582 l +3673 4730 3650 4830 3573 4935 c +3573 5041 l +3596 5023 3630 4992 3667 4942 c +3740 5075 3732 5205 3670 5295 c +3713 5352 3745 5410 3780 5495 c +3692 5468 3608 5445 3533 5440 c +4026 5680 l +4040 5593 4125 5530 4250 5530 c +4310 5530 4415 5580 4453 5616 c +4514 5658 4607 5693 4661 5699 c +4823 5717 4930 5780 5000 5890 c +closepath fill +% and now some lines around the cross, and at the base of the lion field +0 setgray +16 setlinewidth +3675 4582 m 5000 4582 l stroke +3490 3813 m 4670 3813 l 4670 4582 l stroke +3430 3220 m 4670 3220 l 4670 2490 l stroke +} def +/book_clasp { +2 copy +gold_colour +m +50 0 rlineto +0 50 rlineto +-50 0 rlineto +closepath fill +2 copy +0 setgray +m +50 0 rlineto +stroke +m +0 50 rmoveto +50 0 rlineto +stroke +} def +/sym_book { +% Book outline +% First fill the outline +1 setgray +5000 3742 m +4856 3798 4755 3804 4671 3700 c +4671 3325 l +5329 3325 l +5329 3700 l +5245 3804 5144 3798 5000 3742 c +closepath fill +% along the base of the book colour it gold +gold_colour +5329 3315 m +5227 3420 5114 3413 5000 3363 c +4886 3413 4773 3420 4671 3315 c +closepath fill +% Clasps for the book +% Firstly colour the clasps gold +gold_colour +8 setlinewidth +4671 3355 m +4611 3355 l +4611 3700 l +4671 3700 l +closepath +gsave +fill +grestore +0 setgray +stroke +% and strokes on the clasp holder +3412 58 3644 { dup 4611 exch m 4671 exch l stroke } for +4671 3300 m 4671 3700 l stroke +% Now do the three book clasps +5329 3400 book_clasp +5329 3500 book_clasp +5329 3600 book_clasp +% then actually draw the book in black +16 setlinewidth +0 setgray +5000 3742 m +5000 3363 l +4886 3413 4773 3420 4671 3315 c +4671 3700 l +4755 3804 4856 3798 5000 3742 c +closepath stroke +5329 3700 m +5245 3804 5144 3798 5000 3742 c +5000 3363 l +5114 3413 5227 3420 5329 3315 c +5329 3700 l +closepath stroke +5337 3300 m +4663 3300 l +stroke +% Stroke along the spine of the book +5000 3300 m +5000 3742 l +stroke +% Line to the sides of the book +22 setlinewidth +4716 3360 m +4716 3750 l +stroke +5284 3360 m +5284 3750 l +stroke +0 setgray +% finally some fine text lines on the book +4 setlinewidth +3470 60 3710 { dup dup dup dup dup dup dup + 4766 exch m 4840 exch l stroke + 5234 exch m 5160 exch l stroke + 4877 exch m 4953 exch l stroke + 5123 exch m 5047 exch l stroke + } for +} def +/symb_mono { +0 setgray 30 setlinewidth +% bottom most horizontal stroke +4860 2400 m 5000 2400 l stroke +% Horizontal strokes to base of book +2500 100 3200 { dup 4670 exch m 5000 exch l stroke } for +% strokes to the sides of the book +3300 100 3700 { dup 3400 exch m 5000 exch l stroke } for +% horiz strokes above the book +3800 100 4500 { dup 4670 exch m 5000 exch l stroke } for +% Vertical strokes to the top of the figure +3614 5450 m 3614 5520 l stroke +5060 5580 5620 5680 5720 5590 5570 5580 5620 5690 5720 5740 5770 5860 5950 +5000 -99 3614 { dup 4620 m exch l stroke } for +% bottom dark horizontal line for cross +84 setlinewidth 3400 3220 m 4696 3220 l stroke +% Top dark horizontal line for cross +56 setlinewidth 3460 3813 m 4696 3813 l stroke +% Bottom dark line for vertical strokes +92 setlinewidth 3650 4582 m 5000 4582 l stroke +} def + +/sym { sym1 sym2 sym3 sym4 sym5 sym6 sym7 sym8 sym9 syma + colour 0 ne + { symb_colour } + { symb_mono } + ifelse +} def + +% Draw the main body of the crest.. +0 setlinecap +5000 0 translate -1 1 scale -5000 0 translate sym +5000 0 translate -1 1 scale -5000 0 translate sym +sym_book +colour 0 eq +{ + % draw the dark & light edges for the cross + 30 setlinewidth + 4681 3813 m 4681 4582 l stroke + 4681 3220 m 4681 2400 l stroke + 84 setlinewidth + 5346 3813 m 5346 4582 l stroke + 5346 3220 m 5346 2400 l stroke +} if + +/star { +-41 -82 rlineto +-112 42 rlineto +39 -90 rlineto +-85 -52 rlineto +87 -48 rlineto +-28 -86 rlineto +93 33 rlineto +45 -89 rlineto +44 83 rlineto +90 -28 rlineto +-27 106 rlineto +75 45 rlineto +-77 42 rlineto +28 82 rlineto +-90 -24 rlineto +-41 66 rlineto closepath } def +% Draw the lion in black +0 setlinewidth +5863 4715 m +5825 4660 5740 4655 5695 4700 c +5660 4670 5608 4670 5582 4700 c +5553 4730 5555 4780 5588 4800 c +5554 4852 5576 4902 5655 4895 c +5668 4893 5678 4900 5678 4910 c +5678 4970 l +5607 4971 5546 4980 5481 5020 c +5481 4875 l +5363 4930 5323 4890 5364 4810 c +5267 4842 5240 4830 5245 4735 c +5174 4810 5112 4773 5146 4703 c +5115 4655 5055 4640 5021 4678 c +4972 4677 4934 4694 4923 4723 c +4910 4757 4917 4798 4955 4822 c +4932 4850 4952 4875 4983 4896 c +5012 4918 5050 4911 5077 4892 c +5190 4970 l +5127 5061 l +5010 4973 4928 4950 4870 4962 c +4845 4910 4795 4875 4733 4858 c +4659 4942 4610 4932 4602 4804 c +4520 4855 4483 4842 4460 4757 c +4422 4782 4393 4781 4367 4760 c +4378 4710 4357 4672 4326 4659 c +4285 4648 4240 4655 4223 4697 c +4167 4693 4137 4720 4115 4752 c +4112 4790 4130 4828 4183 4840 c +4183 4875 4192 4901 4222 4920 c +4248 4939 4272 4930 4313 4904 c +4315 4980 4272 5010 4225 4994 c +4233 5040 4231 5070 4195 5080 c +4149 5060 4095 5062 4075 5090 c +4050 5112 4045 5159 4074 5193 c +4047 5238 4050 5270 4075 5301 c +4108 5338 4162 5330 4196 5298 c +4232 5320 4262 5315 4287 5285 c +4304 5262 4312 5220 4275 5181 c +4387 5072 l +4430 5095 l +4408 5132 4395 5145 4395 5175 c +4375 5193 4355 5219 4347 5251 c +4302 5293 4300 5330 4335 5367 c +4283 5422 4314 5485 4393 5483 c +4407 5531 4465 5552 4506 5530 c +4545 5561 4615 5562 4655 5530 c +4716 5543 4762 5522 4770 5472 c +4835 5490 4855 5422 4813 5372 c +4844 5313 l +4960 5313 l +4865 5422 4870 5514 5015 5575 c +5035 5631 5067 5658 5114 5700 c +5128 5713 5153 5702 5151 5672 c +5150 5617 l +5195 5656 5240 5660 5258 5628 c +5267 5611 5259 5586 5204 5530 c +5220 5511 5227 5470 5207 5423 c +5255 5442 5300 5467 5334 5485 c +5473 5565 5652 5553 5728 5450 c +5771 5382 5770 5338 5708 5272 c +5673 5245 5674 5200 5702 5173 c +5745 5131 5802 5110 5865 5093 c +5810 5033 5813 5010 5866 4968 c +5795 4925 5795 4898 5863 4850 c +5786 4791 5783 4760 5863 4715 c +5539 5324 m +5565 5327 5589 5328 5607 5348 c +5620 5363 5615 5388 5601 5403 c +5586 5421 5562 5419 5539 5418 c +5470 5406 5386 5372 5332 5324 c +5539 5324 l +closepath 0 setgray fill +% We firstly fix problems, +% The hole in the tail +red_colour +5091 5462 m +5083 5471 5073 5475 5062 5475 c +5050 5475 5040 5471 5032 5462 c +5023 5454 5019 5444 5019 5433 c +5019 5421 5023 5411 5032 5403 c +5040 5394 5050 5390 5062 5390 c +5073 5390 5083 5394 5091 5403 c +5100 5411 5104 5421 5104 5433 c +5104 5444 5100 5454 5091 5462 c +closepath fill +% Inside of right fore paw +4294 5212 m +4287 5200 4282 5191 4274 5180 c +4280 5173 4287 5171 4294 5164 c +4294 5182 4295 5195 4294 5212 c +closepath fill +% Rest of the right fore paw +4328 5261 m +4328 5212 4328 5176 4328 5127 c +4347 5110 4360 5098 4379 5080 c +4386 5074 4401 5084 4400 5094 c +4400 5120 4396 5138 4396 5164 c +4395 5179 4386 5190 4375 5200 c +4354 5219 4354 5250 4328 5261 c +closepath fill +% and now in the rest in gold +gold_colour +% crotch +5300 5162 m +5326 5166 5354 5166 5371 5145 c +5344 5139 5321 5146 5300 5162 c +% Right hind leg +closepath fill +5316 4855 m +5271 4863 5221 4835 5211 4791 c +5188 4803 5166 4806 5141 4798 c +5107 4787 5107 4741 5109 4704 c +5096 4692 5085 4679 5067 4680 c +5044 4682 5030 4709 5033 4731 c +5034 4740 5010 4743 5009 4734 c +5007 4723 4998 4712 4987 4713 c +4962 4716 4939 4737 4939 4762 c +4939 4784 4964 4797 4986 4797 c +4995 4797 5003 4816 4995 4821 c +4979 4831 4973 4859 4987 4872 c +5010 4893 5051 4883 5071 4860 c +5123 4892 5160 4917 5211 4950 c +5221 4956 5224 4970 5218 4979 c +5200 5007 5187 5027 5171 5056 c +5162 5072 5157 5096 5173 5104 c +5207 5121 5231 5135 5264 5152 c +5299 5125 5338 5112 5382 5120 c +5405 5088 5425 5067 5451 5037 c +5450 4993 5449 4961 5449 4916 c +5416 4926 5386 4940 5356 4924 c +5330 4910 5318 4884 5316 4855 c +closepath fill +% Chest +4631 5190 m +4627 5148 4616 5095 4575 5091 c +4535 5087 4514 5140 4511 5180 c +4491 5152 4467 5122 4481 5091 c +4494 5062 4515 5048 4537 5025 c +4580 5046 4612 5060 4653 5085 c +4673 5097 4681 5120 4680 5144 c +4679 5168 4651 5175 4631 5190 c +closepath fill +% Main Body +4306 4871 m +4291 4896 4249 4908 4229 4888 c +4212 4871 4212 4841 4227 4824 c +4224 4819 4220 4817 4217 4812 c +4195 4813 4169 4805 4166 4784 c +4163 4765 4171 4745 4188 4737 c +4207 4728 4229 4738 4243 4753 c +4249 4748 4255 4746 4261 4742 c +4255 4722 4259 4695 4278 4688 c +4297 4682 4319 4681 4332 4696 c +4346 4713 4336 4734 4330 4755 c +4328 4762 4327 4769 4332 4775 c +4358 4805 4401 4817 4438 4801 c +4464 4849 4526 4868 4577 4851 c +4579 4891 4612 4926 4652 4932 c +4687 4936 4722 4923 4740 4892 c +4781 4908 4812 4928 4835 4965 c +4843 4977 4841 4989 4839 5002 c +4835 5027 4826 5043 4815 5065 c +4810 5074 4836 5085 4841 5076 c +4856 5048 4864 5026 4873 4996 c +4939 4998 4995 5004 5047 5045 c +5138 5116 5212 5185 5328 5191 c +5357 5192 5384 5181 5399 5156 c +5462 5050 5572 5010 5694 4995 c +5703 4994 5707 4984 5707 4975 c +5707 4912 5707 4866 5707 4802 c +5697 4802 5689 4802 5678 4801 c +5677 4822 5674 4837 5672 4858 c +5669 4883 5613 4876 5605 4853 c +5597 4833 5615 4813 5633 4800 c +5631 4793 5628 4787 5626 4780 c +5610 4780 5592 4778 5587 4764 c +5581 4748 5584 4729 5598 4719 c +5613 4708 5630 4703 5649 4709 c +5668 4714 5679 4728 5690 4745 c +5698 4744 5703 4743 5711 4742 c +5718 4710 5767 4698 5797 4712 c +5769 4752 5770 4807 5801 4845 c +5773 4874 5770 4922 5794 4954 c +5772 4992 5773 5033 5791 5072 c +5745 5094 5709 5112 5675 5150 c +5643 5186 5635 5231 5647 5277 c +5688 5310 5718 5357 5707 5410 c +5691 5483 5604 5514 5529 5511 c +5385 5505 5298 5418 5159 5379 c +5109 5365 5062 5347 5019 5374 c +4997 5388 4981 5409 4982 5436 c +4983 5465 5003 5488 5030 5500 c +5052 5510 5077 5511 5097 5497 c +5118 5482 5125 5460 5127 5435 c +5128 5423 5147 5413 5157 5419 c +5175 5430 5187 5447 5185 5468 c +5182 5495 5172 5513 5161 5537 c +5187 5554 5199 5574 5217 5599 c +5222 5606 5204 5619 5198 5613 c +5175 5593 5153 5586 5128 5568 c +5122 5563 5107 5568 5107 5576 c +5110 5608 5110 5631 5109 5663 c +5072 5629 5045 5590 5050 5541 c +4992 5542 4922 5509 4919 5451 c +4916 5384 4969 5341 5021 5300 c +4954 5296 4904 5297 4836 5293 c +4833 5276 4821 5264 4806 5256 c +4798 5223 4777 5202 4749 5185 c +4742 5157 4725 5138 4701 5122 c +4694 5093 4682 5069 4657 5054 c +4531 4981 4435 4936 4306 4871 c +5207 5299 l +5319 5353 5395 5408 5515 5439 c +5555 5450 5594 5453 5625 5426 c +5643 5411 5654 5391 5650 5368 c +5645 5330 5611 5298 5573 5297 c +5207 5299 l +closepath fill +% Mane below Left Ear +4774 5350 m +4765 5338 4761 5328 4755 5315 c +4770 5303 4780 5293 4793 5279 c +4800 5284 4804 5289 4810 5295 c +4805 5296 4802 5296 4798 5296 c +4798 5307 4798 5315 4797 5325 c +4796 5338 4783 5342 4774 5350 c +closepath fill +% Mane below Right Ear +4378 5312 m +4368 5324 4365 5337 4362 5352 c +4344 5342 4322 5328 4326 5308 c +4328 5296 4333 5287 4342 5278 c +4354 5292 4362 5302 4378 5312 c +closepath fill +% Mane below left Eye +4690 5230 m +4683 5217 4674 5209 4661 5200 c +4677 5187 4687 5177 4700 5161 c +4713 5173 4735 5196 4720 5207 c +4709 5216 4701 5222 4690 5230 c +closepath fill +% Mane below right Eye +4483 5195 m +4466 5201 4452 5207 4443 5221 c +4420 5208 4398 5174 4416 5155 c +4425 5145 4432 5139 4442 5131 c +4454 5156 4465 5173 4483 5195 c +closepath fill +% Face +4426 5435 m +4418 5454 4400 5481 4417 5491 c +4440 5505 4461 5512 4487 5509 c +4496 5508 4505 5506 4510 5498 c +4521 5479 4526 5464 4536 5444 c +4545 5445 4552 5447 4561 5447 c +4556 5473 4519 5512 4545 5518 c +4571 5524 4606 5536 4619 5512 c +4632 5489 4639 5471 4645 5445 c +4655 5447 4662 5447 4673 5448 c +4669 5471 4658 5508 4681 5511 c +4701 5514 4721 5508 4733 5493 c +4744 5479 4724 5463 4711 5452 c +4717 5445 4722 5440 4729 5433 c +4752 5447 4788 5465 4803 5441 c +4818 5417 4783 5392 4758 5378 c +4754 5375 4750 5372 4747 5367 c +4739 5350 4733 5338 4724 5321 c +4721 5315 4723 5307 4729 5303 c +4747 5289 4758 5276 4777 5262 c +4769 5246 4759 5235 4743 5228 c +4725 5241 4711 5250 4693 5263 c +4693 5269 4694 5273 4694 5278 c +4685 5278 4679 5279 4670 5278 c +4671 5247 4642 5218 4610 5218 c +4597 5218 4585 5226 4581 5239 c +4575 5260 4600 5274 4620 5283 c +4632 5288 4643 5297 4643 5310 c +4643 5325 4644 5336 4643 5350 c +4643 5357 4648 5363 4654 5366 c +4668 5373 4678 5377 4692 5384 c +4690 5393 4689 5400 4687 5410 c +4665 5402 4650 5396 4629 5387 c +4622 5385 4616 5379 4616 5371 c +4615 5351 4611 5336 4612 5315 c +4613 5307 4605 5300 4597 5300 c +4575 5299 4560 5301 4539 5301 c +4529 5301 4524 5312 4523 5322 c +4521 5339 4520 5351 4519 5369 c +4518 5376 4516 5384 4509 5386 c +4486 5397 4470 5405 4446 5414 c +4443 5405 4440 5399 4437 5390 c +4458 5382 4472 5371 4492 5361 c +4494 5340 4494 5325 4496 5304 c +4498 5288 4516 5279 4533 5278 c +4545 5277 4551 5262 4551 5249 c +4551 5235 4541 5217 4526 5218 c +4509 5220 4496 5219 4478 5222 c +4456 5227 4461 5258 4459 5281 c +4450 5281 4443 5281 4434 5281 c +4435 5257 4423 5236 4402 5223 c +4388 5214 4371 5235 4366 5251 c +4360 5273 4387 5291 4409 5295 c +4410 5301 4411 5305 4412 5311 c +4394 5328 4388 5350 4388 5375 c +4361 5387 4321 5414 4338 5437 c +4355 5460 4391 5441 4414 5425 c +4418 5428 4421 5432 4426 5435 c +closepath fill +% Tongue +4564 5204 m +4556 5198 4549 5194 4540 5192 c +4543 5167 4546 5129 4571 5130 c +4597 5130 4596 5170 4595 5195 c +4583 5197 4574 5198 4564 5204 c +closepath fill +% Right Fore Paw +4458 5072 m +4429 5058 4408 5049 4379 5036 c +4324 5086 4286 5124 4232 5174 c +4255 5202 4277 5248 4249 5271 c +4228 5288 4201 5264 4179 5248 c +4158 5270 4127 5298 4103 5280 c +4075 5260 4096 5216 4115 5188 c +4094 5177 4077 5154 4084 5131 c +4093 5101 4137 5086 4166 5100 c +4186 5110 4208 5111 4227 5099 c +4248 5084 4250 5059 4253 5034 c +4304 5041 4346 4983 4351 4931 c +4408 4961 4450 4983 4506 5014 c +4487 5034 4471 5048 4458 5072 c +closepath fill +% Draw the stars (outline in black) +0 setgray 60 setlinewidth +3943 3714 m star stroke +6077 3714 m star stroke +5010 2943 m star stroke +5010 4379 m star stroke +% and fill in gold +gold_colour +3928 3725 m star fill +6062 3725 m star fill +4995 2958 m star fill +4995 4394 m star fill + +0 setgray +%%IncludeResource: font Times-Bold + +/Times-Bold findfont [ 342 0 0 250 0 0 ] makefont setfont newpath + +2430 2395 m +2460 2278 2514 2220 2555 2180 c +2576 2140 2613 2090 2662 2053 c +2730 1993 2812 1925 2910 1893 c +2987 1870 3115 1851 3207 1855 c +3290 1860 3400 1860 3495 1870 c +3760 1890 3990 1834 4135 1732 c +4195 1690 4273 1615 4320 1565 c +4368 1513 4517 1435 4547 1390 c +4666 1320 4847 1250 5000 1250 c +5153 1250 5334 1320 5453 1390 c +5483 1435 5632 1513 5680 1565 c +5727 1615 5805 1690 5865 1732 c +6010 1834 6240 1890 6505 1870 c +6600 1860 6710 1860 6793 1855 c +6885 1851 7013 1870 7090 1893 c +7188 1925 7270 1993 7338 2053 c +7387 2090 7424 2140 7445 2180 c +7486 2220 7540 2278 7570 2395 c +(SIDERE\264MENS\264EADEM\264MUTATO) 0 30 pathtext +grestore +showpage +%%Trailer diff --git a/doc/user/tbl b/doc/user/tbl new file mode 100644 index 0000000..230c69e --- /dev/null +++ b/doc/user/tbl @@ -0,0 +1,48 @@ +@Chapter + @Title { Tables } + @Tag { tables } +@Begin +@LP +This chapter explains how to produce tables like this one: +tables. @Index { tables } +@CD @Tbl + aindent { ctr } + arulebelow { double } + aformat { @StartHSpan @Cell @B X | | @HSpan } + bformat { @Cell rr { no } @I A | @Cell rl { no } B | @Cell C } + rule { yes } +{ +@Rowa + X { Value of mathematical formulae (millions of dollars) } +@Rowb + A { Quadratic formula } + B { @Eq { x ^= { minus b +- sqrt { b sup 2 - 4ac } } over 2a } } + C { 3^.5 } +@Rowb + A { Binomial theorem } + B { @Eq { ( a + b ) sup n ^= big sum from k=0 to infty +matrix atleft { ( } atright { ) } { n above k } a sup k b sup n-k +} } + C { 12^ } +} +As the example shows, the tables may contain spanning columns, aligned +columns, and rules, and the cells may contain arbitrary objects. +@BeginSections + +@Include { tbl_intr } # introduction +@Include { tbl_cell } # basic cell formatting: font, break, width, paint +@Include { tbl_rows } # row formats and the @Row symbol +@Include { tbl_marg } # margins +@Include { tbl_widt } # width and height +@Include { tbl_inde } # indenting and struts +@Include { tbl_rule } # rules +@Include { tbl_span } # spanning columns and rows +@Include { tbl_mult } # multi-page tables +@Include { tbl_alig } # aligned columns and headings over them +@Include { tbl_mark } # @MarkRow +@Include { tbl_plai } # plain text tables +@Include { tbl_setu } # setup file options +@Include { tbl_summ } # summary + +@EndSections +@End @Chapter diff --git a/doc/user/tbl_alig b/doc/user/tbl_alig new file mode 100644 index 0000000..24b6864 --- /dev/null +++ b/doc/user/tbl_alig @@ -0,0 +1,96 @@ +@Section + @Title { Aligned columns } + @Tag { tbl_alig } +@Begin +@PP +Columns of numbers are often presented with decimal points aligned: +aligned.columns @Index { aligned columns in tables } +@CD @OneRow @Tbl + marginvertical { 0.5vx } + aformat { @Cell A } +{ +@Rowa A { 5^.46 } marginabove { 0i } +@Rowa A { 3^.4159 } +@Rowa A { 5772^ } marginbelow { 0i } +} +You can produce this by placing a @Code "^" symbol, which is used +generally throughout Lout for alignment, just before the alignment point in +each entry: +@ID @OneRow @Code @Verbatim { +@Tbl + marginvertical { 0.5vx } + aformat { @Cell A } +{ +@Rowa A { 5^.46 } +@Rowa A { 3^.4159 } +@Rowa A { 5772^ } +} +} +The equals signs of equations can be aligned in the same way (see the +example at the start of this chapter). Aligned cells should have no +@Code indent option. +@PP +Owing to problems behind the scenes, getting a heading over the top +of an aligned column is a problem with no ideal solution. What most +people want is for the heading to be centred in the column, and the +aligned entries to be centred in the column as a block, but Lout cannot +do this. One approximation is to make the heading cell a spanning +cell with centring, like this: +@FootNote { Lout does not currently accept single-column tables +with {@Code "@StartHSpan"}, so we've had to add +an empty second column. } +@ID @OneRow @Code @Verbatim { +@Tbl + marginvertical { 0.5vx } + aformat { @StartHSpan @Cell indent { ctr } @B A | } + bformat { @Cell A | } +{ +@Rowa A { Heading } +@Rowb A { 5^.46 } +@Rowb A { 3^.4159 } +@Rowb A { 5772^ } +} +} +The spanning frees the heading from alignment, permitting +@Code "indent { ctr }" to work: +@CD @OneRow @Tbl + marginvertical { 0.5vx } + aformat { @StartHSpan @Cell indent { ctr } @B A | } + bformat { @Cell A | } +{ +@Rowa A { Heading } marginabove { 0i } +@Rowb A { 5^.46 } +@Rowb A { 3^.4159 } +@Rowb A { 5772^ } marginbelow { 0i } +} +But if the heading cell is wider than the aligned cells, you get this: +@CD @OneRow @Tbl + marginvertical { 0.5vx } + aformat { @StartHSpan @Cell indent { ctr } @B A | } + bformat { @Cell A | } +{ +@Rowa A { A Wider Heading } marginabove { 0i } +@Rowb A { 5^.46 } +@Rowb A { 3^.4159 } +@Rowb A { 5772^ } marginbelow { 0i } +} +In other words, this will centre a heading with respect +to aligned entries, but it will not centre aligned entries with +respect to a heading. In these cases you could forget about +@Code "@StartHSpan" and treat the heading as an aligned entry, +either by placing a @Code "^" within it or by using +@ID @Code "@Cell 0.5w @HShift A" +which places the alignment point in the centre of the entry. +#@CD @OneRow @Tbl +# marginvertical { 0.5vx } +# aformat { @Cell 0.5w @HShift @B A } +# bformat { @Cell A } +#{ +#@Rowa A { A Wider Heading } marginabove { 0i } +#@Rowb A { 5^.46 } +#@Rowb A { 3^.4159 } +#@Rowb A { 5772^ } marginbelow { 0i } +#} +You can move the alignment point about by changing the 0.5. Of course, +all this is a poor substitute for the real thing. +@End @Section diff --git a/doc/user/tbl_cell b/doc/user/tbl_cell new file mode 100644 index 0000000..159372e --- /dev/null +++ b/doc/user/tbl_cell @@ -0,0 +1,97 @@ +@Section + @Title { Changing the appearance of cells } + @Tag { tbl_cell } +@Begin +@PP +The @Code "@Cell" symbol offers a few options for changing the appearance +cell.option @Index { cell options 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 { +@Tbl + aformat { @Cell paint { lightgrey } font { Italic } break { clines } A } +{ +@Rowa A { +IMPORTANT +Do not throw stones at this notice +} +} +} +The result here is +@CD +@Tbl + aformat { @Cell paint { lightgrey } font { Italic } break { clines } A | @Cell B } +{ +@Rowa A { +IMPORTANT +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. +@PP +Later sections introduce other @Code "@Cell" options, for +fixed-width columns, indented entries, margins, and rules. It is also +possible to combine other symbols from Lout with cell formatting, by +placing them between the @Code "@Cell" symbol and its following letter, +rotated.entries @Index { rotated entries in tables } +like this: +@ID @OneRow @Code @Verbatim { +@Tbl + aformat { @Cell 90d @Rotate @S A | @Cell @B grey @Colour B } +{ +@Rowa + A { Col A } + B { Col B } +} +} +Think of the @Code "A" as standing for the value of the @Code "A" +option of the @Code "@Rowa" symbol (which it does), and you'll see +that this is just Lout's usual rule of symbols applying to the +object that follows them. The result here is +@CD @Tbl + aformat { @Cell 90d @Rotate @S A | @Cell @B grey @Colour B } +{ +@Rowa + A { Col A } + B { Col B } +} +In simple cases @Code "@B" is easier than {@Code "font { Bold }"}; +the latter is useful as a default value, as we will see in a moment. +Note the difference between a coloured background, obtained with +{@Code "paint"}, and a coloured entry, obtained using the @Code "@Colour" +symbol. +@PP +@Code "@Tbl" offers many places where you can set cell options. The meaning +of the option is the same wherever you set it; +what changes is the extent of its application. Taking the @Code "paint" +option as a representative example, the most specific place to set it +is at a @Code "@Cell" symbol as above; then it affects only that cell +in rows formatted using that format. Alternatively, +@ID @OneRow @Code @Verbatim { +@Tbl + apaint { lightgrey } + aformat { @Cell A | @Cell B } +} +will paint every cell in the {@Code "aformat"}. And +@ID @OneRow @Code @Verbatim { +@Rowa + paint { lightgrey } + A { ... } +} +will paint every cell in a particular row. To paint the entire table, use +@ID @OneRow @Code @Verbatim { +@Tbl + paint { lightgrey } +} +And finally, there is a @Code "paint" option in the +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 +precise description, see Section {@NumberOf tbl_summ}. +@End @Section diff --git a/doc/user/tbl_inde b/doc/user/tbl_inde new file mode 100644 index 0000000..75a3471 --- /dev/null +++ b/doc/user/tbl_inde @@ -0,0 +1,58 @@ +@Section + @Title { Indenting and struts } + @Tag { tbl_inde } +@Begin +@PP +By default, entries appear at the left within cells, not counting the +cell margin. The @Code indent option causes entries to be indented +horizontally. For example, +@ID @OneRow @Code "@Cell indent { ctr }" +horizontally centres the entry within the cell. The other possible values +centred.entries @Index { centred entries in tables } +right.justified.entries @Index { right justified entries in tables } +of this option are {@Code "left"}, {@Code "right"}, or any length (for +example, {@Code 2f}) meaning that much indent. +@PP +There is a corresponding @Code "indentvertical" option for vertical indenting +within the cell. It takes the same values except that @Code "left" is +renamed {@Code "top"}, and @Code "right" is renamed {@Code foot}. +A common problem with vertical placement is that words that lack +ascenders (parts of letters that rise up) or descenders (parts that +sink down) can easily become misaligned with words that +don't. Looking at +@CD @Tbl + aformat { @Cell A | @Cell B | @Cell C } + marginvertical { 0i } +{ +@Rowa + A { resume } + B { poppy } + C { title } +} +which is the result of +@ID @OneRow @Code @Verbatim { +@Tbl + aformat { @Cell A | @Cell B | @Cell C } +{ +@Rowa + A { resume } + B { poppy } + C { title } +} +} +we see that the words are aligned correctly despite the absence of +ascenders from the first two words, and of descenders from the first +and last; and this despite the fact that these words are vertically +placed at the top of the cell. 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 +ascenders and descenders. The option +@ID @OneRow @Code "@Cell strut { no }" +can be used to remove the strut; other acceptable values for this +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 +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 new file mode 100644 index 0000000..a46da18 --- /dev/null +++ b/doc/user/tbl_intr @@ -0,0 +1,119 @@ +@Section + @Title { Getting started } + @Tag { tbl_intr } +@Begin +@PP +The Lout definitions for table formatting +@FootNote { +The @Code "tbl" package described here replaces the @Code "tab" +package of Version 3.12 and earlier. For backward compatibility +the @Code "tab" package is still available and still works as +described in older versions of this documentation. Users of +@Code "tab" will find simple uses of @Code "tbl" to be very similar, +replacing @Code "@Tab" by {@Code "@Tbl"}, @Code "@Fmta" by +{@Code "aformat"}, @Code "@Col" by {@Code "@Cell"}, and +@Code "!" by {@Code "|"}. +} +are kept in a file called {@Code "tbl"}, which you must include at +the start of your document if +tbl.file @Index { @Code "tbl" file } +you want tables, like this: +@ID @OneRow @Code { +"@SysInclude { tbl }" +"@SysInclude { doc }" +"@Doc @Text @Begin" +"..." +"@End @Text" +} +Specialized setup files, like {@Code "tbl"}, are included before the main +setup file (@Code "doc" in this case). Alternatively, if you are using +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" +@CD +@Tbl + aformat { @Cell A | @Cell B | @Cell C } +{ +@Rowa + A { Austen } + B { Chaucer } + C { Donne } +@Rowa + A { Balzac } + B { Darwin } + C { Goethe } +@Rowa + A { Byron } + B { Dickens } + C { Homer } +} +is produced by the following input: +@ID @OneRow @Code { +"@Tbl" +" aformat { @Cell A | @Cell B | @Cell C }" +"{" +"@Rowa" +" A { Austen }" +" B { Chaucer }" +" C { Donne }" +"@Rowa" +" A { Balzac }" +" B { Darwin }" +" C { Goethe }" +"@Rowa" +" A { Byron }" +" B { Dickens }" +" C { Homer }" +"}" +} +Immediately after the @Code "@Tbl" symbol, which introduces the table, +comes a @I { format option }, {@Code "aformat"}, describing the format of +each row. It says that each row contains three cells: {@Code "@Cell A"}, +{@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. +@PP +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 +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 +may be omitted altogether if it is empty. Lout will choose suitable widths +for the cells, and break paragraphs in the entries to the right widths. +@PP +The result of the @Code "@Tbl" symbol is an object. As usual with +Lout, this object may appear at any point in the document, +@FootNote { +In rare cases, when the table occupies an entire paragraph but is not +displayed, a bug in the current version of Basser Lout causes the second +column to appear much too far to the right. Until the problem is fixed, +the first thing to try if this occurs is to replace the very first +row symbol ({@Code "@Rowa"}, {@Code "@Rowb"}, etc.) by {@Code "@FirstRowa"}, +{@Code "@FirstRowb"}, etc. +# That should work, but if it doesn't, replacing +# @Code "@Tbl" by @Code "@OneCol @Tbl" certainly will, although it also +# prevents the table from breaking across page boundaries. +} +even within a paragraph or another table. Most commonly, though, tables +are displayed using the @Code "@IndentedDisplay" and @Code "@CentredDisplay" +symbols (Section {@NumberOf displays}): +@ID @Code "@CentredDisplay @Tbl ..." +or else they go into the @Code "@Table" symbol (Section {@NumberOf figures}): +@ID @OneRow @Code { +"@Table" +" @Caption { ... }" +"@Tbl ..." +} +which centres them at the top of the following page and adds a +caption. Note the difference between {@Code "@Tbl"}, which builds a +table, and {@Code "@Table"}, which places an arbitrary object in an +appropriate place. It's important to remember that the result +is an object like any other, because from time to time one wants such +things as rotated tables whose entire contents are to be italicised: +@ID @Code "90d @Rotate @I @Tbl ..." +and it helps to remember that the full power of Lout can be +brought to bear on the @I entire table. +@End @Section diff --git a/doc/user/tbl_marg b/doc/user/tbl_marg new file mode 100644 index 0000000..89e63cd --- /dev/null +++ b/doc/user/tbl_marg @@ -0,0 +1,74 @@ +@Section + @Title { Margins } + @Tag { tbl_marg } +@Begin +@PP +The @Code "@Cell" symbol offers a @Code margin option for changing the +margins @RawIndex { margins } +margins.in.tables @SubIndex { margins 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, +which brings us to the @Code marginhorizontal and @Code marginvertical +options: +@ID @OneRow @Code @Verbatim { +@Cell + marginhorizontal { 0.6f } + marginvertical { 0.3f } +} +These are the default values, 0.6 and 0.3 times the current font size +respectively. Another useful value is {@Code "marginvertical { 0.5vx }"}, +which asks for a vertical margin of half the current line separation, but +measured from baseline to baseline (this is what the @Code "x" means). +This produces a separation equal to the separation of the surrounding lines: +@CD @Tbl + marginvertical { 0.5vx } + aformat { @Cell A | @Cell B | @Cell C } +{ +@Rowa + A { Austen } + B { Chaucer } + C { Donne } +@Rowa + A { Balzac } + B { Darwin } + C { Goethe } +@Rowa + A { Byron } + B { Dickens } + C { Homer } +} +This margin does not work so well when the cells contain paragraphs, +diagrams or other things that could not be described as single lines. +@PP +There are {@Code "marginabove"}, {@Code "marginbelow"}, {@Code "marginleft"}, +and {@Code "marginright"} options for setting margins individually. For +example, sometimes you don't want the extreme left and right margins in +a table, and they can be got rid of like this: +@ID @OneRow @Code @Verbatim { +@Tbl + paint { lightgrey } + aformat { @Cell ml { 0i } A | @Cell B | @Cell mr { 0i } C } +{ +@Rowa + A { Column A } + B { Column B } + C { Column C } +} +} +We've used abbreviated versions of the options' names: @Code "ml" for +{@Code marginleft}, and @Code "mr" for {@Code marginright}. Every option +has such an abbreviated name, made from the first letters of the parts of +its full name (Section {@NumberOf tbl_summ} lists all these names). The +result is +@CD @Tbl + paint { lightgrey } + aformat { @Cell ml { 0i } A | @Cell B | @Cell mr { 0i } C } +{ +@Rowa + A { Column A } + B { Column B } + C { Column C } +} +with the painting showing the reduced margins. +@End @Section diff --git a/doc/user/tbl_mark b/doc/user/tbl_mark new file mode 100644 index 0000000..8761979 --- /dev/null +++ b/doc/user/tbl_mark @@ -0,0 +1,65 @@ +@Section + @Title { Vertical alignment of tables } + @Tag { tbl_mark } +@Begin +@PP +Occasionally the vertical alignment of a table with objects to its left +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 produces +#@ID @OneRow @Code @Verbatim { +#@Tbl +# aformat { @Cell A } +# margin { 0i } +# strut { no } +#{ +#@Rowa A { @OpenCircle } +#@Rowa A { @ClosedCircle } +#@Rowa A { @OpenCircle } +#} +#} +#where @Code "@OpenCircle" and @Code "@ClosedCircle" produce open and +#closed circles (they may be defined using the @Code "@Diag" package); +#but this produces +@Tbl + aformat { @Cell A } + margin { 0i } + strut { no } +{ +@Rowa A { @OpenCircle } +@Rowa A { @ClosedCircle } +@Rowa A { @OpenCircle } +} +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 +@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 { +import @TblSetup +def @AmberLight +{ + @OneRow @Tbl + aformat { @Cell A } + margin { 0i } + strut { no } + paint { no } rule { no } + { + @Rowa A { @OpenCircle } + @MarkRowa A { @ClosedCircle } + @Rowa A { @OpenCircle } + } +} +} +Now when we write +@ID @Code "produces @AmberLight in running text" +we find that this definition produces @AmberLight in running text, as +desired. We have enclosed the table in @Code "@OneRow" to ensure that +its rows will never become separated, and added some options just in +case the definition is ever used with a setup file (Section +{@NumberOf tbl_setu}) that has default painting or rules. +@End @Section diff --git a/doc/user/tbl_mult b/doc/user/tbl_mult new file mode 100644 index 0000000..84ce363 --- /dev/null +++ b/doc/user/tbl_mult @@ -0,0 +1,57 @@ +@Section + @Title { Multi-page tables } + @Tag { tbl_mult } +@Begin +@PP +The tables produced by @Code "@Tbl" permit page breaks (including breaking +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 } +rows. +@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 +to break simpler displays. (A display symbol will scale a very high table +to fit on one page, and it will go wrong on a table containing +{@Code "@NP"}.) Multi-page tables can go inside @Code "@Figure" or +@Code "@Table" symbols, because these symbols have been set up to accept +multi-page objects. Or they can go into the body text of the document +at full width with a paragraph symbol before and after, like this: +@ID @Code @Verbatim { +@DP +@Tbl ... +@DP +} +An example of this kind of multi-page table appears in +Section {@NumberOf tbl_summ}. You can simulate an indent by means of an +empty cell at the left of each row format, although in the author's opinion +a multi-page table looks better at full width anyway. Lout will expand the +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 +The simplest way to get rules right in multi-page tables 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. +@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 +have just said 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). +@End @Section diff --git a/doc/user/tbl_plai b/doc/user/tbl_plai new file mode 100644 index 0000000..0813717 --- /dev/null +++ b/doc/user/tbl_plai @@ -0,0 +1,84 @@ +@Section + @Title { Plain text tables } + @Tag { tbl_plai } +@Begin +@PP +Tables work well with plain text output (Section {@NumberOf plain}): +plain.text.tables @Index { plain text tables } +@CD @OneRow -1px @Break @F @Verbatim { +................................................... +. . . +. Johnson . Johnson suddenly uttered an . +. suddenly . apophegm, at which many will . +. uttered an . start: `Patriotism is the . +. apophegm, at . last refuge of a scoundrel.' . +. which many . . +. will start: . . +. `Patriotism ................................. +. is the last . . . +. refuge of a . Johnson . Johnson . +. scoundrel.' . suddenly . suddenly . +. . uttered an . uttered an . +. . apophegm, at . apophegm, at . +. . which many . which many . +. . will start: . will start: . +. . `Patriotism . `Patriotism . +. . is the last . is the last . +. . refuge of a . refuge of a . +. . scoundrel.' . scoundrel.' . +. . . . +. . . . +................................... . +. . . +. Johnson suddenly uttered an . . +. apophegm, at which many will . . +. start: `Patriotism is the . . +. last refuge of a scoundrel.' . . +. . . +. . . +................................................... +} +This table was produced by a separate run of Lout and pasted into this +document. +@PP +@Code "@Tbl" changes the default values of several options when used +in a plain text document: +@ID @Code @Verbatim { +@Tbl + marginvertical { 2f } + marginhorizontal { 2s } + rulehorizontalwidth { 1f } + ruleverticalwidth { 1s } + rulehorizontalgap { 0f } + ruleverticalgap { 0s } +} +When using plain text it is advisable to make vertical distances whole +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 +draw rules. For example, +@ID @Code @Verbatim { +@Tbl + ruleplainchar { - } +} +would be a good choice if you plan to draw only horizontal rules. This +option can be set anywhere as usual. +@PP +If you do use rules it is worth pondering the implications of the last +part of Section {@NumberOf tbl_rule}. Right and below rules are drawn +outside the boundary of the cell, which is unimportant +in ordinary output, but means that they will appear one space to the +right and one line below the cell in plain text output. This explains +the slight asymmetry in the example above; you can correct it with +@ID @Code @Verbatim { +@Tbl + marginright { 1s } + marginbelow { 1f } +} +but you still have to worry about rules at the extreme right of the +page going off the edge, and rules below the last line bumping into +whatever follows the table. The first can be fixed by not using +full width tables with right rules; the second by inserting an extra +@Code "@DP" after a table that ends with a below rule. +@End @Section diff --git a/doc/user/tbl_rows b/doc/user/tbl_rows new file mode 100644 index 0000000..7d26b75 --- /dev/null +++ b/doc/user/tbl_rows @@ -0,0 +1,59 @@ +@Section + @Title { Changing the appearance of rows } + @Tag { tbl_rows } +@Begin +@PP +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 of these row format options: {@Code aformat}, +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"}, +and so on up to {@Code "@Rowh"}: +@ID @OneRow @Code @Verbatim { +@Tbl + aformat { @Cell @I A | @Cell @I B } + bformat { @Cell A | @Cell B } +{ +@Rowa + A { Name } + B { Nationality } +@Rowb + A { Austen } + B { English } +@Rowb + A { Balzac } + B { French } +} +} +The result of this is +@CD @OneRow @Tbl + aformat { @Cell @I A | @Cell @I B } + bformat { @Cell A | @Cell B } +{ +@Rowa + A { Name } + B { Nationality } +@Rowb + A { Austen } + B { English } +@Rowb + A { Balzac } + B { French } +} +The first row, being a {@Code "@Rowa"}, is formatted using +{@Code aformat}; the others, being {@Code "@Rowb"} symbols, are +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 +@Code "@Row" symbol like this: +@ID @OneRow @Code @Verbatim { +@Row + format { @Cell @B A | @Cell paint { lightgrey } B } + A { ... } + B { ... } +} +All formats must contain the same number of cells, otherwise the table +will not be rectangular. +@End @Section diff --git a/doc/user/tbl_rule b/doc/user/tbl_rule new file mode 100644 index 0000000..383ffab --- /dev/null +++ b/doc/user/tbl_rule @@ -0,0 +1,192 @@ +@Section + @Title { Rules } + @Tag { tbl_rule } +@Begin +@PP +There is a @Code "rule" option for drawing a rule around a cell: +@ID @OneRow @Code "@Cell rule { yes }" +The other possible values are {@Code no} (the default), +{@Code single} (the same as {@Code yes}), and {@Code double}, which +draws a double rule. +@PP +There are @Code "rulehorizontal" and @Code "rulevertical" options which +draw only horizontal or vertical rules, and also {@Code "ruleabove"}, +{@Code "rulebelow"}, {@Code "ruleleft"}, and {@Code "ruleright"} options: +@ID @OneRow @Code @Verbatim { +@Tbl + aformat { @Cell A | @Cell B } +{ +@Rowa + ruleabove { yes } + A { Commercial property } + B { 10% } +@Rowa + A { Stock market } + B { 15% } + rulebelow { yes } +} +} +produces +@CD @OneRow @Tbl + aformat { @Cell A | @Cell B } +{ +@Rowa + ruleabove { yes } + A { Commercial property } + B { 10% } +@Rowa + A { Stock market } + B { 15% } + rulebelow { yes } +} +These options take the same values as {@Code "rule"}, but draw +along only one or two of the four edges. +@PP +Other options control the appearance of rules. Here they are with their +default values: +@ID @OneRow @Code @Verbatim { +@Tbl + rulewidth { 0.05f } + rulegap { 0.15f } + rulecolour { black } +} +These say that rules are to be @Code "0.05f" wide (thick), double rules +are to appear @Code "0.15f" apart, and the colour of rules is to be black. +Once again, more specific versions of these symbols exist for controlling +above, below, left, and right rules: +@ID @OneRow @Code @Tbl + aformat { @Cell ml { 0i } A | @Cell B | @Cell C } + marginvertical { 0.5vx } +{ +@Rowa + A { rulehorizontalwidth } + B { rulehorizontalgap } + C { rulehorizontalcolour } +@Rowa + A { ruleabovewidth } + B { ruleabovegap } + C { ruleabovecolour } +@Rowa + A { rulebelowwidth } + B { rulebelowgap } + C { rulebelowcolour } +@Rowa + A { ruleverticalwidth } + B { ruleverticalgap } + C { ruleverticalcolour } +@Rowa + A { ruleleftwidth } + B { ruleleftgap } + C { ruleleftcolour } +@Rowa + A { rulerightwidth } + B { rulerightgap } + C { rulerightcolour } +} +As usual, all these options have abbreviated names; and @Code { colour } +may be spelt @Code { color } wherever it appears. Section +{@NumberOf tbl_summ} has a complete summary of all spellings of all +options. +@PP +To clarify exactly where the rules are drawn, let's start with +a cell with no rules at all: +@CD @Tbl + aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A } +{ +@Rowa +} +Above rules and left rules are drawn within the cell boundary, just +touching it, with any above rule overstriking any left rule: +@CD { @Tbl + aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A } +{ +@Rowa +} +@Background @Tbl + aformat { @Cell width { 3c } height { 1.5c } A } + ruleleft { yes } + ruleabove { yes } + rulehorizontalwidth { 0.8v } + ruleverticalwidth { 0.5v } + ruleverticalcolour { grey } + rulehorizontalcolour { black } +{ +@Rowa +} +} +Below and right rules are drawn just outside the boundary of the +cell, also touching it: +@CD @Tbl aformat { @Cell A | @Cell | @Cell B } +{ +@Rowa + A { + @Tbl + aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A } + { + @Rowa + } + @Background + @Tbl + aformat { @Cell width { 3c } height { 1.5c } A } + rulebelow { yes } + rulehorizontalwidth { 0.8v } + ruleverticalwidth { 0.5v } + ruleverticalcolour { grey } + rulehorizontalcolour { black } + { + @Rowa + } + } + B { + @Tbl + aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A } + { + @Rowa + } + @Background + @Tbl + aformat { @Cell width { 3c } height { 1.5c } A } + ruleright { yes } + rulehorizontalwidth { 0.8v } + ruleverticalwidth { 0.5v } + ruleverticalcolour { grey } + rulehorizontalcolour { black } + { + @Rowa + } + } +} +@DP +When a right rule is present, any above and below rules are extended +by the width of the right rule, and they overstrike it: +@CD { +@Tbl + aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A } +{ +@Rowa +} +@Background +@Tbl + aformat { @Cell width { 3c } height { 1.5c } A } + ruleabove { yes } + ruleright { yes } + rulebelow { yes } + rulehorizontalwidth { 0.8v } + ruleverticalwidth { 0.5v } + ruleverticalcolour { grey } + rulehorizontalcolour { black } +{ +@Rowa +} +} +@DP +(These diagrams were produced by @Code "@Tbl" itself, using horizontal +rules of width @Code 0.8v drawn in black, and vertical rules of width +@Code 0.5v drawn in grey.) These arrangements ensure that even thick +rules produce clean corners, and also that a right rule and a neighbouring +left rule exactly overstrike each other, as do a below rule and its +neighbouring above rule. +@PP +For information about rules in plain text tables, consult Section +{@NumberOf tbl_plai}. +@End @Section diff --git a/doc/user/tbl_setu b/doc/user/tbl_setu new file mode 100644 index 0000000..74bdb9a --- /dev/null +++ b/doc/user/tbl_setu @@ -0,0 +1,65 @@ +@Section + @Title { Changing the overall format } + @Tag { tbl_setu } +@Begin +@PP +All of the options apart from the @Code format options can be changed +setup.files.tables @Index { setup files 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 +lot of time, but its more important purposes are to promote consistency +and to allow document-wide formatting changes to be carried out easily. +@PP +The first step is to obtain your own copy of the setup file, @Code { tbl }, +from the Lout system include directory. You can find out where that +is by typing +@ID @Code { lout -V } +This prints out various things about Lout. Supposing that it says +that the Lout system include directory is @Code { "/usr/lout/include" }, for +example, you can copy the setup file into your current directory, +renaming it @Code { mytbl }, with the Unix command +@ID @Code "cp /usr/lout/include/tbl mytbl" +or its equivalent on your system. You will also need to make +@Code { mytbl } writable. +@PP +The next step is to replace the @Code "@SysInclude { tbl }" line at the +start of your document with @Code { "@Include { mytbl }" }. This causes +Lout to read your copy of the setup file, not the one in the system +include directory. Since the two files are currently identical, this +has changed nothing so far, but now you can change the options within +@Code mytbl and the changes will affect your document. +@PP +Your copy of the setup file has some lines beginning with @Code "#" +that are ignored by Lout, and then it has @Code { "@SysInclude { tblf }" }. +This line tells Lout to read file @Code tblf which contains the definition +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 } + # font { } + # break { } +} +} +Only a few of the options are shown here. To change a setup file +option, delete the @Code "#" in front of it and change the value. For +example, suppose you want all table entries two points smaller than the +surrounding text: +@ID @OneRow @Code @Verbatim { +@Use { @TblSetup + # paint { nopaint } + font { -2p } + # break { } +} +} +This relative specification of font size is available anywhere, not +just in setup files (Section {@NumberOf fonts}). +@PP +Some setup file options contain values which use the @Code "@OrIfPlain" +symbol: +@ID @Code "marginvertical { 0.3f @OrIfPlain 1f }" +This means that the value of @Code marginvertical is to be @Code "0.3f" +usually, but @Code 1f in plain text documents. Feel free to leave these +symbols there when you change a value, or delete them if you prefer. +@End @Section diff --git a/doc/user/tbl_span b/doc/user/tbl_span new file mode 100644 index 0000000..5621961 --- /dev/null +++ b/doc/user/tbl_span @@ -0,0 +1,195 @@ +@Section + @Title { Spanning columns and rows } + @Tag { tbl_span } +@Begin +@PP +To make a cell span across several columns, precede the @Code "@Cell" +spanning.columns @Index { spanning columns and rows in tables } +symbol with @Code "@StartHSpan" and replace each spanned cell's +@Code "@Cell" symbol with {@Code "@HSpan"}, like this: +@ID @OneRow @Code @Verbatim { +@Tbl + rule { yes } + aformat { @StartHSpan @Cell indent { ctr } @B A | @HSpan | @HSpan } + bformat { @Cell A | @Cell B | @Cell C } +{ +@Rowa + A { Some famous authors } +@Rowb + A { Austen } + B { Chaucer } + C { Donne } +@Rowb + A { Balzac } + B { Darwin } + C { Goethe } +} +} +The result of this is +@CD @OneRow @Tbl + rule { yes } + aformat { @StartHSpan @Cell indent { ctr } @B A | @HSpan | @HSpan } + bformat { @Cell A | @Cell B | @Cell C } +{ +@Rowa + A { Some famous authors } +@Rowb + A { Austen } + B { Chaucer } + C { Donne } +@Rowb + A { Balzac } + B { Darwin } + C { Goethe } +} +We've used a sample of options to show how naturally these go with +spanning cells: they apply to the whole cell as usual, whatever +its extent. It is quite acceptable to span just some of the columns, +not all of them; indeed, there may be no @Code "@HSpan" symbols at +all, and then the cell just spans its own column, which sounds redundant +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 +{@Code "@VSpan"}: +@ID @OneRow @Code @Verbatim { +@Tbl + rule { yes } + aformat { @StartVSpan @Cell @I A | @Cell B | @Cell C } + bformat { @VSpan | @Cell B | @Cell C } +{ +@Rowa + A { Mathematics } + B { MATH 1001 } + C { Differential Calculus } +@Rowb + B { MATH 1002 } + C { Linear Algebra } +@Rowa + A { Computer Science } + B { COMP 1001 } + C { Introductory Programming } +@Rowb + B { COMP 1002 } + C { Introductory Computer Science } +} +} +The result of this is +@CD @OneRow @Tbl + rule { yes } + aformat { @StartVSpan @Cell @I A | @Cell B | @Cell C } + bformat { @VSpan | @Cell B | @Cell C } +{ +@Rowa + A { Mathematics } + B { MATH 1001 } + C { Differential Calculus } +@Rowb + B { MATH 1002 } + C { Linear Algebra } +@Rowa + A { Computer Science } + B { COMP 1001 } + C { Introductory Programming } +@Rowb + B { COMP 1002 } + C { Introductory Computer Science } +} +Here is a notorious larger example, the `spiral': +@ID @OneRow @Code @Verbatim { +@QuotedDisplay @Tbl + rule { yes } +{ +@Row + format { @StartVSpan @Cell A | @StartHSpan @Cell B | @HSpan } + A { @SomeText } + B { @SomeText } +@Row + format { @VSpan | @Cell B | @StartVSpan @Cell C } + B { @SomeText } + C { @SomeText } +@Row + format { @StartHSpan @Cell A | @HSpan | @VSpan } + A { @SomeText } +} +} +The @Code "@SomeText" symbol produces a short paragraph of text. The +result is +@QD @Tbl + rule { yes } +{ +@Row format { @StartVSpan @Cell A | @StartHSpan @Cell B | @HSpan } + A { @SomeText } + B { @SomeText } +@Row format { @VSpan | @Cell B | @StartVSpan @Cell C } + B { @SomeText } + C { @SomeText } +@Row format { @StartHSpan @Cell A | @HSpan | @VSpan } + A { @SomeText } +} +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. +@PP +There is a @Code "@StartHVSpan" symbol which combines the effects +of @Code "@StartHSpan" and {@Code "@StartVSpan"}. You need to +use it in this arrangement: +@ID @OneRow @Tbl + mv { 0.5vx } + aformat { @Cell @Code A | @Cell @Code B | @Cell @Code C } +{ +@Rowa + A { "@StartHVSpan" } + B { "@HSpan" } + C { "@HSpan" } +@Rowa + A { "@VSpan" } +@Rowa + A { "@VSpan" } +} +The blank positions should be left empty. For example: +@ID @OneRow @Code @Verbatim { +@Tbl + rule { yes } + aformat { @Cell A | @Cell B | @Cell C | @Cell D } + bformat { @Cell A | @StartHVSpan @Cell i { ctr } iv { ctr } B | @HSpan | @Cell D } + cformat { @Cell A | @VSpan | | @Cell D } +{ +@Rowa +@Rowb + B { CPU } +@Rowc +@Rowa +} +} +produces +@CD @OneRow @Tbl + rule { yes } + strut { no } + aformat { @Cell A | @Cell B | @Cell C | @Cell D } + bformat { @Cell A | @StartHVSpan @Cell i { ctr } iv { ctr } B | @HSpan | @Cell D } + cformat { @Cell A | @VSpan | | @Cell D } +{ +@Rowa +@Rowb + B { CPU } +@Rowc +@Rowa +} +This example illustrates how Lout apportions space in the presence of +spanning columns. If the spanning cell is naturally narrower than the +cells it spans, it is widened to their size. If it is wider (as in +the example above), then the last spanned cell is widened to take +up the slack. This is why the third cell is wider than the second in the +first row of this example. +@End @Section diff --git a/doc/user/tbl_summ b/doc/user/tbl_summ new file mode 100644 index 0000000..6fed734 --- /dev/null +++ b/doc/user/tbl_summ @@ -0,0 +1,255 @@ +@Section + @Title { Summary of options } + @Tag { tbl_summ } +@Begin +@PP +This summary applies to all @Code "@Tbl" options except the @Code format +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 +file, and allowed range of values. Where one option is indented below +another, it means that the indented option is a specialized version of +the other, which affects its default value. For more on this see below. +@DP +@Tbl + marginvertical { 0.5vx } + aformat { @Cell ml { 0i } @Code A | + @Cell @Code B | @Cell @Code C | @Cell mr { 0i } D } + bformat { @Cell ml { 0i } indent { 1f } @Code A | + @Cell @Code B | @Cell @Code C | @Cell mr { 0i } D } + cformat { @Cell ml { 0i } indent { 2f } @Code A | + @Cell @Code B | @Cell @Code C | @Cell mr { 0i } D } + dfont { Italic } + dbreak { lines } + dformat { @Cell ml { 0i } A | @Cell B | @Cell C | @Cell mr { 0i } D } + fformat { @StartHSpan @Cell ml { 0i } @Code A | + @HSpan | @HSpan | @Cell mr { 0i } D } + gformat { @StartHSpan @Cell ml { 0i } indent { 1f } @Code A | + @HSpan | @HSpan | @Cell mr { 0i } D } + hformat { @StartHSpan @Cell ml { 0i } indent { 2f } @Code A | + @HSpan | @HSpan | @Cell mr { 0i } D } +{ +@Rowd + A { Option names } + B { Default in +PS, PDF } + C { Default in +plain text } + D { Allowed values } + rulebelow { yes } +@Rowa + A { paint p } + B { nopaint } + D { any colour from Section {@NumberOf colour} } +@Rowa + A { background bg } + D { any object } +@Rowa + A { font f } + D { any font e.g. @Code "Helvetica Slope -2p" } +@Rowa + A { break b } + D { any break e.g. @Code "ragged nohyphen" } +@Rowa + A { width w } + D { @Code "expand" or any length e.g. @Code 5c } +@Rowa + A { height h } + D { any length e.g. @Code 3c } +@Rowa + A { indent i } + D { {@Code left}, {@Code ctr}, {@Code mctr}, {@Code right}, or any length } +@Rowa + A { indentvertical iv } + D { {@Code top}, {@Code ctr}, {@Code mctr}, {@Code foot}, or any length } +@Rowa + A { strut s } + B { yes } + C { yes } + D { {@Code no}, {@Code yes}, or any length } +@Rowa + A { struthorizontal sh } + B { no } + C { no } + D { {@Code no}, {@Code yes}, or any length } +@Rowa +@Rowa + A { margin m } + B { } + C { } + D { any length } +@Rowb + A { marginhorizontal mh } + B { 0.6f } + C { 2s } + D { any length } +@Rowc + A { marginleft ml } + D { any length } +@Rowc + A { marginright mr } + D { any length } +@Rowb + A { marginvertical mv } + B { 0.3f } + C { 2f } + D { any length } +@Rowc + A { marginabove ma } + D { any length } +@Rowc + A { marginbelow mb } + D { any length } +@Rowa +@Rowa + A { rule r } + B { no } + C { no } + D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} } +@Rowb + A { rulehorizontal rh } + D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} } +@Rowc + A { ruleabove ra } + D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} } +@Rowc + A { rulebelow rb } + D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} } +@Rowb + A { rulevertical rv } + D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} } +@Rowc + A { ruleleft rl } + D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} } +@Rowc + A { ruleright rr } + D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} } +@Rowa +@Rowa + A { rulewidth rw } + B { 0.05f } + D { any length } +@Rowb + A { rulehorizontalwidth rhw } + C { 1f } + D { any length } +@Rowc + A { ruleabovewidth raw } + D { any length } +@Rowc + A { rulebelowwidth rbw } + D { any length } +@Rowb + A { ruleverticalwidth rvw } + C { 1s } + D { any length } +@Rowc + A { ruleleftwidth rlw } + D { any length } +@Rowc + A { rulerightwidth rrw } + D { any length } +@Rowa +@Rowa + A { rulegap rg } + B { 0.15f } + D { any length } +@Rowb + A { rulehorizontalgap rhg } + C { 0f } + D { any length } +@Rowc + A { ruleabovegap rag } + D { any length } +@Rowc + A { rulebelowgap rbg } + D { any length } +@Rowb + A { ruleverticalgap rvg } + C { 0s } + D { any length } +@Rowc + A { ruleleftgap rlg } + D { any length } +@Rowc + A { rulerightgap rrg } + D { any length } +@Rowa +@Rowa + A { rulecolour rulecolor rc } + B { black } + D { any colour from Section {@NumberOf colour} } +@Rowg + A { rulehorizontalcolour rulehorizontalcolor rhc } + D { any colour from Section {@NumberOf colour} } +@Rowh + A { ruleabovecolour ruleabovecolor rac } + D { any colour from Section {@NumberOf colour} } +@Rowh + A { rulebelowcolour rulebelowcolor rbc } + D { any colour from Section {@NumberOf colour} } +@Rowg + A { ruleverticalcolour ruleverticalcolor rvc } + D { any colour from Section {@NumberOf colour} } +@Rowh + A { ruleleftcolour ruleleftcolor rlc } + D { any colour from Section {@NumberOf colour} } +@Rowh + A { rulerightcolour rulerightcolor rrc } + D { any colour from Section {@NumberOf colour} } +@Rowa +@Rowa + A { ruleplainchar rpc } + C { . } + D { any simple word e.g. @Code + } + rulebelow { yes } +} +@DP +There are seven places where these options may be given, counting the +setup file (Section {@NumberOf tbl_setu}). To make it clear that this +summary applies to any of these options, we illustrate the seven places +with a fictitious option called {@Code option}: +@ID @OneRow @Code @Verbatim { +@Use { @TblSetup + option { 1 } +} + +@Tbl + option { 2 } + aoption { 3 } + aformat { @Cell option { 4 } A } +{ + @Rowa + option { 5 } + @Row + option { 6 } + format { @Cell option { 7 } A } +} +} +Each occurrence of @Code option is of course optional. If there are +none, the default value given in the table above applies. For any other +combination of absent and present options, the value that applies is the +present and relevant one with the largest number in the illustration +just above. But before applying this rule, any general options must be +thought of as being replaced by their more specialized versions: +@ID @Code "rulehorizontal { yes }" +is equivalent to +@ID @Code @Verbatim { +ruleabove { yes } +rulebelow { yes } +} +for example. Conflicts are resolved in the logical way: +@ID @Code @Verbatim { +margin { 0.5f } +marginleft { 0.0f } +} +is equivalent to the four specialized options +@ID @Code @Verbatim { +marginabove { 0.5f } +marginbelow { 0.5f } +marginleft { 0.0f } +marginright { 0.5f } +} +General options are really just abbreviations for sets of specialized +options. +@End @Section diff --git a/doc/user/tbl_widt b/doc/user/tbl_widt new file mode 100644 index 0000000..b2e39ad --- /dev/null +++ b/doc/user/tbl_widt @@ -0,0 +1,84 @@ +@Section + @Title { Cell width and height } + @Tag { tbl_widt } +@Begin +@PP +Lout is quite good a choosing suitable widths for cells. It leaves +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: +@QD @OneRow @Tbl + aformat { @Cell @I A | @Cell B | @Cell C } +{ +@Rowa + A { Acacia } + B { +Shrub or small tree with grey-green foliage and brilliant +yellow blossom in late winter. +} + C { +Distributed widely throughout Australia except in the most arid +parts; many varieties. +} +} +This usually looks good, but if you need something else, the @Code width +option may be used to give a particular width to a cell: +@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 +a table wide enough to require paragraph breaking, it is best to use +@Code width to make cells narrower, not wider. +@PP +Regrettably, there is no way to request that several cells in a row be +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 +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 { +@QuotedDisplay @Tbl + width { expand } + paint { lightgrey } + aformat { @Cell A | @Cell B | @Cell C } +{ +@Rowa + A { 23.56 } + B { 98.76 } + C { 65.00 } +} +} +has result +@QuotedDisplay @Tbl + width { expand } + paint { lightgrey } + aformat { @Cell A | @Cell B | @Cell C } +{ +@Rowa + A { 23.56 } + B { 98.76 } + C { 65.00 } +} +We have used our usual trick of making the option apply to several cells +by moving it to a more general level, in this case to {@Code "@Tbl"}. +The available space can be reduced using the @Code "@Wide" symbol; if +we replace @Code "@QuotedDisplay @Tbl" in the example above with +@ID @OneRow @Code "@CentredDisplay 4i @Wide @Tbl" +the result will be +@CentredDisplay 4i @Wide @Tbl + width { expand } + paint { lightgrey } + aformat { @Cell A | @Cell B | @Cell C } +{ +@Rowa + A { 23.56 } + B { 98.76 } + C { 65.00 } +} +with the total table width reduced to four inches. +@PP +There is an analogous @Code height option which makes a cell take on +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. +@End @Section diff --git a/doc/user/typ b/doc/user/typ new file mode 100644 index 0000000..7ebe52f --- /dev/null +++ b/doc/user/typ @@ -0,0 +1,27 @@ +@Chapter + @Title { Types of Documents } + @Tag { types } +@Begin +@LP +Particular types of documents have specialized formatting requirements: +title pages in books, abstracts in technical reports, and so on. Lout +provides a range of @I { document types } with the appropriate +specialized features for +document.types @Index { document types } +each type. +@PP +There are five types: ordinary documents, technical reports, +books, overhead transparencies, and stand-alone illustrations. The +features of all other chapters are available within each document type, +but the features of one type are not available within other types. +@BeginSections +@Include { typ_ordi } +@Include { typ_repo } +@Include { typ_book } +@Include { typ_over } +@Include { typ_illu } +@Include { typ_plai } +@Include { typ_apdf } +@Include { typ_orga } +@EndSections +@End @Chapter diff --git a/doc/user/typ_apdf b/doc/user/typ_apdf new file mode 100644 index 0000000..3203384 --- /dev/null +++ b/doc/user/typ_apdf @@ -0,0 +1,21 @@ +@Section + @Title { PDF (Adobe Portable Document Format) documents } + @Tag { pdf } +@Begin +@PP +You can get Lout to produce PDF (Adobe Portable Document Format) output as +an alternative to PostScript, by adding @Code "-PDF" to the command line +like this: +pdf. @Index { PDF documents } +@ID @Code "lout -PDF simple > simple.pdf" +No other changes are required. +@PP +The PDF output is superior to PostScript in providing links: when viewed +with a PDF viewer, entries in tables of contents and indexes can be +clicked on and this transports the viewer to the part of the document +referenced by the link. (Recent versions of PostScript support this +feature too, but Lout's PostScript doesn't.) However, the PDF output +produced by Lout is inferior at graphics: the advanced features of the +@Code "@Diag" and @Code "@Graph" packages do not produce any output. One +can still format documents that contain them, but the results are disappointing. +@End @Section diff --git a/doc/user/typ_book b/doc/user/typ_book new file mode 100644 index 0000000..34abde2 --- /dev/null +++ b/doc/user/typ_book @@ -0,0 +1,420 @@ +@Section + @Title { Books } + @Tag { books } +@Begin +@PP +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 { +"@SysInclude { book }" +"@Book" +" @Title {}" +" @Author {}" +" @Edition {}" +" @Publisher {}" +" @BeforeTitlePage {}" +" @OnTitlePage {}" +" @AfterTitlePage {}" +" @AtEnd {}" +" @InitialFont { Times Base 12p }" +" @InitialBreak { adjust 1.2fx hyphen }" +" @InitialSpace { lout }" +" @InitialLanguage { English }" +" @PageOrientation { Portrait }" +" @PageHeaders { Titles }" +" @ColumnNumber { 1 }" +" @FirstPageNumber { 1 }" +" @IntroFirstPageNumber { 1 }" +" @OptimizePages { No }" +"//" +} +This shows all the options of @Code "@Book" with their default values. As +usual, these options may be given in any order, and only those +to be changed need be given at all. The meaning of the +@Code "//" symbol after the last option is beyond our scope, but total +disaster will ensue if it is forgotten. +@PP +The {@Code "@Title"}, {@Code "@Author"}, and {@Code "@Edition"} options +will appear on the title page, in the @Code "clines" paragraph breaking +style which centres each line (Section {@NumberOf paras}). The +@Code "@Publisher" option will appear at the foot of the title page. +@PP +The {@Code "@BeforeTitlePage"} option will come out on the page (or +pages) preceding the title page. This is where publishers +advertise other books of a similar kind, perhaps from a series. +@PP +If {@Code "@OnTitlePage"} is given it will replace the title page +that usually appears, superseding the {@Code "@Title"}, {@Code "@Author"}, +{@Code "@Edition"}, and @Code "@Publisher" options in the process. +@PP +The {@Code "@AfterTitlePage"} option will come out on the page +(or pages) following the title page. This is where publishers +traditionally put copyright notices, information about production, +and cataloguing-in-publication data. If this option is empty or +omitted, there will be no such pages. +@PP +The {@Code "@AtEnd"} option will come out on a single unnumbered page +with no page headers or footers, and using the same margins as for even +pages, after the very last page of the book; even after the index if +there is one. It is intended to make it possible to include a back +cover, so @Code "@PageOf last.page" (Section {@NumberOf cross}) does +not take account of any @Code "@AtEnd" page. +@PP +The remaining options are a selection of setup file options (Section +{@NumberOf setup}) that frequently need to be changed. If your changes +to the overall formatting are confined to these options, you can change +them here and avoid having your own setup file. If you already have +your own setup file, change them in either place and omit them in +the other. +@PP +@Code "@InitialFont" is the font of the bulk of the book, +and should contain a family, a face, and a size. The default +value selects the Times family, the Base face, and the 12 point size. +@PP +@Code "@InitialBreak" controls the behaviour of paragraph breaking in +the bulk of the book. It should have three parts: a paragraph +breaking style ({@Code adjust}, {@Code ragged}, etc.), an inter-line +spacing ({@Code "1.2fx"} for single spacing, {@Code "2.4fx"} for +double spacing, and so on), and either @Code "hyphen" or +@Code "nohyphen" for turning hyphenation on or off. It may also +have @Code "nobreakfirst" or @Code "nobreaklast" (or both), meaning +to disallow a page break after the first line of a paragraph, or +before the last, respectively. +@PP +@Code "@InitialSpace" determines how Lout treats white space +between two objects, as described in Section +{@NumberOf white}. @Code "@InitialLanguage" determines the +language of the bulk of the book. +@PP +@Code "@PageOrientation" determines the orientation of the page. Its +value may be {@Code Portrait} (the default), {@Code Landscape}, +{@Code ReversePortrait}, or {@Code ReverseLandscape}. See +Section {@NumberOf pagesize} for further details. +@PP +@Code "@PageHeaders" determines the appearance of page headers and +footers. Its value may be {@Code None}, +{@Code Simple}, {@Code Titles}, or {@Code NoTitles}. Section +{@NumberOf headers} has the details, but just briefly, {@Code None} +and {@Code Simple} are not really suitable for books, @Code Titles +produces full running titles as in the present document, and +@Code "NoTitles" is like @Code "Titles" with the running titles +omitted, leaving just the page numbers. +@PP +@Code "@ColumnNumber" is the number of columns per page in the bulk of +the book, and may be anything from {@Code 1} (the default value) to +{@Code 10}. Irrespective of its value, all prefatory material, all +chapter and appendix headings, and all figures and tables will be +printed full width. There is a separate @Code "@IndexColumnNumber" +option in the setup file which determines the number of columns in +the index (Section {@NumberOf indexes}). +@PP +@Code "@FirstPageNumber" is the page number to be given to the first +non-introductory page. @Code "@IntroFirstPageNumber" is the +page number of the first introductory page; it will usually appear +in Roman but must be given in Arabic. +@PP +Lout ordinarily places lines onto a page until space runs out, then moves +to the next page and so on. This often produces ugly empty spaces at +the bottoms of pages preceding large unbreakable displays. Setting the +@Code "@OptimizePages" option to {@Code "Yes"} causes Lout to examine the +overall situation and try to minimize the ugliness, using the @TeX +optimal paragraph breaking algorithm. It takes two runs to do this, +with intermediate results stored in Lout's cross reference database +(Section {@NumberOf cross}); so deleting file {@Code lout.li} will reset +it, which might be wise after major changes. It is possible for the +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 +After the compulsory @Code "//" comes an optional preface: +preface. @Index @Code "@Preface" +@ID @OneRow @Code { +"@Preface" +" @Title { About this book }" +"@Begin" +"@PP" +"..." +"@End @Preface" +} +Since the title of most prefaces is simply Preface, that is the default +value in English of the @Code "@Title" option. After the preface there +will automatically appear a table of contents listing the introduction, +chapters, sections, subsections, appendices, sub-appendices, bibliography, +and index as appropriate. +@PP +The pages up to this point will be numbered in lower case Roman +numerals; subsequent pages will be numbered in Arabic starting from +the @Code "@FirstPageNumber" option of {@Code "@Book"}. There is +a setup file option for changing this to a single numbering sequence +(see below). +@PP +Next comes an optional abbreviations sections, exactly like the +preface except that its name is @Code "@Abbreviations" and the +abbreviations. @Index @Code "@Abbreviations" +default title in English is Abbreviation. There is no support for +what goes inside; you need to use a list or table to lay out the +abbreviations, in the usual way. +@PP +Next comes an optional introduction, exactly like the preface except that +its name is @Code "@Introduction" and the default title in English is +introduction. @Index @Code "@Introduction" +Introduction: +@ID @OneRow @Code { +"@Introduction" +"@Begin" +"@PP" +"..." +"@End @Introduction" +} +After that comes a sequence of chapters in the usual style: +chapter. @Index @Code "@Chapter" +@ID @OneRow @Code { +"@Chapter" +" @Title { Australian Native Plants }" +"@Begin" +"@PP" +"..." +"@End @Chapter" +} +No @Code "@BeginChapters" or @Code "@EndChapters" symbols are +beginchapters. @Index @Code "@BeginChapters" +endchapters. @Index @Code "@EndChapters" +needed, because these chapters are not inside any other large-scale +structure symbol. Within a chapter, there may be a sequence of sections, +each introduced by {@Code "@Section"}, all bracketed +section.books @SubIndex { in books } +by @Code "@BeginSections" and {@Code "@EndSections"}: +beginsections.books @SubIndex { in books } +endsections.books @SubIndex { in books } +@ID @OneRow @Code { +"preceding text" +"@BeginSections" +"@Section ... @End @Section" +"@Section ... @End @Section" +"..." +"@Section ... @End @Section" +"@EndSections" +} +Within each section there may be subsections, each introduced by +{@Code "@SubSection"}, and the sequence as a whole bracketed by +@Code "@BeginSubSections" and {@Code "@EndSubSections"}: +subsection.books @SubIndex { in books } +beginsubsections.books @SubIndex { in books } +endsubsections.books @SubIndex { in books } +@ID @OneRow @Code { +"preceding text" +"@BeginSubSections" +"@SubSection ... @End @SubSection" +"@SubSection ... @End @SubSection" +"..." +"@SubSection ... @End @SubSection" +"@EndSubSections" +} +The subsections may contain sub-subsections, but +subsubsection.books @SubIndex { in books } +beginsubsubsections.books @SubIndex { in books } +endsubsubsections.books @SubIndex { in books } +there are no sub-sub-subsections. +@PP +After the chapters comes an optional sequence of appendices. Each +is introduced by @Code "@Appendix" in the usual way: +appendix.books @SubIndex { in books } +@ID @OneRow @Code { +"@Appendix" +" @Title { Climatic Regions of Australia }" +"@Begin" +"@PP" +"..." +"@End @Appendix" +} +No @Code "@BeginAppendices" or @Code "@EndAppendices" symbols are +beginappendices.books @SubIndex { in books } +endappendices.books @SubIndex { in books } +needed, because (like chapters) these appendices do not lie inside +any other large-scale structure symbol. The appendices are numbered +A, B, C, etc., as is conventional for them. Within each appendix +there may be a sequence of subappendices, obtained with the +@Code "@SubAppendix" symbol and bracketed by +subappendix.books @SubIndex { in books } +@Code "@BeginSubAppendices" and {@Code "@EndSubAppendices"}: +beginsubappendices.books @SubIndex { in books } +endsubappendices.books @SubIndex { in books } +@ID @OneRow @Code { +"preceding text" +"@BeginSubAppendices" +"@SubAppendix ... @End @SubAppendix" +"@SubAppendix ... @End @SubAppendix" +"..." +"@SubAppendix ... @End @SubAppendix" +"@EndSubAppendices" +} +There are sub-subappendices following the same pattern, but no +subsubappendix.books @SubIndex { in books } +beginsubsubappendices.books @SubIndex { in books } +endsubsubappendices.books @SubIndex { in books } +sub-sub-subappendices. +@PP +The book ends with the last chapter or appendix; any reference list or +index will be appended automatically. Although we have described how to +create books as though everything was in one large file, in practice it +is much better to divide the book into multiple files, following the +method given in Section {@NumberOf organizing}. +@PP +In addition to the {@Code "@Title"} option, each large-scale structure +symbol (i.e. {@Code "@Preface"}, {@Code "@Introduction"}, {@Code "@Chapter"}, +{@Code "@Section"}, {@Code "@SubSection"}, {@Code "@SubSubSection"}, +{@Code "@Appendix"}, {@Code "@SubAppendix"}, and {@Code "@SubSubAppendix"}) +has a @Code "@Tag" option for cross referencing (Section {@NumberOf cross}), +an @Code "@InitialLanguage" option for changing the language of that +part of the document, and a @Code "@RunningTitle" option which will be +used in place of @Code "@Title" in running headers if given. This last +is useful when the full title is rather long. +@PP +The @Code "@Chapter" symbol has three additional options for dividing +parts. @Index { parts of books } +the book into parts: +part.number @Index @Code "@PartNumber" +part.title @Index @Code "@PartTitle" +part.text @Index @Code "@PartText" +@ID @OneRow @Code { +"@Chapter" +" @PartNumber { Part A }" +" @PartTitle { The Ancient World }" +" @PartText { ... }" +} +Any chapter with a non-empty @Code "@PartTitle" option will become the +first chapter of a part. It will be preceded by two pages containing the +part number, title, and text, and there will also be an entry +made in the table of contents. @Code "@PartNumber" and @Code "@PartText" +may be omitted. Parts are @I not numbered automatically: you +have to supply your own numbers or letters as shown above. +@PP +The features described in other chapters are all available within +books. A table of contents and index will appear automatically, and +you will need to change the setup file to avoid them. Endnotes will +appear at the end of the enclosing preface, introduction, chapter, or +appendix. The numbering of figures and tables includes a chapter or +appendix number: the first figure of Appendix C will be Figure C.1, +and so on. Figures and tables within the preface or introduction are +numbered 1, 2, 3, etc. A figure or table will never appear on the +same page as the beginning of a chapter or appendix. References work +as described in Chapter {@NumberOf biblio}. As explained there, it is +possible to have a list of references at the end of each chapter as well +as at the end of the book. +@PP +Within the @Code "book" setup file there is a @Code "@BookSetup" +booksetup. @Index @Code "@BookSetup" +symbol whose options control the appearance of features specific to books +(in other words, the features described in this section). Here is a +representative sample of these options, showing their default values: +@ID @OneRow @Code { +"@Use { @BookSetup" +" # @TitlePageFont { Helvetica Base }" +" # @SeparateIntroNumbering { Yes }" +" # @PrefaceAfterContents { No }" +" # @ReferencesBeforeAppendices { No }" +" # @ChapterStartPages { Any }" +" # @ChapterWord { chapter }" +" # @ChapterNumbers { Arabic }" +" # @ChapterHeadingFont { Bold 2.00f }" +" # @ChapterHeadingBreak { ragged 1.2fx nohyphen }" +" # @ChapterHeadingFormat { number @DotSep title }" +" # @AboveChapterGap { 3.00f }" +" # @ChapterInContents { Yes }" +"}" +} +Section {@NumberOf setup} explains how to make your own setup file and +change its options. @Code "@TitlePageFont" is the font used on the title +title.page.font. @Index @Code "@TitlePageFont" +page of the book, not including a size. @Code "@ChapterStartPages" +determines what kinds of pages chapters and other major components of the +book may begin on, and may be {@Code Any}, {@Code Odd}, or {@Code Even}, +meaning any page, odd-numbered pages only, or even-numbered pages +only. @Code "@SeparateIntroNumbering" +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" +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"}, +produces `Chapter' in the current language. The other six options control +the appearance of chapters, and there are similar options for controlling +the other large-scale structure symbols. +@PP +@Code "@ChapterNumbers" determines how chapters will be numbered, and may +be @Code { None }, @Code { Arabic }, @Code { Roman }, @Code { UCRoman }, +@Code { Alpha }, or @Code { UCAlpha }. The default value is @Code Arabic +for chapters and also for all large-scale structure symbols except +appendices, for which it is {@Code UCAlpha}. This produces the appendices +numbered in upper-case letters (A, B, C, etc.) that were mentioned earlier. +@PP +@Code "@ChapterHeadingFont" is the font used for chapter headings. The +default value shown above produces the bold face of the initial font +family, at twice the initial size. A family name is acceptable +here as well. @Code "@ChapterHeadingBreak" is the break style for +chapter headings. +@PP +@Code "@ChapterHeadingFormat" allows you to change +the format of the heading. The symbol @Code "number" within it will +be replaced by the number of the chapter (actually including the word +Chapter as well in the current language, e.g. {@Code "Chapter 12"}); the +symbol @Code "title" within it will be replaced by the title. So you could +write, say, +@ID @Code +"@ChapterHeadingFormat { @Box paint { lightgrey } { number @DP title } }" +to get the title below the number, both enclosed in a box. The default +value uses the @Code "@DotSep" symbol from Section {@NumberOf headers} +to produce the number and title separated by a dot and two spaces, roughly +the same as +@ID @Code "@ChapterHeadingFormat { number. title }" +except when there is no number. This option is applied +to other major headings, in the preface, introduction, table of +contents, appendices, reference list, and index. In all these other +cases, @Code "number" is an empty object, except for appendices, when it +contains @Code "Appendix A" or whatever. +@PP +There is a @Code "@PartHeadingFormat" option for determining the +format of part headings. It works in the same way as +{@Code "@ChapterHeadingFormat"}, with @Code "number" and @Code "title" +symbols standing for the relevant @Code "@PartNumber" and @Code "@PartTitle" +options. The default value is +@ID @Code "@PartHeadingFormat { @CD number @DP @CD title }" +which centres the number and title. The default paragraph breaking +style is {@Code "clines"}, but you may place a @Code "@Break" symbol +within @Code "@PartHeadingFormat" to change this. +@PP +The example of boxed titles for chapters given above suffers from two +practical deficiencies. First, the box won't extend right across the +page, and second, when there is no @Code "number" we don't want the +@Code "@DP" either. Here is a value for @Code "@ChapterHeadingFormat" +that solves both of these problems and looks good in practice: +@ID @OneCol @Code { +"@ChapterHeadingFormat {" +" number @Case {" +" {} @Yield @Box paint { lightgrey } @HExpand { title }" +" else @Yield @Box paint { lightgrey } @HExpand { number @DP title }" +" }" +"}" +} +The @Code "@Case" symbol (Expert's Guide @Cite { $kingston1995lout.expert }) +distinguishes between the cases where @Code "number" is empty and non-empty; +the @Code "@HExpand" symbol expands the horizontal space occupied by the +heading to the maximum possible, so that when the box is drawn around it +it will occupy the full page width. The format can be as +complicated as you like, and there is no need to squeeze it all onto +one line; as always, the end of a line is the same as one space. +@PP +Every chapter and appendix begins on a new page. @Code "@AboveChapterGap" +determines how much space is left blank above the chapter title; the +default value is three times the initial font size. There are similar +options for other large-scale structure symbols, which determine how +much space is left before each one. +@PP +@Code "@ChapterInContents" determines whether or not an entry is made in +the table of contents for each chapter; it may be @Code Yes or {@Code No}, +but would always be {@Code Yes}. The default value of the corresponding +options for sub-subsections and sub-subappendices, however, is {@Code No}. +@End @Section diff --git a/doc/user/typ_illu b/doc/user/typ_illu new file mode 100644 index 0000000..532b42b --- /dev/null +++ b/doc/user/typ_illu @@ -0,0 +1,85 @@ +@Section + @Title { Stand-alone illustrations } + @Tag { illustrations } +@Begin +@PP +This section describes how to use Lout to produce an illustration for +stand.alone.illustrations. @Index { stand-alone illustrations } +illustrations. @Index { illustrations } +inclusion in some other document, which may itself be a Lout document +but need not be. The opposite process, the inclusion of an illustration +in a Lout document, is the subject of Section {@NumberOf include}. +@PP +Suppose you want to produce the following logo +for inclusion in some other document: +@ID { +45d @Rotate @CurveBox { ARMY @LP 180d @Rotate ARMY } +} +This is just an object, and it is not hard to make it using Lout's +graphics features: +@ID @Code "45d @Rotate @CurveBox { ARMY @LP 180d @Rotate ARMY }" +The problem is that objects ordinarily come out on pages with margins, +page numbers, and so forth, which we don't want here. The solution +is to use the illustration document type, whose setup file, curiously +enough, is called {@Code "picture"}: +illustration. @Index @Code "@Illustration" +@ID @OneRow @Code { +"@SysInclude { picture }" +"@Illustration {" +" 45d @Rotate @CurveBox { ARMY @LP 180d @Rotate ARMY }" +"}" +} +After the usual @Code "@SysInclude" line comes one @Code "@Illustration" +symbol. Following it is an arbitrary object which becomes the entire +result, with no pages and no margins, ready for inclusion in some other +document as an illustration. +@PP +The @Code "@Illustration" symbol has options for setting the initial +font, paragraph breaking style, colour, and language. Here they are +with their default values: +@ID @OneRow @Code { +"@Illustration" +" @InitialFont { Times Base 12p }" +" @InitialBreak { adjust 1.2fx hyphen }" +" @InitialSpace { lout }" +" @InitialLanguage { English }" +" @InitialColour { black }" +"{" +" ..." +"}" +} +You can specify any colour from the list in Section {@NumberOf colour}, +for example {@Code blue}, and then your illustration will have that +colour wherever it is included. +@PP +Because there are no pages, the width and height of the result are +indeterminate, depending on how large the object turns out to be. This +makes things very awkward for filled paragraphs and centring, which depend +on knowing how much space is available to be occupied. So you should either +avoid filled paragraphs and all displays and lists altogether in +illustrations, or else enclose your object in a @Code "@Wide" symbol: +wide @RawIndex { @Code "@Wide" } +wide.illustrations @SubIndex { with illustrations } +@ID @OneRow @Code { +"@Illustration 5c @Wide {" +" ..." +"}" +} +to make clear how wide you want your illustration to be. +@PP +The technical name for a file containing a stand-alone illustration +encapsulated.postscript @Index { encapsulated PostScript file } +eps @Index { EPS file } +is `encapsulated PostScript file' or `EPS file' for short. To get +Lout to produce an encapsulated PostScript file instead of an ordinary +PostScript file, you have to use the @Code "-EPS" Unix command line +flag. For example, suppose the Lout file containing our example +illustration is called {@Code "army"}; then the appropriate Unix +command for formatting it is +@ID @Code "lout -EPS army > army.eps" +An EPS file is supposed to contain only one `page', so Lout will refuse +to generate any second or subsequent pages when the @Code "-EPS" flag +is given. There is also a minor difference in format between ordinary +and encapsulated PostScript files, which is why the @Code "-EPS" flag +is needed at all. +@End @Section diff --git a/doc/user/typ_ordi b/doc/user/typ_ordi new file mode 100644 index 0000000..9fbd07a --- /dev/null +++ b/doc/user/typ_ordi @@ -0,0 +1,313 @@ +@Section + @Title { Ordinary documents } + @Tag { ordinary } +@Begin +@PP +Ordinary documents are the simplest kind, consisting of a plain sequence +ordinary. @Index { ordinary documents } +of numbered pages. To produce an ordinary document, use the @Code doc +setup file and the @Code "@Doc" symbol: +doc. @Index @Code "@Doc" +@ID @OneRow @Code { +"@SysInclude { doc }" +"@Doc @Text @Begin" +"..." +"@End @Text" +} +where @Code ... stands for the body of your document. This is the +arrangement from Section {@NumberOf start} for getting +started. Alternatively, you can begin with +@Code "@Document" instead of {@Code "@Doc"}: +document. @Index @Code "@Document" +@ID @OneRow @Code { +"@SysInclude { doc }" +"@Document" +" @InitialFont { Times Base 12p }" +" @InitialBreak { adjust 1.2fx hyphen }" +" @InitialSpace { lout }" +" @InitialLanguage { English }" +" @PageOrientation { Portrait }" +" @PageHeaders { Simple }" +" @FirstPageNumber { 1 }" +" @ColumnNumber { 1 }" +" @OptimizePages { No }" +" @Unpaginated { No }" +"//" +"@Text @Begin" +"..." +"@End @Text" +} +This shows all the options of {@Code "@Document"}, with their default +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"}. +@PP +The eight options are a selection of setup file options (Section +{@NumberOf setup}) that frequently need to be changed. If your changes +to the overall formatting are confined to these options, you can change +them here and avoid having your own setup file. If you already have +your own setup file, change them in either place and omit them in +the other. +@PP +@Code "@InitialFont" is the font of the bulk of the document, +and should contain a family, a face, and a size. The default +value selects the Times family, the Base face, and the 12 point size. +@PP +@Code "@InitialBreak" controls the behaviour of paragraph breaking in +the bulk of the document. It should have three parts: a paragraph +breaking style ({@Code adjust}, {@Code ragged}, etc.), an inter-line +spacing ({@Code "1.2fx"} for single spacing, {@Code "2.4fx"} for +double spacing, and so on), and either @Code "hyphen" or @Code "nohyphen" +for turning hyphenation on or off. It may also have @Code "nobreakfirst" +or @Code "nobreaklast" (or both), meaning to disallow a page break after +the first line of a paragraph, or before the last, respectively. +@PP +@Code "@InitialSpace" determines how Lout treats white space between +two objects, as described in Section +{@NumberOf white}. @Code "@InitialLanguage" determines the language +of the bulk of the document. +@PP +@Code "@PageOrientation" determines the orientation of the page. Its +value may be {@Code Portrait} (the default), {@Code Landscape}, +{@Code ReversePortrait}, or {@Code ReverseLandscape}. See +Section {@NumberOf pagesize} for further details. +@PP +@Code "@PageHeaders" determines the appearance of page headers and +footers throughout the document, and may be {@Code None}, +{@Code Simple}, {@Code Titles}, or {@Code NoTitles}. Section +{@NumberOf headers} has the details, but just briefly, {@Code None} +means no page headers at all, {@Code Simple} means a +page number between hyphens at the top of each page except the first, +@Code Titles produces full running titles as in this guide, +and @Code "NoTitles" is like @Code "Titles" with the running titles +omitted, leaving just the page numbers. +@PP +@Code "@FirstPageNumber" is the page number given to the first page. +@PP +@Code "@ColumnNumber" is the number of columns per page in the bulk of +the document, and may be anything from {@Code 1} (the default value) to +{@Code 10}. It is possible to produce full-width ordinary +text in a multi-column document, using the @Code "@FullWidth" +full.width. @Index @Code "@FullWidth" +symbol: +@ID @OneRow @Code { +"@SysInclude { doc }" +"@Document" +" @ColumnNumber { 2 }" +"//" +"@Text @Begin" +"@FullWidth {" +"@CentredDisplay @Heading { NOTICE TO TRESPASSERS }" +"}Trespassers are hereby notified that, ..." +"@End @Text" +} +This produces a full-width heading above a two-column body. The word +@Code Trespassers has been placed immediately after the closing brace +of @Code "@FullWidth" because (regrettably) any space here will appear +before @Code Trespassers in the output. Alternatively you could use +a paragraph symbol: +@ID @OneRow @Code { +"@FullWidth {" +"@CentredDisplay @Heading { NOTICE TO TRESPASSERS }" +"}" +"@PP" +"Trespassers are hereby notified that, ..." +} +You can have several @Code "@FullWidth" symbols, +producing full-width text wherever you want. Just be aware that +@Code "@FullWidth" always causes a fresh page to be begun, it will never +appear on the same page as a figure or table, and it is not able to hold +a table of contents, a section, or an appendix. +@PP +Lout ordinarily places lines onto a page until space runs out, then moves +to the next page and so on. This often produces ugly empty spaces at +the bottoms of pages preceding large unbreakable displays. Setting the +@Code "@OptimizePages" option to {@Code "Yes"} causes Lout to examine the +overall situation and try to minimize the ugliness, using the @TeX +tex.page @SubIndex { page optimization } +optimal paragraph breaking algorithm. It takes two runs to do this, +with intermediate results stored in Lout's cross reference database +(Section {@NumberOf cross}); so deleting file {@Code lout.li} will reset +it, which might be wise after major changes. It is possible for the +optimizer to cycle, never settling on a single final best +version; this is usually caused by footnotes or floating figures inserted +at points that end up near page boundaries. +@PP +The @Code "@Unpaginated" option, whose value is ignored unless plain text +output is in effect, produces unpaginated output when changed to +{@Code Yes} (see Section {@NumberOf plain}). +@PP +Within the @Code "@Text" symbol, it is possible to have a sequence +of sections: +section. @RawIndex @Code "@Section" +section.ordinary @SubIndex { in ordinary documents } +beginsections. @RawIndex @Code "@BeginSections" +beginsections.ordinary @SubIndex { in ordinary documents } +endsections. @RawIndex @Code "@EndSections" +endsections.ordinary @SubIndex { in ordinary documents } +@ID @OneRow @Code { +"preceding text" +"@BeginSections" +"@Section ... @End @Section" +"@Section ... @End @Section" +"..." +"@Section ... @End @Section" +"@EndSections" +} +as described in Section {@NumberOf largescale}. Within any +section, a similar arrangement produces subsections: +subsection. @RawIndex @Code "@SubSection" +subsection.ordinary @SubIndex { in ordinary documents } +beginsubsections. @RawIndex @Code "@BeginSubSections" +beginsubsections.ordinary @SubIndex { in ordinary documents } +endsubsections. @RawIndex @Code "@EndSubSections" +endsubsections.ordinary @SubIndex { in ordinary documents } +@ID @OneRow @Code { +"preceding text" +"@BeginSubSections" +"@SubSection ... @End @SubSection" +"@SubSection ... @End @SubSection" +"..." +"@SubSection ... @End @SubSection" +"@EndSubSections" +} +Within any subsection, there may be sub-subsections, obtained +using {@Code "@BeginSubSubSections"}, {@Code "@SubSubSection"}, +subsubsection. @RawIndex @Code "@SubSubSection" +subsubsection.ordinary @SubIndex { in ordinary documents } +beginsubsubsections. @RawIndex @Code "@BeginSubSubSections" +beginsubsubsections.ordinary @SubIndex { in ordinary documents } +endsubsubsections. @RawIndex @Code "@EndSubSubSections" +endsubsubsections.ordinary @SubIndex { in ordinary documents } +and {@Code "@EndSubSubSections"}. There are no sub-sub-subsections. +@PP +Also within the @Code "@Text" symbol only, there may be a sequence of +appendices: +appendix. @RawIndex @Code "@Appendix" +appendix.ordinary @SubIndex { in ordinary documents } +beginappendices. @RawIndex @Code "@BeginAppendices" +beginappendices.ordinary @SubIndex { in ordinary documents } +endappendices. @RawIndex @Code "@EndAppendices" +endappendices.ordinary @SubIndex { in ordinary documents } +@ID @OneRow @Code { +"preceding text" +"@BeginAppendices" +"@Appendix ... @End @Appendix" +"@Appendix ... @End @Appendix" +"..." +"@Appendix ... @End @Appendix" +"@EndAppendices" +} +These will be `numbered' A, B, C etc. as is conventional. Within any +appendix there may be a sequence of subappendices, obtained in the +usual way using {@Code "@BeginSubAppendices"}, {@Code "@SubAppendix"}, +subappendix. @RawIndex @Code "@SubAppendix" +subappendix.ordinary @SubIndex { in ordinary documents } +beginsubappendices. @RawIndex @Code "@BeginSubAppendices" +beginsubappendices.ordinary @SubIndex { in ordinary documents } +endsubappendices. @RawIndex @Code "@EndSubAppendices" +endsubappendices.ordinary @SubIndex { in ordinary documents } +and {@Code "@EndSubAppendices"}. There are sub-subappendices as well, +following the same pattern, but no sub-sub-subappendices. +subsubappendix. @RawIndex @Code "@SubSubAppendix" +subsubappendix.ordinary @SubIndex { in ordinary documents } +beginsubsubappendices. @RawIndex @Code "@BeginSubSubAppendices" +beginsubsubappendices.ordinary @SubIndex { in ordinary documents } +endsubsubappendices. @RawIndex @Code "@EndSubSubAppendices" +endsubsubappendices.ordinary @SubIndex { in ordinary documents } +@PP +In addition to the {@Code "@Title"} option, each large-scale structure +symbol ({@Code "@Section"}, {@Code "@SubSection"}, {@Code "@SubSubSection"}, +{@Code "@Appendix"}, {@Code "@SubAppendix"}, and {@Code "@SubSubAppendix"}) +has a @Code "@Tag" option for cross referencing (Section {@NumberOf cross}), +an @Code "@InitialLanguage" option for changing the language of that part +of the document, and a @Code "@RunningTitle" option which will be used in +place of @Code "@Title" in running headers if given. @Code "@RunningTitle" +is useful when the full title is rather long. +@PP +The features described in other chapters are all available within +ordinary documents. Endnotes and references appear automatically at +the end of the document. Figures are labelled Figure 1, Figure 2, +etc., and tables are labelled Table 1, Table 2, etc. +@PP +To get a table of contents, set the @Code "@MakeContents" option in +the setup file to {@Code Yes}, and insert the symbol +@Code "@ContentsGoesHere" at the point where you would like the +contents.goes.here. @Index @Code "@ContentsGoesHere" +table of contents to appear, anywhere before the first section: +@ID @OneRow @Code { +"@SysInclude { doc }" +"@Text @Begin" +"@CentredDisplay @Heading { Safety Procedures }" +"@Heading { Contents }" +"@DP" +"@ContentsGoesHere" +"@DP" +"..." +"@End @Text" +} +You must supply your own heading, as well as paragraph symbols +before and after. Regrettably, @Code "@ContentsGoesHere" may +not be placed inside a display, nor inside {@Code "@FullWidth"}. +@PP +To get an index, set the @Code "@MakeIndex" option in the setup file +to {@Code Yes}, and follow the instructions in Section +{@NumberOf indexes}. The index will appear automatically at the end +of your document. +@PP +Within the @Code doc setup file there is an @Code "@OrdinarySetup" +symbol whose options control the appearance of features specific to +ordinary documents (in other words, the features described in this +section). Here is a representative sample of these options, showing +their default values: +ordinary.setup @Index @Code "@OrdinarySetup" +@ID @OneRow @Code { +"@Use { @OrdinarySetup" +" # @IndexWord { index }" +" # @AppendixWord { appendix }" +" # @SectionNumbers { Arabic }" +" # @SectionHeadingFont { Bold }" +" # @SectionGap { 2.00v }" +" # @SectionInContents { Yes }" +"}" +} +Section {@NumberOf setup} explains how to make your own setup file and +change its options. +@PP +The @Code "@IndexWord" option determines what the index is called, if +there is one. The default value, {@Code "index"}, produces the word +`Index' in the current language. Any other value produces itself. The +@Code "@AppendixWord" option is similar; its default value is `Appendix' +in the current language. +@PP +@Code "@SectionNumbers" determines how sections will be numbered, and may +be @Code { None }, @Code { Arabic }, @Code { Roman }, @Code { UCRoman }, +@Code { Alpha }, or @Code { UCAlpha }. The default value is @Code Arabic +for sections and also all other large-scale structure symbols except +appendices, for which it is {@Code UCAlpha}. This produces the appendices +numbered in upper-case letters (A, B, C, etc.) that were mentioned earlier. +@PP +@Code "@SectionHeadingFont" is the font used for section headings. The +default value produces the bold face from the family of the +initial font. A family name or size is also acceptable: +@ID @Code "@SectionHeadingFont { Helvetica Base +2p }" +makes the section heading appear in the Helvetica font, two +points larger than the initial size. +@PP +@Code "@SectionGap" determines how much space is left blank before each +section title; the default value shown above is twice the current +inter-line spacing. The special value @Code "2b" may be used to get a +page break rather than a space. There are similar options for other +large-scale structure symbols, which determine how much space is left +before each one. +@PP +@Code "@SectionInContents" determines whether or not an entry is made in +the table of contents for each section; it may be @Code Yes or {@Code No}, +but would always be {@Code Yes}. The default value of the corresponding +options for sub-subsections and sub-subappendices, however, is {@Code No}. +@End @Section diff --git a/doc/user/typ_orga b/doc/user/typ_orga new file mode 100644 index 0000000..8ba6ab7 --- /dev/null +++ b/doc/user/typ_orga @@ -0,0 +1,93 @@ +@Section + @Title { Organizing large documents } + @Tag { organizing } +@Begin +@PP +It is not a good plan to store a large document in a single large +organizing.large @Index { organizing large documents } +file. It takes too long to find things in it, and if some catastrophe +occurs, you lose the lot. Lout encourages you to break documents into +pieces by its willingness to read a sequence of files +({@Code "lout file1 file2 ..."}). For large documents, the following +plan is recommended. +@PP +Suppose you are making a book whose third chapter contains sections on +banksias, grevilleas, acacias, and eucalypts. Place each section, from +@Code "@Section" to {@Code "@End @Section"}, in a separate file, making +four files called, say, {@Code banksias}, {@Code grevilleas}, +{@Code acacias}, and {@Code eucalypts}. Then make a single file for the +chapter as a whole whose contents are as follows: +@ID @OneRow @Code { +"@Chapter" +" @Title { Australian Native Plants }" +"@Begin" +"Australian native plants provide a distinctive identity to the garden. Although" +"less colourful than their European alternatives, some banksias and grevilleas do" +"flower strongly, and of course the acacias (wattles) are unsurpassable in late winter." +"@BeginSections" +"@Include { banksias }" +"@Include { grevilleas }" +"@Include { acacias }" +"@Include { eucalypts }" +"@EndSections" +"@End @Chapter" +} +The @Code "@Include" symbol causes Lout to read the file whose name follows +include. @Index @Code "@Include" +it between braces, just as though the contents of that file had been included +at that point. +@PP +With this arrangement you can easily rearrange the order of the +sections: just swap their @Code "@Include" lines. You should be using +Lout's automatic cross referencing features (Section {@NumberOf cross}), +so you don't have to worry about keeping cross references up to date. You +can also temporarily delete a section by placing a @Code "#" character at +the start of its line: +@ID @Code "# @Include { acacias }" +This works because @Code "#" is the @I { comment character }: Lout will +comment. @Index { comments } +ignore this character (unless enclosed in double quotes) and everything +following it up to the end of the line. You can even temporarily delete +every section except the one you are working on at the moment, using +these comments. +@PP +Suppose now that this chapter file is called @Code { natives }, and you +have others called @Code { preface }, @Code { flowers }, etc. Then you +can make one file (call it @Code { garden }) for the whole book like this: +@ID @OneRow @Code { +"@SysInclude { book }" +"@Book" +" @Title { The Australian Garden }" +" @Author { Martha S. Vineyard }" +"//" +"@Include { preface }" +"@Include { flowers }" +"@Include { shrubs }" +"@Include { natives }" +"@Include { trees }" +} +You can play the same tricks here: swap chapters around, or temporarily +delete one or more with a {@Code "#"}. When a chapter is finished +you can temporarily delete it to save formatting time and paper, and +bring it back at the end. To format the book, use +@Code "lout garden > out.ps" +in Unix. Lout will read each @Code "@Include" file as it comes to it, +and if it finds an @Code "@Include" of a section while reading a chapter +file, it will read the section too. +@PP +If the order of your chapters is fairly stable, it might be advantageous +to use the @Code "@BypassNumber" option of @Code "@Chapter" (described +in Appendix {@NumberOf bypass}) to fix the numbers of all your chapters, +so that you get correct chapter numbers even when formatting one +chapter at a time. +@PP +If you decide to store chapters in separate Unix directories, make sure +that any @Code "/" characters in the file names are enclosed in double +quotes: +@ID @Code "@Include { \"natives.dir/acacias\" }" +Be careful not to give the directory the same name as your chapter +file. You might also find it useful to construct your book +@I { top-down }, as computer scientists call it, laying out all the +chapters and sections as empty skeletons and filling their contents in +later. +@End @Section diff --git a/doc/user/typ_over b/doc/user/typ_over new file mode 100644 index 0000000..fd14e2a --- /dev/null +++ b/doc/user/typ_over @@ -0,0 +1,314 @@ +@Section + @Title { Overhead transparencies } + @Tag { overheads } +@Begin +@PP +To produce overhead transparencies +@FootNote { +In Version 3.15 overhead transparencies were updated and brought into line +with the other document types. Although existing source files do not need +to be modified, their printed appearance may change (spacing, running +headers). There are some new setup file options, and some changes to +existing setup file options. +} +(hereafter called overheads), start off +overheads. @Index { overhead transparencies } +slides. @RawIndex { slides @I see overhead transparencies } +with the @Code slides setup file and the @Code "@OverheadTransparencies" +overhead.transparencies. @Index @Code "@OverheadTransparencies" +symbol: +@ID @OneRow @Code { +"@SysInclude { slides }" +"@OverheadTransparencies" +" @Title {}" +" @RunningTitle {}" +" @Author {}" +" @Institution {}" +" @DateLine { No }" +" @InitialFont { Times Base 20p }" +" @InitialBreak { ragged 1.2fx nohyphen }" +" @InitialSpace { lout }" +" @InitialLanguage { English }" +" @PageOrientation { Portrait }" +" @PageHeaders { Titles }" +" @FirstPageNumber { 1 }" +" @FirstOverheadNumber { 1 }" +" @FirstLectureNumber { 1 }" +" @OptimizePages { No }" +"//" +} +This shows all the options of @Code "@OverheadTransparencies" 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 given at all. The +meaning of the @Code "//" symbol after the last option is beyond our +scope, but disaster will ensue if it is forgotten. +@PP +If @Code "@Title" is not empty, an initial overhead will be produced +containing the {@Code "@Title"}, {@Code "@Author"}, {@Code "@Institution"}, +and {@Code "@DateLine"} options. @Code "@DateLine" may be set to +{@Code "No"}, meaning no dateline, {@Code "Yes"}, meaning print the current +date, or anything else, which is taken to be a date and printed. +@PP +Each overhead has a running header printed in small type at the top +left. The @Code "@RunningTitle" option goes into this header, or, if +there is no @Code "@RunningTitle" option, @Code "@Title" is used instead. +@PP +The remaining options are a selection of setup file options (Section +{@NumberOf setup}) that frequently need to be changed. If your changes +to the overall formatting are confined to these options, you can change +them here and avoid having your own setup file. If you already have +your own setup file, change them in either place and omit them in +the other. +@PP +@Code "@InitialFont" is the font in which the overheads will be set, and +should contain a family, a face, and a size. A good font size for +overheads is 20 points, so that is the default size. +@PP +@Code "@InitialBreak" controls the behaviour of paragraph breaking in +the overheads. It should have three parts: a paragraph +breaking style ({@Code adjust}, {@Code ragged}, etc.), an inter-line +spacing ({@Code "1.2fx"} for single spacing, {@Code "2.4fx"} for +double spacing, and so on), and either @Code "hyphen" or @Code "nohyphen" +for turning hyphenation on or off. Adjusted lines and hyphenated words +are difficult to read from overheads, so the default is not to have them. +@Code "@InitialSpace" determines how Lout treats white space between +objects (Section {@NumberOf white}). @Code "@InitialLanguage" +determines the language of the overheads. +@PP +@Code "@PageOrientation" determines the orientation of the page. Its +value may be {@Code Portrait} (the default), {@Code Landscape}, +{@Code ReversePortrait}, or {@Code ReverseLandscape}. See +Section {@NumberOf pagesize} for further details. +@PP +@Code "@PageHeaders" determines the appearance of page headers and +footers. Its value may be {@Code None}, {@Code Simple}, {@Code Titles}, +or {@Code NoTitles}. Section {@NumberOf headers} has the details, but +just briefly, {@Code None} produces no page headers, {@Code Simple} produces +page numbers only, @Code Titles produces full running titles, and +@Code "NoTitles" is similar to @Code "Simple" in this context. +@PP +@Code "@FirstPageNumber" is the number given to the first page, +@Code "@FirstOverheadNumber" is the number given to the first overhead, +and @Code "@FirstLectureNumber" is the number given to the first lecture, +of which more below. See preceding sections for {@Code "@OptimizePages"}. +# Lout ordinarily places lines onto a page until space runs out, then moves +# to the next page and so on. This often produces ugly empty spaces at +# the bottoms of pages preceding large unbreakable displays. Setting the +# @Code "@OptimizePages" option to {@Code "Yes"} causes Lout to examine the +# overall situation and try to minimize the ugliness, using the @TeX +# optimal paragraph breaking algorithm. It takes two runs to do this, +# with intermediate results stored in Lout's cross reference database +# (Section {@NumberOf cross}); so deleting file {@Code lout.li} will reset +# it, which might be wise after major changes. It is possible for the +# 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 +After the compulsory {@Code "//"} come the overheads themselves. There +are two alternatives: a series of overheads, corresponding to a single +lecture, or a series of series of overheads, corresponding to a series +of lectures. If the first is wanted, use this arrangement: +overhead. @Index @Code "@Overhead" +@ID @OneRow @Code { +"@SysInclude { slides }" +"@OverheadTransparencies" +" ..." +"//" +"@Overhead ... @End @Overhead" +"@Overhead ... @End @Overhead" +"..." +"@Overhead ... @End @Overhead" +} +@Code "@Overhead" is a large-scale structure symbol, similar to +{@Code "@Section"}, with the usual options: +@ID @OneRow @Code { +"@Overhead" +" @Title { Trends in investment since 1980 }" +" @RunningTitle { Investment }" +" @Tag { investment }" +" @InitialLanguage { English }" +"@Begin" +"..." +"@End @Overhead" +} +If @Code "@Title" is given it will appear as a centred, bold display +at the beginning of the overhead. As usual, these options may be given +in any order or omitted altogether. +@PP +The body of the overhead is quite arbitrary. Typically one tends to +use lists and displays more than paragraphs, but all the usual features +are available. Each overhead begins on a fresh page, but it may occupy +more than one page. +@PP +@Code "@Overhead" also has a @Code "@Format" option which allows you to +specify an arbitrary format for the body of the overhead (that is, +everything except its title). For example, +@ID @Code "@Format { @CurveBox @HExpand @VExpand @Body }" +encloses the body in a curvebox, with the box expanded to the full +available width and height. Unlike the similar option for figures +and tables, however, this @Code "@Format" option unfortunately has +not been set up to work with multi-page overheads, so if you use the +format just given you have to make sure your overheads all fit on one +page. To draw boxes around the @I entire page, use the @Code "@PageBox" +setup file options. +@PP +Lout does not provide any special support for overlays. A good way to +make them is to first produce one overhead containing all the layers +simultaneously. Once this is correct, enclose the entire body of the +overhead in {@Code "white @Colour"}, make one copy of the text of the +overhead for each layer, separating the copies with @Code "@NP" +(new page) symbols, and, in each copy, enclose the parts that are +to appear in that layer in {@Code "black @Colour"} (or any other +colour). This works because @Code "white @Colour" makes an object +invisible without altering its size. +@PP +We turn now to the second major alternative, which is a series +of lectures, like this: +lecture. @Index @Code "@Lecture" +@ID @OneRow @Code { +"@SysInclude { slides }" +"@OverheadTransparencies" +" ..." +"//" +"@Lecture ... @End @Lecture" +"@Lecture ... @End @Lecture" +"..." +"@Lecture ... @End @Lecture" +} +@Code "@Lecture" is a large-scale structure symbol, again with +the usual options: +@ID @OneRow @Code { +"@Lecture" +" @Title { Macro-Economic Policies for the Nineties }" +" @RunningTitle { Macro-economic policies }" +" @Tag { macro-economics }" +" @InitialLanguage { English }" +"@Begin" +"..." +"@End @Lecture" +} +If @Code "@Title" is non-empty the series of overheads will begin with +an overhead containing the title alone, centred on the page using the +@Code "clines" paragraph breaking style. This means that it makes +sense to have a multi-line title. Any text following the @Code "@Begin" +will appear under the lecture title as you would expect. +@PP +Within the body of {@Code "@Lecture"}, place a series of overheads +bracketed by @Code "@BeginOverheads" and {@Code "@EndOverheads"}: +beginoverheads. @Index @Code "@BeginOverheads" +endoverheads. @Index @Code "@EndOverheads" +@ID @OneRow @Code { +"@BeginOverheads" +"@Overhead ... @End @Overhead" +"@Overhead ... @End @Overhead" +"..." +"@Overhead ... @End @Overhead" +"@EndOverheads" +} +The @Code "@Overhead" symbol is exactly as described earlier. +@PP +The features described in other chapters are available with +overheads. Endnotes and references appear automatically at the +end of the overheads. You can have a table of contents, by setting +the @Code "@MakeContents" option of the setup file to {@Code Yes}. It +will appear automatically after any title overhead. The setup file +options have been set on the assumption that you want your lectures +to appear in the table of contents, but not individual overheads. It is not +possible to have an index, and it is not possible to have multiple columns. +@PP +Within the @Code slides setup file there is an @Code "@OverheadSetup" +symbol whose options control the appearance of features specific to +overhead.setup. @Index @Code "@OverheadSetup" +overheads (in other words, the features described in this section). Here +are some of these options and their default values: +@ID @OneRow @Code { +"@Use { @OverheadSetup" +" # @DateLine { No }" +" # @FirstOverheadNumber { 1 }" +" # @FirstLectureNumber { 1 }" +" # @ContentsWord { contents }" +" # @LectureNumbers { Arabic }" +" # @OverheadNumbers { Arabic }" +" # @TitlePageFont { Helvetica Base }" +" # @LectureHeadingFont { Bold 1.20f }" +" # @LectureHeadingFormat { @Centre number @DP @Centre title @DP }" +" # @OverheadHeadingFormat { @Centre title @DP }" +" # @OverheadHeadingFont { Bold }" +" # @LectureInContents { Yes }" +" # @OverheadInContents { No }" +" # @ReferencesInContents { Yes }" +"}" +} +For an introduction to setup files and their options, consult +Section {@NumberOf setup}. The first four options are as for +@Code "@OverheadTransparencies" as described above. @Code "@ContentsWord" +determines the table of contents heading; its default value, {@Code contents}, +produces `Contents' in the current language. @Code "@LectureNumbers" +and @Code "@OverheadNumbers" determine the style of numbering of lectures +and overheads, and may be {@Code None}, {@Code Arabic}, {@Code Roman}, +{@Code UCRoman}, {@Code Alpha}, or {@Code UCAlpha} as usual. Next come +options for setting the font of the overall title page, the +title page of each lecture, and so on, and finally options which +determine which entries are made in any table of contents. +@PP +The @Code "@LectureHeadingFormat" option determines the +format of the heading of each lecture. Within it, the symbol @Code "number" +stands for the number of the lecture, including the `Lecture' word if +there is one, and @Code "title" stands for the title of the lecture. The +default value centres the number and title, with display gaps below +each one. @Code "@OverheadHeadingFormat" is similar; it has the same +symbols but the default value chooses not to use {@Code "number"}. +@PP +Other setup file options exist which permit you to have a box drawn +around each overhead, and to change the page size, margins, and +orientation. These are described in Chapter {@NumberOf changes}. +@PP +Section {@NumberOf headers} describes the setup file options that +control the appearance of page headers and footers. With overheads, +the values given to the {@Code "@MajorTitle"}, {@Code "@MinorTitle"}, +{@Code "@MajorNum"}, and {@Code "@MinorNum"} symbols within those +options are as follows. If @Code "@Lecture" is being used: +@ID @Tab + @Fmta { @Col A ! @Col B } +{ +@Rowa + A { @Code "@MajorTitle" } + B { The @Code "@RunningTitle" option of +{@Code "@OverheadTransparencies"}, or its @Code "@Title" option +if @Code "@RunningTitle" is absent; } +@Rowa + A { @Code "@MinorTitle" } + B { The @Code "@RunningTitle" option of the current +{@Code "@Lecture"}, or else its @Code "@Title" option if +@Code "@RunningTitle" is absent; } +@Rowa + A { @Code "@MajorNum" } + B { The number of the current {@Code "@Lecture"}; } +@Rowa + A { @Code "@MinorNum" } + B { A two-part number, for example 5.2, containing the number of +the current @Code "@Lecture" and the number within that lecture +of the current overhead. } +} +If @Code "@Lecture" is not being used: +@ID @Tab + @Fmta { @Col A ! @Col B } +{ +@Rowa + A { @Code "@MajorTitle" } + B { The @Code "@RunningTitle" option of +{@Code "@OverheadTransparencies"}, or its @Code "@Title" option +if @Code "@RunningTitle" is absent; } +@Rowa + A { @Code "@MinorTitle" } + B { Empty; } +@Rowa + A { @Code "@MajorNum" } + B { Empty; } +@Rowa + A { @Code "@MinorNum" } + B { The number of the current overhead. } +} +The first page occupied by any overhead is a @Code Start page; subsequent +pages are @Code NonStart pages. There are no @Code Intro pages. +@End @Section diff --git a/doc/user/typ_plai b/doc/user/typ_plai new file mode 100644 index 0000000..a880ccb --- /dev/null +++ b/doc/user/typ_plai @@ -0,0 +1,76 @@ +@Section + @Title { Plain text documents } + @Tag { plain } +@Begin +@PP +Occasionally you may need to produce an output file containing plain text +plain.text. @Index { plain text documents } +rather than PostScript, for example for an online manual entry or to send +as electronic mail. Any document that can be produced by Lout in +PostScript can be produced in plain text as well, by adding a @Code "-p" +flag to the Unix command line: +@ID @Code "lout -p simple" +No other changes are required. Here we are sending the output directly to +the screen, but it can be redirected to a file, or piped through the +@Code more command for viewing one page at a time, etc. +@PP +Of course, plain text is an extremely limited medium of communication +compared with PostScript, and this forces Lout to make some rather +drastic compromises: +@BulletList gap { @ParaGap } +@LI { Symbols like {@Code "@Bullet"}, which stand for unusual characters, +produce printable characters which approximate the PostScript ones. For +example, {@Code "@Bullet"} produces {@Code "o"}. However, the @Code "@Char" +and @Code "@Sym" symbols often produce unprintable characters, and are best +avoided; } +@LI { All font and size changes are ignored, since plain text has only +one font and size. Every character is taken to be @Eq { 1 frac 10 } inch +wide and @Eq { 1 frac 6 } inch high; } +@LI { No underlines are printed; } +@LI { No margin notes are printed; } +@LI { Scaled objects are not printed unless the scale factor happens to be 1; } +@LI { Rotated objects are not printed unless the angle happens to be zero +degrees. This means that page orientations (Section {@NumberOf pagesize}) +other than @Code Portrait do not work; } +@LI { Ruled lines are not printed, and paint and colour options are +ignored. This spoils the graphics and graphs of Chapters +{@NumberOf graphics}, {@NumberOf diagrams}, and {@NumberOf graphs}. } +@EndList +Despite the problems, many things work surprisingly well. Tables, for example, +look very good. It does no harm to try things and see if they work out. +@PP +The worst problem with plain text is that characters cannot be placed at +arbitrary points on the page. A superscript, for example, is impossible to +place correctly, so Lout uses a different layout for footnote labels (and +makes a mess of equations, which are best avoided). Because of this problem +it's best to make all horizontal lengths multiples of @Eq {1 frac 10} inch +(conveniently expressed as {@Code 1s}), and all vertical lengths multiples +of @Eq { 1 frac 6 } inch (conveniently expressed as {@Code 1f}). To help +you do this, the setup files contain many entries that look like this +example: +@ID @Code "# @InitialBreak { {adjust 1.2fx hyphen} @OrIfPlain {ragged 1fx nohyphen} }" +The meaning is that the value of @Code "@InitialBreak" will be +@Code "adjust 1.2fx hyphen" usually, but will switch to +{@Code "ragged 1fx nohyphen"}, which is better suited to plain text, +if the @Code "-p" command line flag is used. These setup file values +allow you to switch from PostScript to plain text and back again without +changing anything at all except the @Code "-p" command line flag. +@PP +If you use @Code "lout -P" instead of {@Code "lout -p"}, the plain text +output will contain a form-feed character (control-L) after each page +form.feed @Index { form-feed in plain text } +except the last. This character causes most printing devices to start +a new page, which is very useful when your page height is not exactly +right. +@PP +The @Code "@Document" symbol (Section {@NumberOf ordinary}) has an +unpaginated. @Index @Code "@Unpaginated" +@Code "@Unpaginated" option which, when set to {@Code "Yes"}, causes +the plain text output to appear unpaginated, that is, in one long +continous stream with no page breaks. Its value is ignored if plain text +output is not in effect, so it can be safely set to @Code "Yes" in +documents intended for formatting both ways. The usual margins apply; +footnotes appear at the end; figures and tables do not work. Lout +stupidly reads the entire document before producing any output when +this option is used, so if the document is long you might run out of memory. +@End @Section diff --git a/doc/user/typ_repo b/doc/user/typ_repo new file mode 100644 index 0000000..b73671a --- /dev/null +++ b/doc/user/typ_repo @@ -0,0 +1,359 @@ +@Section + @Title { Technical reports } + @Tag { reports } +@Begin +@PP +To make a technical report, +start off with the @Code "report" setup +reports. @Index { reports } +technical.reports. @Index { technical reports } +report. @Index @Code "@Report" +file and the @Code "@Report" symbol: +@ID @OneRow @Code { +"@SysInclude { report }" +"@Report" +" @Title {}" +" @Author {}" +" @Institution {}" +" @DateLine { No }" +" @AtEnd {}" +" @CoverSheet { Yes }" +" @ContentsSeparate { No }" +" @InitialFont { Times Base 12p }" +" @InitialBreak { hyphen adjust 1.2fx }" +" @InitialSpace { lout }" +" @InitialLanguage { English }" +" @PageOrientation { Portrait }" +" @PageHeaders { Simple }" +" @ColumnNumber { 1 }" +" @FirstPageNumber { 1 }" +" @OptimizePages { No }" +" @AbstractDisplay { Yes }" +" @AbstractTitle { Abstract }" +" @Abstract {}" +"//" +} +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. +} +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 +given at all. The meaning of the @Code "//" symbol is beyond our scope, +but disaster will ensue if it is forgotten. +@PP +The @Code "@Title" option holds the title of the report. It will be +printed using the @Code clines paragraph breaking style (Section +{@NumberOf paras}), which centres each line, so it makes sense +to have multi-line titles: +@ID @OneRow @Code { +"@Report" +" @Title {" +"The solution of real instances of" +"the timetabling problem" +"}" +" ..." +} +With a multi-line title, each line after the first should begin +at the left margin, not indented. It doesn't matter where the first +line begins, because space following an open brace is ignored. +@PP +The @Code "@Author" and @Code "@Institution" options hold the author's +name and institution or address, and will also be printed using the +@Code clines style. If there are several authors but only one +institution, list all the authors in the @Code "@Author" option: +@ID @Code "@Author { Tim B. Cooper and Jeffrey H. Kingston }" +With more authors, or with more than one institution, it is best to +ignore the @Code "@Institution" option and place all the information +within the @Code "@Author" option, enclosing institution information +in @Code "@I" symbols. In extreme cases, a table with columns of +authors might be necessary (Chapter {@NumberOf tables}). +@PP +@Code "@DateLine" may be set to {@Code No}, meaning no dateline, +{@Code Yes}, meaning print the current date, or anything else, which is +taken to be a date and printed: +@ID @Code "@DateLine { 4 July, 1776 }" +A good plan is to use @Code "@DateLine { Yes }" until +the report is finalized. +@PP +The {@Code "@AtEnd"} option will come out on a single unnumbered +page with no page headers or footers, and using the same margins as for +even pages, after the very last page of the report; even after the +index if there is one. It is intended to make it possible to +include a back cover, so @Code "@PageOf last.page" does not take +account of any @Code "@AtEnd" page. +@PP +The remaining options (except {@Code "@Abstract"}) are setup file options +(Section {@NumberOf setup}) that frequently need to be changed. If your +changes to the overall formatting are confined to these options, you can +change them here and avoid having your own setup file. If you already have +your own setup file, change them in either place and omit them in +the other. +@PP +If @Code "@CoverSheet" is {@Code Yes}, an unnumbered cover +cover.sheet. @Index @Code "@CoverSheet" +sheet will be produced containing the title, author, institution, +abstract, and dateline. Otherwise they will appear on the +first page. The `cover sheet' is in reality a sequence of Intro pages +(Section {@NumberOf headers}), numbered by default with Roman numerals +on pages after the first. +@PP +In order to get a table of contents, it is necessary to use your +own setup file (Section {@NumberOf setup} explains how to do this) +and to set the @Code "@MakeContents" option within it to +{@Code Yes}. The table of contents will ordinarily appear beginning +on the first page, but if the @Code "@ContentsSeparate" option of +@Code "@Report" is +contents.separate @Index @Code "@ContentsSeparate" +set to @Code "Yes" it will appear on separate pages. This is only +effective if @Code "@CoverSheet" is {@Code No}, since a separate cover +sheet and separate pages for the table of contents would leave nothing on +the first page. +@PP +@Code "@InitialFont" is the font of the bulk of the report, +and should contain a family, a face, and a size. The default +value selects the Times family, the Base face, and the 12 point size. +@PP +@Code "@InitialBreak" controls the behaviour of paragraph breaking in +the bulk of the report. It should have three parts: a paragraph +breaking style ({@Code adjust}, {@Code ragged}, etc.), an inter-line +spacing ({@Code "1.2fx"} for single spacing, {@Code "2.4fx"} for +double spacing, and so on), and either @Code "hyphen" or +@Code "nohyphen" for turning hyphenation on or off. It may also +have @Code "nobreakfirst" or @Code "nobreaklast" (or both), meaning +to disallow a page break after the first line of a paragraph, or +before the last, respectively. +@PP +@Code "@InitialSpace" determines how Lout treats white space between +two objects, as described in Section +{@NumberOf white}. @Code "@InitialLanguage" determines the language +of the bulk of the report. +@PP +@Code "@PageOrientation" determines the orientation of the page. Its +value may be {@Code Portrait} (the default), {@Code Landscape}, +{@Code ReversePortrait}, or {@Code ReverseLandscape}. See +Section {@NumberOf pagesize} for further details. +@PP +@Code "@PageHeaders" determines the appearance of page headers and +footers. Its value may be {@Code None}, +{@Code Simple}, {@Code Titles}, or {@Code NoTitles}. Section +{@NumberOf headers} has the details, but just briefly, {@Code None} +produces no page headers, {@Code Simple} produces a centred page number +between hyphens on every page except the cover sheet and the first +page, @Code Titles produces full running titles as in the present +document, and @Code "NoTitles" is like @Code "Titles" with the running +titles omitted, leaving just the page numbers. +@PP +@Code "@ColumnNumber" is the number of columns per page in the bulk of +the report, and may be anything from {@Code 1} (the default value) to +{@Code 10}. However, there is nothing analogous to the @Code "@FullWidth" +symbol of ordinary documents. Instead, the cover sheet, title material, +and all figures and tables will be printed full width, and the rest will +be set in columns. There is a separate @Code "@IndexColumnNumber" option +in the setup file which determines the number of columns in the index +(Section {@NumberOf indexes}). +@PP +@Code "@FirstPageNumber" is the page number given to the first page. +@PP +Lout ordinarily places lines onto a page until space runs out, then moves +to the next page and so on. This often produces ugly empty spaces at +the bottoms of pages preceding large unbreakable displays. Setting the +@Code "@OptimizePages" option to {@Code "Yes"} causes Lout to examine the +overall situation and try to minimize the ugliness, using the @TeX +optimal paragraph breaking algorithm. It takes two runs to do this, +with intermediate results stored in Lout's cross reference database +(Section {@NumberOf cross}); so deleting file {@Code lout.li} will reset +it, which might be wise after major changes. It is possible for the +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 +Finally we have three options that control the abstract. +@Code "@AbstractDisplay" may be @Code { Yes } or {@Code No}; +it determines whether the abstract is displayed (occupying +the full page width except for an indent at each side like a quoted +display) or inline (occupying the column width). +@Code "@AbstractTitle" is the title of the abstract; its default +value is @Code Abstract or its equivalent in the current language. +abstract. @Index @Code "@Abstract" +Finally, @Code "@Abstract" contains the abstract itself; it may be +empty or absent, in which case there will be no abstract. +@PP +The abstract may contain footnotes in the usual way. Regrettably, each +footnote in the abstract will generate one spurious `unresolved cross +reference' error message that does not go away. This slight problem +might be fixed in the future. +@PP +After the compulsory {@Code "//"} comes the report body in the +form of a sequence of sections: +section.reports @SubIndex { in reports } +@ID @OneRow @Code { +"@Section" +" @Title { Introduction }" +"@Begin" +"@PP" +"..." +"@End @Section" +} +No @Code "@BeginSections" or @Code "@EndSections" symbols are needed. The +beginsections.reports @SubIndex { in reports } +endsections.reports @SubIndex { in reports } +general rule is that you need these bracketing symbols only when you are +inside something else. Sections lie inside +@Code "@Text" in ordinary documents, but they don't lie inside anything +else in technical reports. +@PP +A section may have subsections, between +subsection.reports @SubIndex { in reports } +beginsubsections.reports @SubIndex { in reports } +endsubsections.reports @SubIndex { in reports } +@Code "@BeginSubSections" and {@Code "@EndSubSections"}: +@ID @OneRow @Code { +"preceding text" +"@BeginSubSections" +"@SubSection ... @End @SubSection" +"@SubSection ... @End @SubSection" +"..." +"@SubSection ... @End @SubSection" +"@EndSubSections" +} +Within each subsection there may be sub-subsections, each introduced +by {@Code "@SubSubSection"}, with the whole sequence bracketed by +subsubsection.reports @SubIndex { in reports } +beginsubsubsections.reports @SubIndex { in reports } +endsubsubsections.reports @SubIndex { in reports } +@Code "@BeginSubSubSections" and {@Code "@EndSubSubSections"}: +@ID @OneRow @Code { +"preceding text" +"@BeginSubSubSections" +"@SubSubSection ... @End @SubSubSection" +"@SubSubSection ... @End @SubSubSection" +"..." +"@SubSubSection ... @End @SubSubSection" +"@EndSubSubSections" +} +There are no sub-sub-subsections. +@PP +After the sections comes an optional sequence of appendices: +appendix.reports @SubIndex { in technical reports } +@ID @OneRow @Code { +"@Appendix" +" @Title { Derivation of the renewal formula }" +"@Begin" +"@PP" +"..." +"@End @Appendix" +} +No @Code "@BeginAppendices" or @Code "@EndAppendices" symbols are needed, +beginappendices.reports @SubIndex { in reports } +endappendices.reports @SubIndex { in reports } +because (like the sections above) these appendices do not lie inside +any other large-scale structure symbol. The appendices are numbered +A, B, C, etc., as is conventional for them. Within each appendix +there may be a sequence of subappendices, obtained with the +@Code "@SubAppendix" symbol and bracketed by @Code "@BeginSubAppendices" +subappendix.reports @SubIndex { in reports } +beginsubappendices.reports @SubIndex { in reports } +endsubappendices.reports @SubIndex { in reports } +and {@Code "@EndSubAppendices"}: +@ID @OneRow @Code { +"preceding text" +"@BeginSubAppendices" +"@SubAppendix ... @End @SubAppendix" +"@SubAppendix ... @End @SubAppendix" +"..." +"@SubAppendix ... @End @SubAppendix" +"@EndSubAppendices" +} +There are sub-subappendices following the same pattern, but no +subsubappendix.reports @SubIndex { in reports } +beginsubsubappendices.reports @SubIndex { in reports } +endsubsubappendices.reports @SubIndex { in reports } +sub-sub-subappendices. +@PP +The report ends with the last section or appendix; any reference list or +index will be appended automatically. Although we have described how to +create reports as though everything was in one large file, in practice it +is much better to divide the report into multiple files, following the +method given in Section {@NumberOf organizing}. +@PP +In addition to the {@Code "@Title"} option, each large-scale structure +symbol ({@Code "@Section"}, {@Code "@SubSection"}, {@Code "@SubSubSection"}, +{@Code "@Appendix"}, {@Code "@SubAppendix"}, +and {@Code "@SubSubAppendix"}) has a @Code "@Tag" option for cross +referencing (Section {@NumberOf cross}), an @Code "@InitialLanguage" +option for changing the language of that part of the document, and a +@Code "@RunningTitle" option which will be used in place of @Code "@Title" +in running headers if given. @Code "@RunningTitle" is useful when the +full title is rather long. +@PP +The features described in other chapters are all available within +technical reports. To get a table of contents, change the @Code +"@MakeContents" option in the setup file to {@Code Yes}; the rest is +automatic, and you don't need the @Code "@ContentsGoesHere" symbol from +ordinary documents. To get an index, again you need only change the +@Code "@MakeIndex" setup file option to {@Code Yes}. Endnotes and +references appear at the end of the report. Figures and tables are +numbered 1, 2, 3, etc. +@PP +Within the @Code "report" setup file there is a @Code "@ReportSetup" +symbol whose options control the appearance of features specific to +report.setup @Index @Code "@ReportSetup" +reports (in other words, the features described in this section). Section +{@NumberOf setup} explains setup files and their options in general; here +is a representative sample of these options, showing their default values: +@ID @OneRow @Code { +"@Use { @ReportSetup" +" # @CoverSheet { Yes }" +" # @DateLine { No }" +" # @ReferencesBeforeAppendices { No }" +" # @AbstractWord { abstract }" +" # @ContentsWord { contents }" +" # @SectionNumbers { Arabic }" +" # @SectionHeadingFont { Bold }" +" # @SectionGap { 2.00v }" +" # @SectionInContents { Yes }" +"}" +} +@Code "@CoverSheet" and @Code "@DateLine" are as for {@Code "@Report"}; +you can set them in either place as you prefer. @Code +"@ReferencesBeforeAppendices" determines whether the reference list is +printed out before or after any appendices. @Code "@AbstractWord" +determines the value of the title of the abstract if none is given there; +its default value, {@Code abstract}, produces `Abstract' in the current +language. @Code "@ContentsWord" is similar; its default value produces +`Contents' in the current language. The other four options +control the appearance of sections, and there are similar options for +controlling the other large-scale structure symbols. +@PP +@Code "@SectionNumbers" determines how sections will be numbered, and may +be @Code { None }, @Code { Arabic }, @Code { Roman }, @Code { UCRoman }, +@Code { Alpha }, or @Code { UCAlpha }. The default value is @Code Arabic +for sections, and also for all large-scale structure symbols except +appendices, for which it is {@Code UCAlpha}. This produces the appendices +numbered in upper-case letters (A, B, C, etc.) that were mentioned earlier. +@PP +@Code "@SectionHeadingFont" is the font used for section headings. The +default value shown above produces the bold face from the family of the +initial font. A family name and size is acceptable here as well: +@ID @Code "@SectionHeadingFont { Helvetica Base +2p }" +produces section headings in the Helvetica font, two points larger +than the initial font size. +@PP +@Code "@SectionGap" determines how much space is left blank before each +section title; the default value shown above is twice the current +inter-line spacing. The special value @Code "2b" may be used to get a +page break rather than a space. @Code "@SectionInContents" determines +whether or not an entry is made in the table of contents for each section; +it may be @Code Yes or {@Code No}. There are similar options for other +large-scale structure symbols. +@End @Section diff --git a/doc/user/vbas b/doc/user/vbas new file mode 100644 index 0000000..0004cfb --- /dev/null +++ b/doc/user/vbas @@ -0,0 +1,3 @@ +vi bas bas_star bas_objs bas_spac bas_char bas_empt bas_font bas_head \ + bas_par1 bas_par2 bas_line bas_hyph bas_unde bas_date bas_lang \ + bas_supe bas_verb bas_drop bas_conv diff --git a/doc/user/vfmt b/doc/user/vfmt new file mode 100644 index 0000000..39d5efe --- /dev/null +++ b/doc/user/vfmt @@ -0,0 +1 @@ +vi fmt fmt_setu fmt_size fmt_marg fmt_head diff --git a/doc/user/vref b/doc/user/vref new file mode 100644 index 0000000..55e3596 --- /dev/null +++ b/doc/user/vref @@ -0,0 +1 @@ +vi ref ref_sett ref_cite ref_labe ref_entr ref_chan ref_crea diff --git a/doc/user/vstr b/doc/user/vstr new file mode 100644 index 0000000..7f4e2d0 --- /dev/null +++ b/doc/user/vstr @@ -0,0 +1,2 @@ +vi str str_disp str_list str_foot str_marg str_theo str_figs str_larg \ + str_cros str_cont str_indx str_colu str_defs diff --git a/doc/user/vtbl b/doc/user/vtbl new file mode 100644 index 0000000..24f6a4d --- /dev/null +++ b/doc/user/vtbl @@ -0,0 +1,2 @@ +vi tbl tbl_intr tbl_cell tbl_rows tbl_marg tbl_widt tbl_inde tbl_rule \ + tbl_span tbl_mult tbl_alig tbl_mark tbl_plai tbl_setu tbl_summ diff --git a/doc/user/vtyp b/doc/user/vtyp new file mode 100644 index 0000000..003ff0b --- /dev/null +++ b/doc/user/vtyp @@ -0,0 +1,2 @@ +vi typ typ_ordi typ_repo typ_book typ_over typ_illu typ_plai \ + typ_apdf typ_orga |