diff options
Diffstat (limited to 'doc/user')
| -rw-r--r-- | doc/user/README | 21 | ||||
| -rw-r--r-- | doc/user/all | 8 | ||||
| -rw-r--r-- | doc/user/bas_font | 42 | ||||
| -rw-r--r-- | doc/user/bas_lang | 72 | ||||
| -rw-r--r-- | doc/user/bas_verb | 3 | ||||
| -rw-r--r-- | doc/user/bgr_colo | 31 | ||||
| -rw-r--r-- | doc/user/bgr_incl | 30 | ||||
| -rw-r--r-- | doc/user/bgr_scal | 16 | ||||
| -rw-r--r-- | doc/user/dia_erro | 36 | ||||
| -rw-r--r-- | doc/user/dia_summ | 166 | ||||
| -rw-r--r-- | doc/user/dia_tags | 22 | ||||
| -rw-r--r-- | doc/user/fmt_head | 2 | ||||
| -rw-r--r-- | doc/user/gra_data | 8 | ||||
| -rw-r--r-- | doc/user/gra_summ | 4 | ||||
| -rw-r--r-- | doc/user/preface | 5 | ||||
| -rw-r--r-- | doc/user/prg | 16 | ||||
| -rw-r--r-- | doc/user/ref_chan | 19 | ||||
| -rw-r--r-- | doc/user/ref_cite | 8 | ||||
| -rw-r--r-- | doc/user/str_cros | 51 | ||||
| -rw-r--r-- | doc/user/str_indx | 10 |
20 files changed, 479 insertions, 91 deletions
diff --git a/doc/user/README b/doc/user/README index 810f7ca..16f4db9 100644 --- a/doc/user/README +++ b/doc/user/README @@ -17,35 +17,28 @@ nearly all beginning with "unresolved cross reference". These should gradually go away on later runs. The following shows the error message output on the later runs for A4 size printing: -lout file "str_indx" (from "str" line 15, from "all" line 37): - 43,1: 0.3c object too high for -0.0c space; will try elsewhere lout file "typ_repo" (from "typ" line 19, from "all" line 38): 38,1: 1.0c object too high for 0.2c space; will try elsewhere -lout file "dia_synt" (from "dia" line 49, from "all" line 44): - 79,1: 1.0c object too high for 0.8c space; will try elsewhere -lout file "prg_tabs" (from "prg" line 102, from "all" line 46): +lout file "typ_over" (from "typ" line 21, from "all" line 38): + 8,1: 1.0c object too high for 0.0c space; will try elsewhere +lout file "prg_tabs" (from "prg" line 108, from "all" line 46): 58,23: prg2lout 2,1: program text ended within comment 60,35: prg2lout 2,1: program text ended within comment -The first three warnings are about footnotes whose first lines did not +The first two warnings are about footnotes whose first lines did not fit on the bottom of the current page, so had to begin on the following page. The last two warnings point to two places where a C program text ended inside a comment, which in these cases was deliberate. If you set the document in Letter size paper, you will also get different warning messages pointing to places where Lout had to slightly scale a display -to fit the smaller page: - -lout file "gra_summ" (from "gra" line 44, from "all" line 45): - 8,1: 23.6c object too high for 21.8c space; @Scale inserted -lout file "ap_qck" (from "all" line 48): - 158,25: 22.4c object too high for 21.9c space; @Scale inserted +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.24.user.ps.gz". +stored at "ftp://ftp.cs.su.oz.au/jeff/lout/lout-3.25.user.ps.gz". Jeffrey H. Kingston -8 October 2000 +24 December 2001 diff --git a/doc/user/all b/doc/user/all index d38a47c..bafac7a 100644 --- a/doc/user/all +++ b/doc/user/all @@ -8,8 +8,8 @@ @SysInclude { cprint } @SysInclude { eiffel } @SysInclude { perl } -# @SysInclude { book } -@Include { letterbook } # for testing Letter size formatting +@SysInclude { book } +# @Include { letterbook } # for testing Letter size formatting @SysDatabase @Reference { loutrefs } @@ -21,8 +21,8 @@ Lout Document Formatting System } @Author { Jeffrey H. Kingston } - @Edition { Version 3.24 -October, 2000 } + @Edition { Version 3.25 +September, 2001 } @Publisher { Copyright @CopyRight 1991, 2000 Jeffrey H. Kingston, Basser Department of Computer Science, diff --git a/doc/user/bas_font b/doc/user/bas_font index 65d711e..c59225f 100644 --- a/doc/user/bas_font +++ b/doc/user/bas_font @@ -479,7 +479,9 @@ 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 }. +and get @I @S { Hello World }. You can change the size of small +capitals using the @Code "@Font" or @Code "@InitialFont" symbols, +as described below. @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: @@ -596,6 +598,29 @@ 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 +If you switch font sizes in the middle of a line, as in +@ID @Code "Here's a 20p @Font big word" +you will discover one of Lout's obscure secrets: +@ID { Here's a 20p @Font big word } +Adjacent letters are aligned vertically through their middles, not +through the baseline, causing this awkward alignment. This was done +because it makes equation formatting easy, and examples like the above +look poor anyway. However, if you want to do this and so require +alignment through the baseline, you can get it, with the @Code baselinemark +option to the @Code "@Font" symbol like this: +@ID @Code "baselinemark @Font { Here's a 20p @Font big word }" +which produces +@ID @Code { baselinemark @Font { Here's a 20p @Font big word } } +If you want it this way throughout your document, you can put +@Code { baselinemark } in your initial font (see below). Lout's +equation formatter contains the opposite option, which is +@Code "xheight2mark @Font { ... }" +(meaning that the alignment goes through a point half the height of +an x character) so you won't disrupt equation formatting if you do +this, although you will have a problem if you put an equation inside +a paragraph, since its axis will be aligned with the baseline of +the adjacent words. +@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: @@ -617,6 +642,21 @@ 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 +The @Code "@InitialFont" option is also a good place to set the size +of small capitals if you don't like the default size that Lout gives +you: +@ID @Code "@InitialFont { Helvetica Base 10p setsmallcaps 0.9 }" +In this example we're asking for small capitals to have size 0.9 +times the height of ordinary capitals. The number following +@Code "setsmallcaps" is a ratio, not a length, so it carries no +unit of measurement. You can put @Code "setsmallcaps" in an ordinary +@Code "@Font" symbol too, if you like. For example, +@ID @Code "{ setsmallcaps 0.9 } @Font @S { Hello, world }" +has result +@ID { { setsmallcaps 0.9 } @Font @S { Hello, world } } +However for consistency most people would use @Code "setsmallcaps" only in +{@Code "@InitialFont"}, if at all. +@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 } diff --git a/doc/user/bas_lang b/doc/user/bas_lang index a4c33e9..fec9a63 100644 --- a/doc/user/bas_lang +++ b/doc/user/bas_lang @@ -33,29 +33,32 @@ 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 -Portuguese Português -Russian -Slovenian Slovenia Slovenija -Spanish Espa{@Char ntilde}ol -Swedish Svenska +Croatian Hrvatski +Czech Cesky Cestina cs +Danish Dansk da +Dutch Nederlands nl +English en +EnglishUK en-GB +Finnish Suomi fi +French Francais Fran{@Char ccedilla}ais fr +German Deutsch de +Hungarian Magyar hu +Italian Italiano it +Norwegian Norsk no +Polish Polski pl +Portuguese Português pt +Russian ru +Slovak Slovensky Slovencina +Slovenian Slovenia Slovenija sl +Spanish Espa{@Char ntilde}ol es +Swedish Svenska sv +UpperSorbian hornjoserbsce serbsce } -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. +File @Code "include/langdefs" in the distribution always has the exact +list of known languages. 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. @PP If your entire document is in a language other than English, you need to change the @Code "@InitialLanguage" option: @@ -65,8 +68,8 @@ 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 Latin2 character set, and -users of these languages have to place +Czech, Polish, and Slovenian (at least) use the Latin2 character set, +and users of these languages have to place @ID @Code "@SysInclude { latin2 }" at the start of their documents in order to get access to the Latin2 versions of the fonts. @@ -76,9 +79,24 @@ been corrected by getting Lout to generate output for these characters which prints their base letter and accent separately. } These have family names such as TimesCE, CourierCE, HelveticaCE, and so on (CE standing for Central European), to distinguish them from the same -fonts encoded in Latin1. The face names are unchanged. Consult -database file @Code "latin2.ld" in the standard database directory -for a complete list of these fonts. +fonts encoded in Latin1. The face names are unchanged. A typical +Latin2 document would therefore start off like this: +@ID @OneRow @Code { +"@SysInclude { latin2 }" +"@SysInclude { doc }" +"@Document" +" @InitialLanguage { Polish }" +" @InitialFont { TimesCE Base 12p }" +"//" +} +Depending on the document type there may be a few other font-setting +options in the setup file that need to be changed; in fact, it might be +best to produce your own setup file in this case, replacing {@Code "doc"}, +with the changed options in it. See Section {@NumberOf setup} for how +to do this. You could even start your setup file off with +@Code "@SysInclude { latin2 }" to avoid the trouble of typing it at +the top of every document. Consult database file @Code "latin2.ld" +in the standard database directory for a complete list of Latin2 fonts. @PP Russian uses Cyrillic characters. In principle, users of Russian have to place diff --git a/doc/user/bas_verb b/doc/user/bas_verb index 6da835a..d7f2904 100644 --- a/doc/user/bas_verb +++ b/doc/user/bas_verb @@ -37,13 +37,14 @@ 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. +other file. Braces do not have to be balanced in that 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 +raw.verbatim.sym @Index @Code "@RawVerbatim" as soon as a newline character is reached; in other words, it will preserve all white spaces following the first newline. @End @Section diff --git a/doc/user/bgr_colo b/doc/user/bgr_colo index 08d8d2a..7da8eeb 100644 --- a/doc/user/bgr_colo +++ b/doc/user/bgr_colo @@ -32,21 +32,28 @@ The @Code "@Colour" symbol will accept any of the following colours: @Rowb A { black } B { white } } Monochrome output devices will render them as shades of grey. Colouring -something @Code white makes it invisible, which is sometimes useful. +something @Code white makes it invisible (unless it is being printed +on a coloured background), 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. +colour called {@Code nochange} which produces whatever colour you already +happen to be using; you can also use an empty object to ask for this. And +you can get lots more colours by specifying them using numbers, like this: +@ID @Code "{ rgb 0.5 0.5 1.0 } @Colour { Hello, world }" +which means use red at intensity 0.5, green at intensity 0.5, and +blue at intensity 1.0, producing +@ID { rgb 0.5 0.5 1.0 } @Colour { Hello, world } +In the strange world of colour coordinates, in which 0 is dark and 1 is +light, this is a light blue. You can also use the CMYK system if you +know what that is: +@ID @Code "{ cmyk 0.5 0.5 1.0 1.0 } @Colour { Hello, world }" +produces +@ID { cmyk 0.5 0.5 1.0 1.0 } @Colour { Hello, world } +Wherever in this document it says that that you can use any colour +from this section, it means any of the names above, or {@Code nochange}, +or an object beginning with @Code "rgb" or @Code "cmyk" as shown. @PP Whether or not the colours produced by @Code "@Colour" actually 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. For example, -@ID @Code "{ 0.5 0.5 1.0 } @SetColour Hello" -prints @Code Hello in a colour containing red at intensity 0.5, green -at intensity 0.5, and blue at intensity 1.0, which turns out, in the -strange world of colour coordinates, to be a light blue. +nominal colour can look quite different on screen and on paper. @End @Section diff --git a/doc/user/bgr_incl b/doc/user/bgr_incl index 57ac4a1..0299b6d 100644 --- a/doc/user/bgr_incl +++ b/doc/user/bgr_incl @@ -44,4 +44,34 @@ page than would otherwise have been the case, and 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. +@PP +Sometimes you need to include the same EPS file many times, for +example once per page. If it is a large file it can make the +output file very large to include it over and over again. Lout +offers a solution to this problem, in the form of the +includegraphicrepeated. @Index @Code "@IncludeGraphicRepeated" +@Code "@IncludeGraphicRepeated" symbol. You place this at +the start of your document, like this for example: +@ID @Code { +"@Include { doc }" +"@IncludeGraphicRepeated { su_crest.eps }" +} +(note the braces around the following EPS file name). Adding +@Code "@IncludeGraphicRepeated" like this does not actually print the +graphic anywhere on any page; on the contrary, it is guaranteed to not +change the appearance of your document at all. What it does do +is give Lout a hint that the EPS file between the braces is likely +to be included many times over in this document. Lout then +handles this EPS file in a different way that involves copying it +into the PostScript output file just once, no matter how many +times it is included by subsequent @Code "@IncludeGraphic" symbols. +@PP +When your EPS file would otherwise be included many times over, using +@Code "@IncludeGraphicRepeated" definitely makes your PostScript +output file a lot shorter, and it usually makes it print faster as +well. On the other hand, {@Code "@IncludeGraphicRepeated"} uses +Level 2 PostScript features which some older printers may not have, +and it consumes a lot of memory in the printer. If memory runs out +your job will not print properly, so @Code "@IncludeGraphicRepeated" +must be used with caution. @End @Section diff --git a/doc/user/bgr_scal b/doc/user/bgr_scal index ad73f4c..37b6582 100644 --- a/doc/user/bgr_scal +++ b/doc/user/bgr_scal @@ -50,4 +50,20 @@ wide.scale @SubIndex { with @Code "@Scale" } produces @ID { 5c @Wide @Scale @Box WARNING! } which is 5 centimetres wide. +@PP +The @Code "@Scale" symbol will scale either up or down, whichever +is required to fit the available space. There is also a way to make +it scale down if necessary but never scale up, by giving the +@Code "downifneeded" keyword instead of an empty object: +@ID @Code "5c @Wide downifneeded @Scale @Box WARNING!" +produces no scaling: +@ID 5c @Wide downifneeded @Scale @Box WARNING! +but +@ID @Code "1c @Wide downifneeded @Scale @Box WARNING!" +does produce scaling: +@ID 1c @Wide downifneeded @Scale @Box WARNING! +This is a good option if scaling is being used when a display is +around the same width as the page; it scales only if this is +needed to fit the display into the column, not otherwise. +slig @End @Section diff --git a/doc/user/dia_erro b/doc/user/dia_erro index 2ad02d5..a04aae0 100644 --- a/doc/user/dia_erro +++ b/doc/user/dia_erro @@ -42,4 +42,40 @@ 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. +@PP +On other occasions your document might print without problems but you +see things that should not be there. Here is a typical example, +reported by a user: +@CD @Diag + margin { 0.3f } + outline { shadowbox } + shadow { 0.2f } + paint { lightyellow } + zindent { 0.4f } +{ + @Tbl + marginhorizontal { 0.55f } + aformat { @Cell A } + { + @Rowa + A { QEVENT:: @Node paint { lightblue } { QEvent } } + @Rowa + A { QIMEVENT:: @Node paint { lightblue } halign { right } { QIMEvent } } + @Rowa + A { QKEYEVENT:: @Node paint { lightblue } { QKeyEvent } } + } + // + @RVLCurveArrow from { QEVENT } to { QIMEVENT } bias { 1.5f } + @RVLCurveArrow from { QEVENT } to { QKEYEVENT } bias { 1.5f } +} +The problem here is the two short lengths of straight line protruding +backwards beyond the point where the arrow starts to curve. This has +occurred because the @Code TO labels are to the right of the point +where the curving begins; it can be corrected either by reducing the +@Code radius option, or else by decreasing @Code { zindent }. Ideally +@Code "@Diag" would adjust options for you so as to ensure that the +diagram always look good; but this is quite difficult to do, especially +when space to turn in is tight or there is a choice of which option to +adjust, as in the example above. So @Code "@Diag" just does a few +basic things and leaves the rest to you. @End @Section diff --git a/doc/user/dia_summ b/doc/user/dia_summ index 8bf3b1d..230b745 100644 --- a/doc/user/dia_summ +++ b/doc/user/dia_summ @@ -586,6 +586,11 @@ A:: @Circle /0.8c |1.5c B:: @Circle } } +@LII { +In the following links, the @Code radius option determines the +radius of the curved corners of the link. +} + @LI { @Code { "@Link" @@ -638,6 +643,12 @@ A:: @Circle /0.8c |1.5c B:: @Circle } } +@LII { +In the following links, the @Code bias option determines how far +the link extends to the left of the leftmost node, or to the +right of the rightmost node. +} + @LI { @Code { "@Link" @@ -744,6 +755,135 @@ A:: @Circle /0.8c |1.5c B:: @Circle } } +@LII { +In the following links, the @Code "hfrac" and @Code "hbias" options +determine how far across from @Code "FROM" to @Code "TO" the path turns +vertical: a fraction @Code "hfrac" of the way across, plus a distance +{@Code "hbias"}. The default settings shown make this point halfway; by +changing @Code "hfrac" to 0 and giving a length to {@Code "hbias"}, one can +select a particular distance, rather than a fraction of the total distance. +} + +@LI { +@Code { +"@Link" +" path { hvhline }" +" hfrac { 0.5 }" +" hbias { 0f }" +" radius { 1.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { hvhline } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { hvhline } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { hvhcurve }" +" hfrac { 0.5 }" +" hbias { 0f }" +" radius { 1.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /0.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { hvhcurve } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /0.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { hvhcurve } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { vhvline }" +" hfrac { 0.5 }" +" hbias { 0f }" +" radius { 1.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /1.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { vhvline } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /1.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { vhvline } from { A } to { B } +} +} + +@LI { +@Code { +"@Link" +" path { vhvcurve }" +" hfrac { 0.5 }" +" hbias { 0f }" +" radius { 1.0f }" +} +||6ct +@Diag { +//0.5f +A:: @Circle /1.8c |1.5c B:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { vhvcurve } from { A } to { B } +} +&2.5c +@Diag { +//0.5f +|1.5c B:: @Circle /1.8c A:: @Circle +// +@ShowTags @Link + pathstyle { solid dashed } + path { vhvcurve } from { A } to { B } +} +} + +@LII { +In the following links, the @Code "fbias" option determines +how far the curve extends away from the FROM node; the +@Code "tbias" option determines how far it extends away from +the TO node; and the @Code "bias" option determines how far +it extends above the higher or below the lower node. +} + @LI { @Code { "@Link" @@ -928,6 +1068,23 @@ path also has an abbreviation which adds a forward arrow: C { RVLCurveArrow } @Rowa + A { hvhline } + B { HVHLine } + C { HVHArrow } +@Rowa + A { vhvline } + B { VHVLine } + C { VHVArrow } +@Rowa + A { hvhcurve } + B { HVHCurve } + C { HVHCurveArrow } +@Rowa + A { vhvcurve } + B { VHVCurve } + C { VHVCurveArrow } + +@Rowa A { dwrapline } B { DWrapLine } C { DWrapArrow } @@ -966,6 +1123,7 @@ have been omitted where they are the same as the {@Code linklabel} options. {@Code "ccurve"}, {@Code "bezier"}, {@Code "vhline"}, {@Code "hvline"}, {@Code "vhcurve"}, {@Code "hvcurve"}, {@Code "lvrline"}, {@Code "rvlline"}, {@Code "lvrcurve"}, {@Code "rvlcurve"}, +{@Code "hvhline"}, {@Code "vhvline"}, {@Code "hvhcurve"}, {@Code "vhvcurve"}, {@Code "dwrapline"}, {@Code "uwrapline"}, {@Code "dwrapcurve"}, {@Code "uwrapcurve"}, or any path } @Rowa @@ -989,6 +1147,14 @@ have been omitted where they are the same as the {@Code linklabel} options. B { 2.0f } C { any @I length } @Rowa + A { " hfrac"} + B { 0.5 } + C { any fractional @I number } +@Rowa + A { " hbias"} + B { 0.0f } + C { any @I length } +@Rowa A { " radius"} B { 1.0f } C { any @I length } diff --git a/doc/user/dia_tags b/doc/user/dia_tags index 91cd7a1..86f22e3 100644 --- a/doc/user/dia_tags +++ b/doc/user/dia_tags @@ -165,4 +165,26 @@ 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. +@PP +The @Code "::" symbol has a @Code restrict option which can be +used to save printer memory in deeply nested structures (such as +the syntax diagrams of Section {@NumberOf dia_synt}) by restricting +the tags promoted by @Code "::" to a limited set: +@ID { +@Code { +"A:: restrict { (E) (W) } @Ellipse" +} +||7ct +@Diag { +@ShowTags { + A:: restrict { (E) (W) } @Ellipse + vsize { 1.5c } + hsize { 3.0c } + } +} +} +The tags to be preserved appear within the @Code restrict option, each +enclosed in parentheses. Care is needed with this option: all of +the listed tags must actually exist in the following object. If not, the +result will be a PostScript error mentioning the @Code get command. @End @Section diff --git a/doc/user/fmt_head b/doc/user/fmt_head index ed1f487..31f6d89 100644 --- a/doc/user/fmt_head +++ b/doc/user/fmt_head @@ -273,7 +273,7 @@ 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 +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" diff --git a/doc/user/gra_data b/doc/user/gra_data index 323f155..049a644 100644 --- a/doc/user/gra_data +++ b/doc/user/gra_data @@ -217,7 +217,7 @@ option: "@Data" " colour { blue }" } -For the complete list of acceptable colour names, see Section +For the complete list of acceptable colours, see Section {@NumberOf colour}. The @Code "colour" option's name may also be spelt @Code {"color"}. @PP @@ -262,6 +262,8 @@ the original input had been "}" } 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. +default value, {@Code "xandy"}, gives the usual interpretation, and +{@Code "swapxandy"} exchanges adjacent pairs of numbers in the data, so +that the data is interpreted as @E { (y, x) } pairs rather than @E { (x, y) } +pairs. The layout of data on lines has no effect on the interpretation. @End @Section diff --git a/doc/user/gra_summ b/doc/user/gra_summ index ea074b9..8039440 100644 --- a/doc/user/gra_summ +++ b/doc/user/gra_summ @@ -168,7 +168,7 @@ automatic } @Rowa A { "colour/color" } B { none } - C { {@Code none} or any colour name from Section {@NumberOf colour}} + C { {@Code none} or any colour from Section {@NumberOf colour}} @Rowa A { paint } B { no } @@ -176,7 +176,7 @@ automatic } @Rowa A { dataformat } B { xandy } - C { {@Code xandy}, {@Code yonly}, {@Code xonly} } + C { {@Code xandy}, {@Code yonly}, {@Code xonly}, {@Code swapxandy} } @Rowa A { dashlength } B { 0.2 ft } diff --git a/doc/user/preface b/doc/user/preface index 2b1c1b0..ff16e97 100644 --- a/doc/user/preface +++ b/doc/user/preface @@ -18,7 +18,7 @@ gnu. @Index { GNU Public License } primary source is directory @ID @Code "ftp://ftp.cs.usyd.edu.au/jeff/lout" in which may be found a gzipped tar file containing the main distribution -(currently {@Code "lout-3.24.tar.gz"}), and various other things including +(currently {@Code "lout-3.25.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 @@ -61,7 +61,8 @@ hope that seeing their ideas adopted will be thanks enough. @DP @RLD lines @Break { Jeffrey H. Kingston -Basser Department of Computer Science +School of Information Technologies +(formerly Basser Department of Computer Science) The University of Sydney 2006, Australia @Code "jeff@cs.usyd.edu.au" } diff --git a/doc/user/prg b/doc/user/prg index d22a7b2..3a862b3 100644 --- a/doc/user/prg +++ b/doc/user/prg @@ -46,6 +46,12 @@ pod. @Index { Pod (for Perl) printing } D { Default style } E { ` ' escapes } @Rowb + A { Blue } + B { blue } + C { "@Blue" } + D { varying } + E { Yes } +@Rowb A { C, C++ } B { cprint } C { "@CP" } @@ -58,11 +64,11 @@ pod. @Index { Pod (for Perl) printing } D { varying } E { Yes } @Rowb - A { Blue } - B { blue } - C { "@Blue" } - D { varying } - E { Yes } + A { Java } + B { java } + C { "@Java" } + D { fixed } + E { No } @Rowb A { Perl } B { perl } diff --git a/doc/user/ref_chan b/doc/user/ref_chan index f7114fb..befc860 100644 --- a/doc/user/ref_chan +++ b/doc/user/ref_chan @@ -173,12 +173,22 @@ 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 +sorts by tag. Another 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. +to the citation if there is one. To sort by order of first citation, use +@ID @Code "@RefListSortKey { @CiteOrder }" +@Code "@CiteOrder" is implemented in a quick and dirty way, and there +are a couple of problems to watch out for if you use it. First, +when you cite references more than once you get some strange +intermediate error messages and results. All such problems will +be gone by the end of the fifth run. Second, if you insert +more citations later on, you will need to restart the whole process, +by deleting the cross reference index file {@I lout.li}, since any +late insertions get erroneously stuck on the end instead of inserted +in the correct order. If things go haywire, delete {@I lout.li} then +do five runs and they should be right again. @PP @Code "@RefListSortKey" may be any sequence of words and options from the @Code "@Reference" symbol, but not @Code "@RefNum" @@ -189,7 +199,8 @@ 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"}. +sorting keys other than {@Code "@Tag"}, {@Code "@Label"}, and +{@Code "@CiteOrder"}. @PP A colon within the @Code "@RefListSortKey" option is converted by Lout into a character smaller than any printable character, which ensures that diff --git a/doc/user/ref_cite b/doc/user/ref_cite index 89958b9..7746841 100644 --- a/doc/user/ref_cite +++ b/doc/user/ref_cite @@ -48,14 +48,16 @@ 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 }." +"... our scope @NoCite { $kingston1995lout.expert $kingston1993lout.design }." } produces @ID { -... our scope @NoCite { $kingston1995lout.expert, $kingston1993lout.design }. +... 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 +references will nevertheless appear in the reference list as usual. Note +that if you put commas between the references inside @Code "@NoCite" you +will get commas in the output (so don't). There is a @Code "@NoChapCite" symbol that combines @Code "@NoCite" and no.chap.cite @Index @Code "@NoChapCite" {@Code "@ChapCite"}. For compatibility with previous versions of Lout, diff --git a/doc/user/str_cros b/doc/user/str_cros index 4bb391d..bbabfc9 100644 --- a/doc/user/str_cros +++ b/doc/user/str_cros @@ -80,6 +80,20 @@ produces For further information on this point, please consult Section @NumberOf cross (page @PageOf { cross }). } +For symbols with a @Code "@Title" option (chapters, sections, etc.) +there is also the @Code "@TitleOf" symbol: +@ID @OneRow @Code { +"For further information on this point, please consult" +"the @TitleOf { cross } section." +} +produces +@QD { +"For further information on this point, please consult" +"the @TitleOf { cross } section." +} +But this symbol won't work for footnotes, list items, and other +things without a title. +@PP 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 @@ -115,11 +129,12 @@ version of cross references called {@I links}, which allow the user to click on, say, the entry for a section in a table of contents and be immediately transported to the page on which that section begins. In principle, anything could happen when a link is clicked on, but Lout -only offers the kind of link that transports the user to some page -in the current document. +only offers two kinds of links: @I { internal links } that transport +the user to some page in the current document, and @I { external +links } that transports the user to a URL location on the World Wide Web. @PP -Lout automatically makes a link out of every page number it prints -in the table of contents and in the index, and every reference +Lout automatically makes an internal link out of every page number it +prints in the table of contents and in the index, and every reference citation. You can also insert your own links, using the @Code "@CrossLink" symbol like this: @ID @Code "See cross @CrossLink { Section @NumberOf cross }" @@ -169,11 +184,25 @@ to the right of @Code "@CrossLink" can be an arbitrary Lout object: However, in this form the @Code "@CrossLinkFormat" setup file option is still applied. @PP -At present, the @Code "@CrossLink" symbol behaves as though a @Code "@OneCol" -symbol encloses the object on its right. This means that that object -is kept together on one line of any enclosing paragraph, and inter-word -spaces within it are not adjusted along with the inter-word spaces of -any enclosing paragraph. This deficiency might be corrected in the -future, but meanwhile it means that it is best to keep your objects -on the right short. +External links are obtained in much the same way as internal ones, +except that the symbol to use is @Code "@ExternalLink" and instead +of supplying a tag, you need to supply a URL: +@ID @Code { +"\"http://snark.ptc.spbu.ru/~uwe/lout/lout.html\" @ExternalLink { Lout Home Page }" +} +Once again the result is the object to the right, modified by any +@Code "@Format" option; and there is an {@Code "@ExternalLinkFormat"} +setup file option that works in the same way as +{@Code "@CrossLinkFormat"}. This time, though, the effect is to +jump right out of your document to the given place on the World +Wide Web, assuming that the software you are using to display your +document is capable of such a thing. +@PP +At present, the @Code "@CrossLink" and @Code "@ExternalLink" symbols +behave as though a @Code "@OneCol" symbol encloses the object to their +right. This means that that object is kept together on one line of any +enclosing paragraph, and inter-word spaces within it are not adjusted +along with the inter-word spaces of any enclosing paragraph. This +deficiency might be corrected in the future, but meanwhile it means +that it is best to keep your objects on the right short. @End @Section diff --git a/doc/user/str_indx b/doc/user/str_indx index b75c8db..be6ca5d 100644 --- a/doc/user/str_indx +++ b/doc/user/str_indx @@ -258,6 +258,7 @@ There are eight setup file options for the index. Here they are with their default values: @ID @OneRow @Code @Verbatim { @MakeIndex { No } +@IndexText { @Null } @IndexFont { } @IndexBreak { oragged 1.2fx } @IndexColumnNumber { 2 } @@ -273,6 +274,12 @@ 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 "@IndexText" is some text to put at the start of the index, +after the heading but before any index entries. It will appear +full width on the page. This option is also available as an option +of the {@Code "@Document"}, {@Code "@Report"}, and {@Code "@Book"} +symbols. +@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 @@ -320,7 +327,8 @@ 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. +will insert the usual 25 blank entries into index B. There are +setup file options to change the titles of indexes. @PP In large projects it might help to rename the @Code "@IndexA" symbol to something else, such as {@Code "@AuthorIndex"}. This can |