diff options
Diffstat (limited to 'doc/user')
82 files changed, 700 insertions, 607 deletions
diff --git a/doc/user/README b/doc/user/README index 6278f75..ec748d8 100644 --- a/doc/user/README +++ b/doc/user/README @@ -1,31 +1,38 @@ 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 +This directory contains the Lout source files for the User's +Guide to the Lout Document Formatting System. A copy of the +final PostScript output file (A4 paper size) is stored at - lout -r6 all > user.ps + http://jeffreykingston.id.au/lout -in this directory. The -r6 flag causes Lout to run over the -document six times. This is needed to completely resolve all +To produce the Guide yourself, type the command + + lout -r5 all > user.ps + +in this directory. The -r5 flag causes Lout to run over the +document five times. This is needed to completely resolve all cross references, although a readable PostScript file would be produced after one run if -r was omitted. Auxiliary files with -.li and .ld suffixes will be created in this directory. Six runs -is an unusually large number; it is owing to some unfortunate page -breaks in the early runs that so many runs are needed. +.li and .ld suffixes will be created in this directory. + +Slight changes (e.g. to Letter paper size) could easily cause +the number of required runs to increase. I've kept it down +to 5 by rewriting to eliminate cases where the number of pages +consumed by a chapter varies from run to run. 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 last run for A4 size printing: +error message output on the fifth run for A4 size printing: lout: - : lout -r beginning run 6: + : lout -r beginning run 5: lout file "gra_tick" (from "gra" line 38, from "all" line 46): - 234,1: 23.7c object too high for 23.7c space; @Scale inserted + 234,1: 23.7c object too high for 23.6c space; @Scale inserted lout file "gra_summ" (from "gra" line 44, from "all" line 46): 10,1: 25.7c object too high for 23.6c space; @Scale inserted -lout file "prg_tabs" (from "prg" line 139, from "all" line 48): +lout file "prg_tabs" (from "prg" line 152, from "all" line 48): 66,23: prg2lout 2,1: program text ended within comment 68,35: prg2lout 2,1: program text ended within comment @@ -36,11 +43,9 @@ these cases was deliberate. If you set the document in Letter size paper, you will get a somewhat different set of warning messages. 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.it.usyd.edu.au/jeff/lout/lout-3.39.user.ps.gz". +failure to converge, caused by footnotes and floating figures close +to large unbreakable displays. Jeffrey H. Kingston -21 September 2010 +26 June 2013 +19 June 2023 diff --git a/doc/user/all b/doc/user/all index 23410b2..bf7349d 100644 --- a/doc/user/all +++ b/doc/user/all @@ -22,10 +22,10 @@ Lout Document Formatting System } @Author { Jeffrey H. Kingston } - @Edition { Version 3.39 -September 2010 } + @Edition { Version 3.41 +June 2023 } @Publisher { -Copyright @CopyRight 1991, 2008 Jeffrey H. Kingston, +Copyright @CopyRight 1991, 2023 Jeffrey H. Kingston, School of Information Technologies, The University of Sydney 2006, Australia. ISBN 0 86758 951 5. } diff --git a/doc/user/ap_col b/doc/user/ap_col index 36306d1..495deea 100644 --- a/doc/user/ap_col +++ b/doc/user/ap_col @@ -1,5 +1,5 @@ @Appendix - @Title { Lots more colours } + @Title { Lots More Colours } @Tag { morecolours } @Begin Here is the long list of extra colours, said to be from the diff --git a/doc/user/ap_qck b/doc/user/ap_qck index 092673d..531e63d 100644 --- a/doc/user/ap_qck +++ b/doc/user/ap_qck @@ -27,7 +27,6 @@ " @InitialFont { Times Base 12p }" " @InitialBreak { adjust 1.2fx hyphen }" " @InitialLanguage { English }" -" @PageHeaders { Simple }" " @FirstPageNumber { 1 }" " @ColumnNumber { 1 }" " @PageOrientation { Portrait }" @@ -69,7 +68,6 @@ B { @LI @Code { "@Section" " @Title { ... }" -" @RunningTitle { ... }" " @Tag { ... }" "@Begin" "@PP" diff --git a/doc/user/bas_char b/doc/user/bas_char index 3805021..58f25a2 100644 --- a/doc/user/bas_char +++ b/doc/user/bas_char @@ -575,7 +575,7 @@ author's viewer has this problem, for example, but his printer doesn't. The easiest way to get a dingbat is to write, for example, @ID @Code "@Ding a123" which produces the dingbat with the given name from the table -above. This is just a shorthand for +above. This is just a short for @ID @Code @Verbatim { { Dingbats Base } @Font { @Char a123 } } @@ -598,6 +598,6 @@ symbol, although they aren't ISO-LATIN-1 characters. @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. +Most of these are also listed as `characters important enough to +deserve their own symbols'. @End @Section diff --git a/doc/user/bas_conv b/doc/user/bas_conv index 492f306..bad4ed7 100644 --- a/doc/user/bas_conv +++ b/doc/user/bas_conv @@ -56,9 +56,9 @@ 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. +You must use a paragraph symbol, such as @Code "@PP" or {@Code "@LP"}, +to separate 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 @@ -69,7 +69,7 @@ space). For example, 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. +the result. However, @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_font b/doc/user/bas_font index dd8442d..631ecfd 100644 --- a/doc/user/bas_font +++ b/doc/user/bas_font @@ -3,8 +3,8 @@ @Tag { fonts } @Begin @PP -A @I font is a collection of characters that may be printed. For -example, here is the Times Roman font: +A @I font is a collection of printable characters. For example, here +is the Times Roman font: @ID @OneRow { Times Base } @Font 0.05c @Space { { @Char space } { @Char exclam } @@ -609,10 +609,10 @@ alignment through the baseline, you can get it, with the @Code baselinemark option to the @Code "@Font" symbol: @ID @Code "baselinemark @Font { Here's a 20p @Font big word }" which produces -@ID @Code { baselinemark @Font { Here's a 20p @Font big word } } -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 +@ID baselinemark @Font { Here's a 20p @Font big word } +If you want it this way throughout your document, you can get it by +putting @Code { baselinemark } in your initial font (see below). +Lout's equation formatter contains the opposite option, which is @Code "xheight2mark @Font { ... }" (which aligns through a point half the height of an x character) so you won't disrupt equation formatting if you do @@ -654,10 +654,9 @@ has result 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 +@I Ligatures are sequences of two or more letters run together; the ligatures. @Index { ligatures } -common ligatures are `fi' and `fl.' @I Kerning is moving adjacent +most 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 diff --git a/doc/user/bas_lang b/doc/user/bas_lang index 7c6ac09..9e36cea 100644 --- a/doc/user/bas_lang +++ b/doc/user/bas_lang @@ -93,8 +93,8 @@ at the start of their documents in order to get access to the Latin2 versions of the fonts. @FootNote { Prior to Version 3.21 of Lout, some accented characters were missing from these Latin2 fonts, but this deficiency has now -been corrected by getting Lout to generate output for these characters -which prints their base letter and accent separately. } These have +been corrected. Lout generates 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. A typical diff --git a/doc/user/bas_line b/doc/user/bas_line index 3210cdc..7861112 100644 --- a/doc/user/bas_line +++ b/doc/user/bas_line @@ -37,7 +37,7 @@ 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. +for 14 point, @Code "0.5cx" for 0.5 centimetres, etc. But don't use +the @Code "v" unit, 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_par2 b/doc/user/bas_par2 index f57a0ef..f26ec9e 100644 --- a/doc/user/bas_par2 +++ b/doc/user/bas_par2 @@ -25,10 +25,10 @@ breakzzz.sym @Index { @Code "@Break" symbol } This example causes every paragraph in the following object to be broken using the @Code ragged style, of which more below. @PP -The first two of the ten styles perform @I { line adjustment }, which +The first two 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: +line except the last so as to fill the lines completely: @IndentedList @LI @Tab @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B } @@ -124,7 +124,7 @@ is like @Code "outdent" except the resulting lines are not adjusted. 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: +recommended way is to separate them by the @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. @@ -208,10 +208,10 @@ Or to keep off envies stinging, 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. 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: +input lines; as the result shows, such indents will be respected. +However, Lout's rule that only white space separating objects +affects the result (Section {@NumberOf spaces}) still holds, so +indenting the first line is not effective: @ID @OneRow @Code { "@IndentedDisplay lines @Break @I {" " And finde" @@ -225,12 +225,12 @@ produces 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}): +This may seem awkward, but actually it is very 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" diff --git a/doc/user/bas_star b/doc/user/bas_star index ec6eb3b..512148a 100644 --- a/doc/user/bas_star +++ b/doc/user/bas_star @@ -105,9 +105,9 @@ errors. @Index { errors } @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. +they will gradually go away. Of course, if you see messages about missing +braces, unknown symbols, and so on, you need to revise your file. Lout will +give 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 diff --git a/doc/user/bgr_boxs b/doc/user/bgr_boxs index 5e275cf..c75b059 100644 --- a/doc/user/bgr_boxs +++ b/doc/user/bgr_boxs @@ -55,9 +55,9 @@ produces } 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 +has width zero. If you draw very 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 +is empty, which produces whatever width the PostScript interpreter in your output device thinks is a good default value. The special value @Code "none" for @Code "linewidth" ensures that no line is drawn around the box at all. @@ -76,8 +76,8 @@ 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: +makes a box painted in whatever colour we are 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. @@ -131,11 +131,11 @@ black @Colour striped @Texture angle { 45d } darkgrey @Colour striped @Texture scale { 2 } 50p @Font ABC } The outline colour and texture are the colour and texture from outside -the box; the background colour and texture are always determined by the +the box; the background colour and texture are determined by the @Code paint and @Code texture options; and the colour and texture of the contents are inherited from outside the box, but can be changed as -shown if desired. Notice what happens when two textures overstrike: the -lower one shows through the unpainted parts of the upper one. +shown if desired. When two textures overstrike, the lower one shows +through the unpainted parts of the upper one. @PP There are @Code "@CurveBox" and @Code "@ShadowBox" symbols that curvebox. @Index @Code "@CurveBox" @@ -172,15 +172,15 @@ 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" +Two symbols make horizontal rules. @Code "@FullWidthRule" fullwidthrule. @Index @Code "@FullWidthRule" rules. @Index rules -produces a rule which occupies the full page (or column) width: +makes a rule which occupies the full page (or column) width, +or (more precisely) as much horizontal space as it legally can: @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. +@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" diff --git a/doc/user/bgr_clip b/doc/user/bgr_clip index 696668a..dc31f66 100644 --- a/doc/user/bgr_clip +++ b/doc/user/bgr_clip @@ -15,7 +15,6 @@ produces The following object may be arbitrary as usual; for example, it could be an illustration included using @Code "@IncludeGraphic" (Section {@NumberOf include}). -@PP We have used the @Code "@Wide" symbol from Section {@NumberOf precise} to make clear what the available width is in this small example (one centimetre), but @Code "@HClip" will work in any context; for example, @@ -45,6 +44,6 @@ produces @ID { @Box 1c @Wide 0.2c @High @HClip @VClip WARNING! } -The @Code "shift" options may be used as usual to determine which part of -the two-dimensional area is displayed. +The @Code "shift" options to determine which part of the two-dimensional +area is displayed, as usual. @End @Section diff --git a/doc/user/bgr_colo b/doc/user/bgr_colo index ca4f019..90d95fd 100644 --- a/doc/user/bgr_colo +++ b/doc/user/bgr_colo @@ -53,8 +53,8 @@ produces 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 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. +# @PP +# Whether the colours produced by @Code "@Colour" actually +# correspond with the names depends on the output device; the same +# nominal colour can look quite different on screen and on paper. @End @Section diff --git a/doc/user/bgr_outl b/doc/user/bgr_outl index af11eb1..226683d 100644 --- a/doc/user/bgr_outl +++ b/doc/user/bgr_outl @@ -9,7 +9,7 @@ causes all the words in the following object (which may be arbitrary as usual) to be printed in outline. For example, @ID @Code @Verbatim { @Outline @Box 24p @Font HELP } produces -@ID @Outline @Box 24p @Font HELP +@ID @Outline @Box 18p @Font HELP There is no way to control the thickness of the outline, and @@Outline has no effect in PDF output. On the other hand, it works with any font likely to be used in practice. diff --git a/doc/user/bgr_prec b/doc/user/bgr_prec index 737d9c9..d4f70d1 100644 --- a/doc/user/bgr_prec +++ b/doc/user/bgr_prec @@ -8,8 +8,8 @@ them relative to each other. If your problem is to place objects precisely at some unusual point on the page, you probably need a margin note or the @Code "@Place" symbol, for which see Section {@NumberOf marginnotes}. @PP -Precise object placement is not a subject with any clear boundaries, so -this section is mainly a list of examples, covering the use of the +Precise object placement is not a subject with clear boundaries, so +this section is mainly a list of examples, covering the @Code {"@OneCol"}, @Code {"@OneRow"}, @Code {"@Wide"}, @Code {"@High"}, @Code {"@HExpand"}, @Code {"@VExpand"}, @Code {"@HShift"}, @Code {"@VShift"}, @Code {"@VStrut"}, @Code {"@OverStrike"}, @Code {"@ZeroHeight"}, diff --git a/doc/user/bgr_rota b/doc/user/bgr_rota index 202d129..002af2d 100644 --- a/doc/user/bgr_rota +++ b/doc/user/bgr_rota @@ -5,9 +5,9 @@ @PP The @Code "@Rotate" symbol rotates the following object by any positive rotate. @Index @Code "@Rotate" -or negative angle, measured in degrees: +or negative angle: @ID @Code "45d @Rotate @Box WARNING!" -has result +The angle is measured in degrees. The result here is @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 @@ -17,14 +17,14 @@ using the @Code "@Wide" symbol from Section {@NumberOf precise}: wide. @RawIndex { @Code "@Wide" } wide.rotate @SubIndex { with @Code "@Rotate" } @ID @OneRow @Code @Verbatim { --90d @Rotate 4.5c @Wide { +-90d @Rotate 4c @Wide { Papal initiatives and influence from the crowning of Charlemagne to the First Crusade } } The result here is @ID { --90d @Rotate 4.5c @Wide { +-90d @Rotate 4c @Wide { Papal initiatives and influence from the crowning of Charlemagne to the First Crusade } diff --git a/doc/user/bgr_text b/doc/user/bgr_text index 286698a..5f76227 100644 --- a/doc/user/bgr_text +++ b/doc/user/bgr_text @@ -194,7 +194,7 @@ The characters to be displayed } This last example seems like a good one for experimenting with -the {@Code hshift} and {@Code vshift} options, so here goes: +the {@Code hshift} and {@Code vshift} options: texture.sym.hshift @SubIndex { @Code "hshift" option } texture.sym.vshift @SubIndex { @Code "vshift" option } @ID @OneRow @Tbl diff --git a/doc/user/dia b/doc/user/dia index 5e7e966..e23d5a8 100644 --- a/doc/user/dia +++ b/doc/user/dia @@ -6,22 +6,22 @@ This chapter describes how to use the @@Diag symbol diagrams. @RawIndex { diagrams } diag.diagrams @Index { @Code "@Diag" (diagrams) } -@FootNote { -Starting with Version 3.18 of Lout, the @@Diag symbol was enhanced with -the {@Code "@ANode"}, {@Code "@BNode"}, and {@Code "@CNode"} symbols -described in Section {@NumberOf dia_node}, and with the symbols for -syntax diagrams described in Section {@NumberOf dia_synt}. +# @FootNote { +# Starting with Version 3.18 of Lout, the @@Diag symbol was enhanced with +# the {@Code "@ANode"}, {@Code "@BNode"}, and {@Code "@CNode"} symbols +# described in Section {@NumberOf dia_node}, and with the symbols for +# syntax diagrams described in Section {@NumberOf dia_synt}. #These #enhancements are upwardly compatible, unless the user has defined #symbols with these same names and used them within diagrams. -@LP -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. -} +# @LP +# 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 diff --git a/doc/user/dia_intr b/doc/user/dia_intr index 02ab5b2..1aa8c66 100644 --- a/doc/user/dia_intr +++ b/doc/user/dia_intr @@ -24,11 +24,7 @@ Change this to 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: +is commonly made into a floating figure, like this: @ID @OneRow @Code { "@Figure" " @Caption { ... }" @@ -36,10 +32,15 @@ or into a floating figure, like this: " ..." "}" } +or into a centred display, like this: +@ID @OneRow @Code { +"@CentredDisplay @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 }: +Although it is not compulsory, most uses of @@Diag contain a +@I { nodes part } and a @I { links part }: @ID @OneRow lines @Break { @Code "@Diag {" @I { nodes part } diff --git a/doc/user/dia_labe b/doc/user/dia_labe index 18b1d80..3bc647a 100644 --- a/doc/user/dia_labe +++ b/doc/user/dia_labe @@ -117,13 +117,30 @@ arrowheads to links: 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 +@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. +just {@Code xlabel} near the start, {@Code ylabel} in the middle, and +{@Code zlabel} near the end; but when you need different arrowheads, or +arrowheads in a different colour from the rest of the arrow: +@ID { +@Code @Verbatim { +@Link + tolabel { red @Colour @SolidArrowHead } +} +||9ct +@VContract @Diag { +3c @Wide 1c @High +// +@Link + from { 0 0 } + to { 1,1 } + tolabel { red @Colour @SolidArrowHead } +} +} +{@Code fromlabel} and {@Code tolabel} are the answer. @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 diff --git a/doc/user/dia_link b/doc/user/dia_link index 2c96a8c..d20a451 100644 --- a/doc/user/dia_link +++ b/doc/user/dia_link @@ -19,7 +19,7 @@ given by a {@Code path} option: diagrams. @RawIndex { diagrams } diagrams.path @SubIndex { @Code "path" option } path.diagrams @Index { @Code "path" option (diagrams) } -@ID @Code @Verbatim { +@ID @OneRow @Code @Verbatim { @Link path { ... } from { ... } @@ -30,9 +30,11 @@ Unlike {@Code "@Node"}, {@Code "@Link"} has no following object. 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: +(Section {@NumberOf dia_summ}). Here is a sample: @ID @Tab - @Fmta { @Col @Code { path "{" A "}" } ! @Col ! @Col B } + @Fmta { @Col @Code { path "{" A "}" } ! @Col ! @Col B ! + @Col 0.5c @Wide ! @Col @Code { path "{" C "}" } ! @Col ! @Col D + } { @Rowa @@ -43,10 +45,8 @@ A:: @Circle //1c ||2c B:: @Circle // @Link from { A } to { B } path { line } arrow { yes } } } - -@Rowa - A { acurve } - B { + C { acurve } + D { @Diag { A:: @Circle //1c ||2c B:: @Circle // @Link from { A } to { B } path { acurve } arrow { yes } @@ -54,33 +54,31 @@ A:: @Circle //1c ||2c B:: @Circle } @Rowa - A { ccurve } + A { rvlcurve } B { @Diag { A:: @Circle //1c ||2c B:: @Circle -// @Link from { A } to { B } path { ccurve } arrow { yes } +// @Link from { A } to { B } path { rvlcurve } arrow { yes } } } - -@Rowa - A { rvlcurve } - B { + C { ccurve } + D { @Diag { A:: @Circle //1c ||2c B:: @Circle -// @Link from { A } to { B } path { rvlcurve } arrow { yes } +// @Link from { A } to { B } path { ccurve } 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. +The name @Code rvlcurve is a reminder that the curve goes right, then +vertically, then left, with curved corners. The @Code acurve and +@Code ccurve values produce circular arcs, anticlockwise or clockwise, +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 diagrams. @RawIndex { diagrams } @@ -128,26 +126,27 @@ account when placing a diagram on the page: @ID { @Code @Verbatim { @Link - path { ccurve } + path { acurve } bias { 2c } } ||7ct @Diag vstrut { no } { A:: @Circle &3c B:: @Circle // -@Link path { ccurve } bias { 2c } from { A } to { B } +@Link path { acurve } 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. +As with {@Code "@Node"} options, {@Code "@Link"} options 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} +There are {@Code pathstyle}, {@Code pathdashlength}, {@Code pathwidth}, +and {@Code pathcolour} (alternative name {@Code pathcolor}) diagrams. @RawIndex { diagrams } diagrams.pathstyle @SubIndex { @Code "pathstyle" option } pathstyle.diagrams @Index { @Code "pathstyle" option (diagrams) } @@ -157,13 +156,26 @@ pathdashlength.diagrams @Index { @Code "pathdashlength" option (diagrams) } diagrams. @RawIndex { diagrams } diagrams.pathwidth @SubIndex { @Code "pathwidth" option } pathwidth.diagrams @Index { @Code "pathwidth" option (diagrams) } -options which affect the appearance of the path in the same way as the -{@Code outlinestyle}, {@Code outlinedashlength} and {@Code outlinewidth} -options of {@Code "@Node"} affect the outline. When {@Code pathstyle} -contains just one value (as opposed to a sequence of values) @Code "@Diag" -tries to divide the path into fewer segments than it would otherwise, to -make dashed and dotted paths look as good as possible. There is also -a {@Code pathgap} option which affects only @Code doubleline paths; it +diagrams.pathcolour @SubIndex { @Code "pathcolour" option } +pathcolour.diagrams @Index { @Code "pathcolour" option (diagrams) } +options which affect the path's appearance like the +{@Code outlinestyle}, {@Code outlinedashlength}, {@Code outlinewidth}, +and {@Code outlinecolour} options of {@Code "@Node"} affect its outline. +Here they are with their default values: +@ID { +@Code @Verbatim { +@Link + pathstyle { solid } + pathdashlength { 0.2f } + pathwidth { thin } + pathcolour { nochange } +} +} +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 diagrams. @RawIndex { diagrams } diagrams.pathgap @SubIndex { @Code "pathgap" option } pathgap.diagrams @Index { @Code "pathgap" option (diagrams) } @@ -195,6 +207,7 @@ Its value may be {@Code no} (the default), {@Code yes}, {@Code forward} @Code @Verbatim { @Link arrow { both } + pathcolour { green } } ||7ct @Diag { @@ -204,11 +217,17 @@ Its value may be {@Code no} (the default), {@Code yes}, {@Code forward} from { 0,0 } to { 1,1 } arrow { both } + pathcolour { green } } } -@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 +To colour the arrowheads differently you need {@Code fromlabel} and +{@Code tolabel}, described in Section {@NumberOf dia_labe}. Colouring +a link using `{@Code "green @Colour @Link ..."}' works too; it also +colours the link's labels. +@PP +@Code "@Link" offers {@Code arrowstyle}, {@Code arrowwidth}, and +{@Code arrowlength} options for changing the appearance of the +arrowheads. For diagrams. @RawIndex { diagrams } diagrams.arrowstyle @SubIndex { @Code "arrowstyle" option } arrowstyle.diagrams @Index { @Code "arrowstyle" option (diagrams) } @@ -218,10 +237,10 @@ arrowwidth.diagrams @Index { @Code "arrowwidth" option (diagrams) } diagrams. @RawIndex { diagrams } diagrams.arrowlength @SubIndex { @Code "arrowlength" option } arrowlength.diagrams @Index { @Code "arrowlength" option (diagrams) } -consistency it is almost always better to set the corresponding options -to the @Code "@Diag" symbol, which applies them to every arrow in the +consistency it is usually best to set the corresponding options to +the @Code "@Diag" symbol, which applies them to every arrow in the diagram: -@ID @Code @Verbatim { +@ID @OneRow @Code @Verbatim { @Diag arrowstyle { solid } arrowwidth { 0.3f } @@ -292,7 +311,7 @@ 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. -} +} &2s The arrow with style @Code solidwithbar has a bar at the tip of the arrowhead, whose length equals the width of the arrow and whose width is {@Code pathwidth}, like this: @@ -341,9 +360,9 @@ It is also possible to place an arbitrary object at the beginning or end of a link, using the @Code "fromlabel" and @Code "tolabel" options of Section {@NumberOf dia_labe}. @PP -To save time in common cases, @Code "@Diag" provides link symbols, -each of which is just @Code "@Link" with one of the standard paths -already set: {@Code "@Line"}, {@Code "@Curve"}, {@Code "@CCurve"}, +@Code "@Diag" offers link symbols which are just @Code "@Link" with +one of the standard paths already set: {@Code "@Line"}, +{@Code "@Curve"}, {@Code "@CCurve"}, diagrams. @RawIndex { diagrams } diagrams.line @SubIndex { @Code "@Line" symbol } line.diagrams @Index { @Code "@Line" symbol (diagrams) } @@ -351,7 +370,7 @@ diagrams. @RawIndex { diagrams } diagrams.curve @SubIndex { @Code "@Curve" symbol } curve.diagrams @Index { @Code "@Curve" symbol (diagrams) } {@Code "@RVLCurve"}, and so on. There are also symbols in which -the @Code "arrow" option is set to @Code yes in addition: {@Code "@Arrow"}, +the @Code "arrow" option is set to @Code yes as well: {@Code "@Arrow"}, diagrams. @RawIndex { diagrams } diagrams.arrow.sym @SubIndex { @Code "@Arrow" symbol } arrow.sym.diagrams @Index { @Code "@Arrow" symbol (diagrams) } diff --git a/doc/user/dia_node b/doc/user/dia_node index 52f6b4d..af72196 100644 --- a/doc/user/dia_node +++ b/doc/user/dia_node @@ -58,10 +58,9 @@ 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: +The @Code "@Node" symbol has many options. They all share a 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 @Verbatim { @Diag @@ -147,14 +146,13 @@ in this section for the @Code font option): @BNode keyword } } -Note that when giving an option directly to {@Code "@ANode"}, -{@Code "@BNode"}, {@Code "@CNode"}, {@Code "@DNode"}, and -{@Code "@ENode"}, the initial @Code { a }, @Code { b }, -@Code { c }, @Code { d }, or @Code { e } used with @Code "@Diag" -and in the setup file is omitted. +When giving an option directly to {@Code "@ANode"}, {@Code "@BNode"}, +{@Code "@CNode"}, {@Code "@DNode"}, and {@Code "@ENode"}, the initial +@Code { a }, @Code { b }, @Code { c }, @Code { d }, or @Code { e } +used with @Code "@Diag" and in the setup file is omitted. @PP To save time in simple cases, @Code "@Diag" provides nine other -node symbols called +node symbols: {@Code "@Box"}, diagrams. @RawIndex { diagrams } diagrams.box @SubIndex { @Code "@Box" symbol } @@ -190,8 +188,8 @@ diagrams. @RawIndex { diagrams } diagrams.circle @SubIndex { @Code "@Circle" symbol } circle.diagrams @Index { @Code "@Circle" symbol (diagrams) } and {@Code "@Circle"}. These are just abbreviations for @Code "@Node" -with the appropriate value of {@Code outline}, nothing more. They take -the same options as {@Code "@Node"} (except that @Code outline is +with its {@Code outline} option set, 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 @@ -265,7 +263,8 @@ 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} +The {@Code outlinestyle}, {@Code outlinedashlength}, {@Code outlinewidth}, +and {@Code outlinecolour} (alternative name {@Code outlinecolor}) diagrams. @RawIndex { diagrams } diagrams.outlinestyle @SubIndex { @Code "outlinestyle" option } outlinestyle. @RawIndex { @Code "outlinestyle" option } @@ -278,6 +277,8 @@ diagrams. @RawIndex { diagrams } diagrams.outlinewidth @SubIndex { @Code "outlinewidth" option } outlinewidth. @RawIndex { @Code "outlinewidth" option } outlinewidth.in.diagrams @SubIndex { in diagrams } +outlinecolour. @RawIndex { @Code "outlinecolour" option } +outlinecolour.in.diagrams @SubIndex { in diagrams } options apply to any node and affect the appearance of the outline: @ID @OneRow { @Code @Verbatim { @@ -285,6 +286,7 @@ options apply to any node and affect the appearance of the outline: outlinestyle { solid } outlinedashlength { 0.2f } outlinewidth { thin } + outlinecolour { nochange } { Hello, world } } ||7ct @@ -293,6 +295,7 @@ options apply to any node and affect the appearance of the outline: outlinestyle { solid } outlinedashlength { 0.2f } outlinewidth { thin } + outlinecolour { nochange } { Hello, world } } } @@ -336,11 +339,7 @@ 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}. +reduced to make the dashes or dots fit evenly. @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 @@ -363,6 +362,31 @@ 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 +The @Code outlinewidth option gives 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 outlinecolour} (alternatively {@Code outlinecolor}) option +determines the colour of the outline: +@ID @OneRow { +@Code @Verbatim { +@CurveBox + outlinestyle { cdashed } + outlinecolour { red } +{ Hello, world } +} +||7ct +@Diag { +@CurveBox + outlinestyle { cdashed } + outlinecolour { red } +{ Hello, world } +} +} +It may be {@Code nochange} (or empty) for the colour currently in +use, or any colour from Section {@NumberOf colour}. +@PP The node symbols of @Code "@Diag" are quite separate symbols from the three basic box symbols of Section {@NumberOf boxes}. Although much is the same, one obvious difference between the two is that to get no @@ -398,7 +422,7 @@ paint.in.diagrams @SubIndex { in diagrams } } In this example the object following @Code "@Box" is a diamond containing {@Code "Hello, world"}. The default value of @Code "paint" is {@Code none}, -a special value (not a colour) meaning don't use any paint. There is +a special value (not a colour) meaning `don't apply any paint'. There is also a @Code "texture" option which causes this paint to be applied with a diagrams. @RawIndex { diagrams } diagrams.texture @SubIndex { @Code "texture" option } @@ -407,10 +431,10 @@ texture.option.in.diagrams @SubIndex { in diagrams } given texture. This works exacly like the @Code texture option described in Section {@NumberOf boxes}, so we'll say no more about it here. @PP -When painting it is important to know what order things are done in, because -anything put down earlier will disappear under the paint. This is why -@Code none and @Code white are different. Painting is done first, then -boundaries, and finally the following object. +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 none and @Code white are different. Painting is +done first, then outlines, and finally the following object. @PP Each node symbol has @Code "font" and @Code "break" options which may be used to @@ -544,11 +568,11 @@ other. For example, } } 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 +applied to all nodes at once, but, as usual, 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 @@ -606,7 +630,7 @@ is to appear: } 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 +meaning that far 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, @@ -689,8 +713,8 @@ hindent.diagrams @Index { @Code "hindent" option (diagrams) } diagrams. @RawIndex { diagrams } diagrams.hstrut @SubIndex { @Code "hstrut" option } hstrut.diagrams @Index { @Code "hstrut" option (diagrams) } -options which work horizontally exactly as {@Code valign}, {@Code vsize}, -{@Code vindent}, and {@Code vstrut} work vertically, except that they +options that do horizontally exactly what {@Code valign}, {@Code vsize}, +{@Code vindent}, and {@Code vstrut} do 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}. diff --git a/doc/user/dia_posi b/doc/user/dia_posi index 5cf8d82..7b41f15 100644 --- a/doc/user/dia_posi +++ b/doc/user/dia_posi @@ -3,18 +3,18 @@ @Title { Positioning } @Begin @PP -Once the nodes of the diagram are in place, @@Diag can be trusted to look +Once the nodes are in place, @@Diag can be trusted to look diagrams. @RawIndex { diagrams } diagrams.positioning @SubIndex { positioning nodes } positioning.diagrams @Index { positioning nodes in diagrams } after the rest: links to standard outlines will terminate neatly on their boundaries, labels will not overstrike links no matter what direction they are heading, and so on. The great weakness of @@Diag is in positioning -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. +the nodes. This is partly because `what pleases the eye' is often the +rule, 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 @@ -23,8 +23,8 @@ this is very primitive. This section suggests three better ways: using 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: +{@Code "@Tbl"} (Chapter {@NumberOf tables}) is a good choice when +the nodes have any grid-like arrangement: @ID @OneRow { @Code @Verbatim { @Diag { @@ -72,8 +72,8 @@ the nodes have any kind of grid-like arrangement: @Arrow from { A } to { D } } } -The table occupies the nodes part. Tags may have the same name -as columns; the two can never conflict. +The table lies in the nodes part. Tags may share names +with columns; the two cannot conflict. @PP Similarly, the @Code "@Graph" symbol from Chapter {@NumberOf graphs} has an @Code "objects" option which can place arbitrary objects, diff --git a/doc/user/dia_summ b/doc/user/dia_summ index 661f1b9..6dd0383 100644 --- a/doc/user/dia_summ +++ b/doc/user/dia_summ @@ -218,9 +218,9 @@ the {@Code nodelabel} options except for {@Code nodelabelpos}. hmargin { 1s } # vmargin { 0.6vx } @Fmth { @Col @Code A ! @Col @Code " " ! @Col @Code B ! @Col @Code " " ! - @Col 1.0c @Wide ! @Col C } + @Col 0.3c @Wide ! @Col C } @Fmta { @Col @Code A ! @Col @Code "{" ! @Col @Code B ! @Col @Code "}" ! - @Col 1.0c @Wide ! @Col C } + @Col 0.3c @Wide ! @Col C } { @FirstRowh A { "@Node" } @@ -256,7 +256,7 @@ any outline } C { {@Code solid}, {@Code dashed}, {@Code cdashed}, {@Code dotted}, {@Code dotdashed}, {@Code dotcdashed}, {@Code dotdotdashed}, {@Code dotdotcdashed}, {@Code dotdotdotdashed}, {@Code dotdotdotcdashed}, -{@Code noline}, or any sequence of one or more of these values } +{@Code noline}, or any sequence of one or more of these } @Rowa A { " outlinedashlength"} B { 0.2f } @@ -266,6 +266,10 @@ any outline } B { thin } C { {@Code thin}, {@Code medium}, {@Code thick}, or any @I length } @Rowa + A { " outlinecolour" } + B { nochange } + C { @Code nochange or any colour from Section {@NumberOf colour} } +@Rowa A { " paint" } B { none } C { @Code none or any colour from Section {@NumberOf colour} } @@ -1243,9 +1247,9 @@ have been omitted where they are the same as the {@Code linklabel} options. hmargin { 1s } # vmargin { 0.6vx } @Fmth { @Col @Code A ! @Col @Code " " ! @Col @Code B ! @Col @Code " " ! - @Col 1.0c @Wide ! @Col C } + @Col 0.3c @Wide ! @Col C } @Fmta { @Col @Code A ! @Col @Code "{" ! @Col @Code B ! @Col @Code "}" ! - @Col 1.0c @Wide ! @Col C } + @Col 0.3c @Wide ! @Col C } { @Rowh A { "@Link" } @@ -1324,6 +1328,10 @@ have been omitted where they are the same as the {@Code linklabel} options. B { thin } C { {@Code thin}, {@Code medium}, {@Code thick}, or any @I length } @Rowa + A { " pathcolour" } + B { nochange } + C { @Code nochange or any colour from Section {@NumberOf colour} } +@Rowa A { " pathgap" } B { thin } C { {@Code thin}, {@Code medium}, {@Code thick}, or any @I length } diff --git a/doc/user/dia_synt b/doc/user/dia_synt index 48f341b..de0811c 100644 --- a/doc/user/dia_synt +++ b/doc/user/dia_synt @@ -67,8 +67,8 @@ The basic components of syntax diagrams are @I { category cells }, shown as boxes in the example above and obtained with the @Code "@ACell" symbol; @I { keyword cells }, shown as curved boxes and obtained with {@Code "@BCell"}; and @I { punctuation cells }, -containing punctuation symbols small enough to be enclosed in circles, -and obtained with {@Code "@CCell"}. After each symbol, place whatever +containing symbols small enough to be enclosed in circles, and +obtained with {@Code "@CCell"}. After each symbol, place whatever has to go inside the cell: @ID @OneRow { @Code @Verbatim { @StartRight @BCell loop } diff --git a/doc/user/dia_tags b/doc/user/dia_tags index 67ad6a0..71a423d 100644 --- a/doc/user/dia_tags +++ b/doc/user/dia_tags @@ -55,7 +55,7 @@ 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 +since in general there will be many nodes and so many @Code N and @Code S tags. The retagging symbol, {@Code "::"}, solves this problem: @ID { @Code { @@ -134,7 +134,7 @@ better to avoid the whole problem by not using digits.) @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 @Verbatim { +@ID @OneRow @Code @Verbatim { @Square @Circle Hello } @@ -149,10 +149,10 @@ 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: +@Code "@Diag" where a point is expected, and so where a tag may be given, +they have a special virtue not shared by other options. It is possible +to give the name of an entire node, not just a tag denoting one point, +to them: @ID { @Code @Verbatim { A:: @Circle diff --git a/doc/user/dia_tree b/doc/user/dia_tree index 52f52f6..2845b89 100644 --- a/doc/user/dia_tree +++ b/doc/user/dia_tree @@ -347,10 +347,9 @@ and its subtrees: } } } -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. +These may also be given to individual subtree symbols; @Code "treevsep" +works 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 diagrams. @RawIndex { diagrams } diff --git a/doc/user/fmt_head b/doc/user/fmt_head index da88b24..a47a16f 100644 --- a/doc/user/fmt_head +++ b/doc/user/fmt_head @@ -107,7 +107,7 @@ 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 +and so on. This makes eight (@M { 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 (e.g. pages containing part titles in books). @@ -181,9 +181,9 @@ Arabic, Roman, etc. as specified by the @Code "@PageNumbers" or within page header and footer options. @PP To get the @I last page into a header, so that you can have page -headers like `Page 5 of 8', you need @Code "@NumberOf last.page" as +headers like `Page 5 of 8', you need @Code "@PageOf last.page" as described in Section {@NumberOf cross}. You might have -@ID @Code "@Centre { Page @PageNum of @NumberOf last.page }" +@ID @Code "@Centre { Page @PageNum of @PageOf last.page }" as the value of @Code "@EvenTop" and the rest. @PP At this point you might like to pause and verify that the default diff --git a/doc/user/fmt_marg b/doc/user/fmt_marg index bc02956..c3a98b0 100644 --- a/doc/user/fmt_marg +++ b/doc/user/fmt_marg @@ -44,8 +44,8 @@ for ordinary margins, the total (left plus right) page body margin must be the same on odd and even pages. Margin notes (Section {@NumberOf marginnotes}) occupy body margin space. @PP -You can have a box drawn around each page if you wish. Here are the -relevant options and their default values: +You can draw a box around each page. The relevant options and their +default values are @ID @OneRow @Code @Verbatim { @PageBoxType { None } @PageBoxMargin { 1.00c } @@ -93,30 +93,28 @@ 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 -More generally, you can enclose each page in any object at all, by -means of the @Code "@PageEnclose" option: +More generally, you can enclose each page in any object at all, +using @Code "@PageEnclose": @ID @Code { "@PageEnclose { @Body }" } -Within this option, @Code "@Body" stands for the page, and it must -occur exactly once. You could place a curved box around each page, -for example, by writing +Within the @Code "@PageEnclose" option, @Code "@Body" stands for the +page, and it must occur exactly once. You could place a curved box +around each page, for example, by writing @ID @Code { "@PageEnclose { @CurveBox @Body }" } -This is of course also available from the @Code "@PageBox" symbols, but -with @Code "@PageEnclose" there are infinitely many other possibilities. +This could be done with {@Code "@PageBox"}, but @Code "@PageEnclose" +offers infinitely many possibilities. @PP -Finally, it is possible to have something other than the usual white -background on the page, using the @Code "@PageBackground" option: +@Code "@PageBackground" replaces the usual white background of the page: 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: +Its value 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 diff --git a/doc/user/fmt_setu b/doc/user/fmt_setu index acc0da0..2e38a0d 100644 --- a/doc/user/fmt_setu +++ b/doc/user/fmt_setu @@ -29,10 +29,10 @@ 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, +to copy the @Code doc setup file into 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 +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 diff --git a/doc/user/fmt_size b/doc/user/fmt_size index 550bf57..8418f30 100644 --- a/doc/user/fmt_size +++ b/doc/user/fmt_size @@ -35,6 +35,10 @@ the @Code "@PageType" option to the name of the paper you use: @Rowa A { A3 } B { 842p } C { 1190p } @Rowa A { A4 } B { 595p } C { 842p } @Rowa A { A5 } B { 420p } C { 595p } +@Rowa A { ISOB4 } B { 709p } C { 1001p } +@Rowa A { ISOB5 } B { 499p } C { 709p } +@Rowa A { JISB4 } B { 729p } C { 1032p } +@Rowa A { JISB5 } B { 516p } C { 729p } @Rowa A { B4 } B { 729p } C { 1032p } @Rowa A { B5 } B { 516p } C { 729p } @Rowa A { Folio } B { 612p } C { 936p } @@ -43,9 +47,11 @@ the @Code "@PageType" option to the name of the paper you use: } 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: +have to worry about those options. It is recommended that {@Code ISOB4} +or {@Code JISB4} be used instead of {@Code B4}, and that {@Code ISOB5} +or {@Code JISB5} be used instead of {@Code B5}. 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 @@ -89,8 +95,9 @@ the basic ones: 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"}. +# @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_data b/doc/user/gra_data index f39c751..318cd20 100644 --- a/doc/user/gra_data +++ b/doc/user/gra_data @@ -50,14 +50,13 @@ centred over the data point. There is a @Code "symbolsize" graphs. @RawIndex { graphs (statistical) } graphs.symbolsize @SubIndex { @Code symbolsize option } symbolsize.graph @Index { @Code "symbolsize" option (graphs) } -option which controls the size (radius) of all these symbols, -and a @Code "symbollinewidth" option -@FootNote { -The @Code "symbollinewidth" option was introduced in Version 3.37, -as part of a bug fix which also caused the printed size of some -symbols to change slightly. -} -which controls their line width: +option which controls the size (radius) of all these symbols, and +a @Code "symbollinewidth" option which controls their line width: +# @FootNote { +# The @Code "symbollinewidth" option was introduced in Version 3.37, +# as part of a bug fix which also caused the printed size of some +# symbols to change slightly. +# } @ID @OneRow @Code { "@Data" " symbolsize { 0.15f }" diff --git a/doc/user/gra_erro b/doc/user/gra_erro index f71a251..2a11dba 100644 --- a/doc/user/gra_erro +++ b/doc/user/gra_erro @@ -21,10 +21,10 @@ 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. +to be printed up to where the error occurred, with a message 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 @@ -41,8 +41,8 @@ save.in.graphs @SubIndex { in graphs } ... } 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. +the graph is printed, which might solve your problem if you have +several graphs on one page. However, if the graph is inside some +other major package, notably {@Code "@Diag"}, this could cause +PostScript errors in that package. @End @Section diff --git a/doc/user/gra_func b/doc/user/gra_func index a2d6fdc..fbe3df4 100644 --- a/doc/user/gra_func +++ b/doc/user/gra_func @@ -62,9 +62,6 @@ for @M { x } from 10 to 500: 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 } @@ -96,7 +93,9 @@ pp. 15--33 (1985). } } } } -The points are connected by straight line segments as usual, but a +(Jeffrey H. Kingston, Analysis of tree algorithms for the simulation +event list. @I { Acta Informatica } {@B 22}, pp. 15--33 1985). 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 @@ -167,7 +166,7 @@ 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 +@Code "cos" (see Section {@NumberOf grsummary} 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 diff --git a/doc/user/gra_intr b/doc/user/gra_intr index 28dfd1b..94d2cd3 100644 --- a/doc/user/gra_intr +++ b/doc/user/gra_intr @@ -14,9 +14,9 @@ you want graphs, like this: "..." "@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. +Setup files like {@Code "graph"} are best included before the main +setup file. Once this is done, the @Code "@Graph" symbol will 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, @@ -47,5 +47,5 @@ per line, for example. The result of this example is 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. +at all. @End @Section diff --git a/doc/user/gra_over b/doc/user/gra_over index a2f5467..4f7eae6 100644 --- a/doc/user/gra_over +++ b/doc/user/gra_over @@ -6,7 +6,16 @@ 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. +and if omitted are assigned some sensible default value. The default +values may be changed by setting options in the setup file as usual. +@PP +There is a @Code "font" option for changing the font throughout the +graph, whose value is anything suitable for passing to Lout's +@Code "@Font" symbol. Indeed, you can get the same effect by +placing a @Code "@Font" symbol immediately before @Code "@Graph" +in the usual way. However, the @Code "font" option is useful +because it can be set in the setup file, where it applies to +every graph in your document. @PP There is a @Code "style" option for controlling the overall style of the graphs. @RawIndex { graphs (statistical) } @@ -32,7 +41,8 @@ graphs. @RawIndex { graphs (statistical) } graphs.yorigin @SubIndex { @Code yorigin option } yorigin.graph @Index { @Code "yorigin" option (graphs) } @ID @OneRow @Code @Verbatim { --2p @Font @Graph +@Graph + font { -2p } style { axes } xorigin { 0 } yorigin { 0 } @@ -59,9 +69,7 @@ yorigin.graph @Index { @Code "yorigin" option (graphs) } } } } -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 +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 } diff --git a/doc/user/gra_summ b/doc/user/gra_summ index 60e9a8e..7854efb 100644 --- a/doc/user/gra_summ +++ b/doc/user/gra_summ @@ -20,6 +20,26 @@ their possible values are: B { frame } C { {@Code frame}, {@Code grid}, {@Code axes}, or {@Code none} } @Rowa + A { font } + B { } + C { Any value suitable for {@Code "@Font"} } +@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 { width } B { 6.0c } C { any @I distance } @@ -29,12 +49,12 @@ their possible values are: C { any @I distance } @Rowa A { xextra } - B { 0.5c } - C { any @I distance ({@Code axes} and {@Code none} default is {@Code "0c"}) } + B { auto } + C { any @I distance ({@Code auto} means @Code "0.5c" for {@Code frame} else {@Code "0c"}) } @Rowa A { yextra } - B { 0.5c } - C { any @I distance ({@Code axes} and {@Code none} default is {@Code "0c"}) } + B { auto } + C { any @I distance ({@Code auto} means @Code "0.5c" for {@Code frame} else {@Code "0c"}) } @Rowa A { xdecreasing } B { no } @@ -80,22 +100,6 @@ their possible values are: 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} } @@ -126,18 +130,15 @@ their possible values are: @Rowa A { xticks } B { auto } - C { @I sequence (of numbers and strings), or @Code auto meaning -automatic } + C { @I sequence (of numbers and strings), or @Code auto (automatic) } @Rowa A { yticks } B { auto } - C { @I sequence (of numbers and strings), or @Code auto meaning -automatic } + C { @I sequence (of numbers and strings), or @Code auto (automatic) } @Rowa A { rticks } B { } - C { @I sequence (of numbers and strings), or @Code auto meaning -automatic } + C { @I sequence (of numbers and strings), or @Code auto (automatic) } @Rowa A { xticklength } B { 0.5f } @@ -156,12 +157,24 @@ automatic } C { sequence of {@Code "@CTR"}, {@Code "@NW"}, {@Code "@SW"}, {@Code "@SE"}, {@Code "@NE"}, {@Code "@N"}, {@Code "@W"}, {@Code "@S"}, {@Code "@E"} symbols } @Rowa + A { save } + B { no } + C { {@Code no} or {@Code yes} } +@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 { symbolsize } + B { 0.15f } + C { any @I distance } +@Rowa + A { symbollinewidth } + B { 0.5p } + C { any @I distance } +@Rowa A { pairs } B { none } C { {@Code none}, {@Code solid}, {@Code dashed}, {@Code dotted}, @@ -169,13 +182,21 @@ automatic } {@Code yhisto}, {@Code xhisto}, {@Code filledyhisto}, {@Code filledxhisto}, {@Code surfaceyhisto}, {@Code surfacexhisto} } @Rowa + A { dashlength } + B { 0.2f } + C { any @I distance } +@Rowa + A { linewidth } + B { 0.5p } + C { any @I distance } +@Rowa A { "colour/color" } B { none } C { {@Code none} or any colour from Section {@NumberOf colour}} @Rowa A { paint } B { no } - C { {@Code no} or {@Code yes} } + C { {@Code none}, {@Code no}, or {@Code yes} } @Rowa A { texture } B { solid } @@ -184,22 +205,6 @@ automatic } A { dataformat } B { xandy } C { {@Code xandy}, {@Code yonly}, {@Code xonly}, {@Code swapxandy} } -@Rowa - A { dashlength } - B { 0.2f } - C { any @I distance } -@Rowa - A { linewidth } - B { 0.5p } - C { any @I distance } -@Rowa - A { symbolsize } - B { 0.15f } - C { any @I distance } -@Rowa - A { symbollinewidth } - B { 0.5p } - C { any @I distance } } @I Number means an ordinary decimal number; @I distance means a number with a unit of measurement (Section {@NumberOf objects}), such as @@ -251,12 +256,24 @@ their possible values are: {@Code circle}, {@Code filledcircle}, {@Code triangle}, {@Code filledtriangle} } @Rowa + A { symbolsize } + C { any @I distance } +@Rowa + A { symbollinewidth } + C { any @I distance } +@Rowa A { pairs } C { {@Code none}, {@Code solid}, {@Code dashed}, {@Code dotted}, {@Code dotdashed}, {@Code dotdotdashed}, {@Code dotdotdotdashed}, {@Code yhisto}, {@Code xhisto}, {@Code filledyhisto}, {@Code filledxhisto}, {@Code surfaceyhisto}, {@Code surfacexhisto} } @Rowa + A { dashlength } + C { any @I distance } +@Rowa + A { linewidth } + C { any @I distance } +@Rowa A { "colour/color" } C { {@Code none}, or any colour name from Section {@NumberOf colour} } @Rowa @@ -268,24 +285,23 @@ their possible values are: @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 } -@Rowa - A { symbollinewidth } - 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. +Furthermore, every option of {@Code "@Graph"} and {@Code "@Data"}, +as well as of {@Code "@GraphPlus"}, {@Code "@GraphNoLine"}, and the +other symbols from Section {@NumberOf key}, appears in the setup file, +and giving a value to an option there makes that value the default +value for every {@Code "@Graph"} in your document. For example, +if you want every data set in every graph to use {@Code "dashed"} +for {@Code "pairs"}, you can set the @Code "pairs" option in the +setup file to {@Code "dashed"}, and then all your data sets will +have dashed lines unless you override the setup file value by +some other value to the {@Code "pairs"} option of a {@Code "@Graph"} +or @Code "@Data" symbol. @PP The right parameter of @Code "@Data" contains a @I sequence of zero or more {@I expressions}. The {@Code xticks}, {@Code yticks}, and diff --git a/doc/user/mat_summ b/doc/user/mat_summ index f6bf1a2..e1e1d55 100644 --- a/doc/user/mat_summ +++ b/doc/user/mat_summ @@ -947,7 +947,6 @@ uniformly @Code "no" as required by mathematical convention. The @Code "largeop" symbol causes an arbitrary object to be treated mathematics.largeop. @SubIndex { @Code "largeop" symbol } largeop. @Index { @Code "largeop" symbol (mathematics) } -options which work as described for the @Code "sum" symbol as a large operator: @ID { @Code @Verbatim { largeop symbol { diamond } from { a } to { b } x } diff --git a/doc/user/preface b/doc/user/preface index b87b3ef..99310c7 100644 --- a/doc/user/preface +++ b/doc/user/preface @@ -15,20 +15,20 @@ 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 +primary source is @ID @Code "ftp://ftp.it.usyd.edu.au/jeff/lout" -containing a gzipped tar file of the current version -(currently {@Code "lout-3.39.tar.gz"}), and various other things including -a PostScript version of this guide. The distribution contains source code, -libraries, documentation, license, and installation instructions. +containing a gzipped tar file of the current version, 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 (or unsubscribe), visit @ID @Code "http://lists.nongnu.org/mailman/listinfo/lout-users" After subscribing, to post an item send email to {@Code "lout-users@nongnu.org"}; it will be forwarded to all -subscribers via email. There is also a Lout web -site at {@Code "http://lout.wiki.sourceforge.net/"}. +subscribers via email. There is also a web +site at {@Code "http://savannah.nongnu.org/projects/lout"}. @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 @@ -43,7 +43,7 @@ Scribe system @Cite { $reid1980scribe }. That scribe. @RawIndex { Scribe } scribe.influence @SubIndex { influence on Lout } reid.b @Index { Reid, Brian K. } -research phase ended in October 1991 with the first public release of Lout. +research phase ended in October 1991 with the first public release. @PP Since then the system has been steadily improved and extended. Optimal paragraph breaking and automatic hyphenation were copied from Donald diff --git a/doc/user/prg b/doc/user/prg index 11d4b7d..fcda27e 100644 --- a/doc/user/prg +++ b/doc/user/prg @@ -15,12 +15,14 @@ c. @Index { C and C++ program printing } eiffel. @Index { Eiffel program printing } haskell. @Index { Haskell program printing } java. @Index { Java program printing } +javascript. @Index { Javascript program printing } nonpareil. @Index { Nonpareil program printing } perl. @Index { Perl program printing } pod. @Index { Pod (for Perl) printing } python. @Index { Python program printing } rsl. @Index { RSL program printing } ruby. @Index { Ruby program printing } +tcl. @Index { Tcl program printing } @CD @Tbl mv { 0.5vx } af { Italic } @@ -65,6 +67,12 @@ ruby. @Index { Ruby program printing } D { fixed } E { No } @Rowb + A { Javascript } + B { javascript } + C { "@JavaScript" } + D { fixed } + E { No } +@Rowb A { Nonpareil } B { np } C { "@Nonpareil" } @@ -100,6 +108,12 @@ ruby. @Index { Ruby program printing } C { "@Ruby" } D { fixed } E { No } +@Rowb + A { Tcl } + B { tcl } + C { "@Tcl" } + D { fixed } + E { No } rb { yes } } C and C++ are handled together since, for formatting purposes, they @@ -127,10 +141,9 @@ or interpret in some way (braces and so on), ensuring that you can include program texts with absolutely no modifications; plus, if you wish, Lout will print keywords in bold, identifiers in italics, add line numbers, etc. @PP -It is relatively easy to add new languages, since you don't have to write -executable code, just declare a lot of records describing your language. -Consult the instructions at the top of file {@I prg2lout.c} if you want -to try it yourself. +It is fairly easy to add new languages: you don't have to write +executable code, just declare records describing your language. +There are instructions at the top of file {@I prg2lout.c}. @BeginSections @Include { prg_lone } @Include { prg_embe } diff --git a/doc/user/prg_embe b/doc/user/prg_embe index 3228426..c7d2952 100644 --- a/doc/user/prg_embe +++ b/doc/user/prg_embe @@ -20,7 +20,6 @@ this for the C language: @ID @OneRow @Code @Verbatim { @IndentedDisplay @CP { #include <stdio.h> - treeprint(struct tnode *p) /* print tree p recursively */ { if (p != NULL) { @@ -37,7 +36,6 @@ allowing the program text to be incorporated with absolutely no modifications. The result is @ID @OneRow @CP { #include <stdio.h> - treeprint(struct tnode *p) /* print tree p recursively */ { if (p != NULL) { diff --git a/doc/user/ref b/doc/user/ref index 6ea5782..baf81e7 100644 --- a/doc/user/ref +++ b/doc/user/ref @@ -9,7 +9,7 @@ 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 +Some good 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 @@ -18,8 +18,9 @@ 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. +same source. +# , so translation from Scribe and @LaTeX references is +# fairly straightforward. @BeginSections @Include { ref_sett } @Include { ref_cite } diff --git a/doc/user/ref_cite b/doc/user/ref_cite index 925d61e..c2ea68c 100644 --- a/doc/user/ref_cite +++ b/doc/user/ref_cite @@ -29,22 +29,21 @@ 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 +In books, there is a @Code "@ChapCite" symbol which is references. @RawIndex { references } references.chap.cite @SubIndex { @Code "@ChapCite" } chap.cite.references @Index { @Code "@ChapCite" (references) } the same as @Code "@Cite" except that its references come out at the -end of the current preface, introduction, chapter, or appendix, rather -than at the end of the document. +end of the current preface, introduction, chapter, or appendix. @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. +A citation may appear in a footnote, figure, table, or index entry. +The reference will appear in the first reference list after the +citation point, or if none, in 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 @@ -60,8 +59,8 @@ produces ... 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. Note -that if you put commas between the references inside @Code "@NoCite" you +references nevertheless appear in the reference list as usual. 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 references. @RawIndex { references } diff --git a/doc/user/ref_crea b/doc/user/ref_crea index 637bca5..7a01ac9 100644 --- a/doc/user/ref_crea +++ b/doc/user/ref_crea @@ -3,13 +3,11 @@ @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: +Although the options of @Code "@Reference" ({@Code "@Tag"}, +{@Code "@Type"}, {@Code "@Author"}, etc.) are fixed, you can add your +own reference types and change the formatting of existing types. To +do this you must use your own setup file, as explained in +Section {@NumberOf setup}. At the end of the setup file is this line: references. @RawIndex { references } references.refstyle @SubIndex { @Code "@RefStyle" } refstyle.references @Index { @Code "@RefStyle" (references) } @@ -34,11 +32,11 @@ Unix command 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 +to copy @Code "refstyle.ld" into 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 +directory, renamed {@Code "mystyle.ld"}. Since @Code "refstyle.ld" +is read-only, you may need to change @Code "mystyle.ld" +to be writable (@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 }" @@ -67,27 +65,26 @@ might look something like this: } } } -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: +The first two lines are beyond our scope, except that @Code "Book" +identifies this as the entry defining how references of type +@Code Book appear. Apart from this one word these lines are the +same in every reference style, 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. +on. To change the @Code Book format, change this object. To create +a new reference type, copy the whole entry, change @Code Book to a +new name of your choice, and change the middle part. Delete index +file @Code "mystyle.li" (if there is one) so that Lout knows to +regenerate it. @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 } + vmargin { 0.5vx } @Fmta { @Col @Code A ! @Col @Code B } { @Rowa A { "{ Book @RefStyle @Style" } @@ -124,9 +121,9 @@ 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. +The objects subject to @Code "@If" are printed with no preceding space; +any space in the result will be from 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 diff --git a/doc/user/ref_entr b/doc/user/ref_entr index e4c4b17..e5949fc 100644 --- a/doc/user/ref_entr +++ b/doc/user/ref_entr @@ -6,7 +6,7 @@ Here is the complete, fixed list of options that you may give to the @Code "@Reference" symbol: @ID @Tab - vmargin { 0.5vx } + vmargin { 0.47vx } @Fmta { @Col @Code A ! @Col B } { @Rowa @@ -293,8 +293,8 @@ 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 +had in mind. So a truly meticulous compiler of database entries would +enclose @I all language-specific options in @Code "@Language" symbols: @ID @OneRow @Code @Verbatim { { @Reference diff --git a/doc/user/ref_sett b/doc/user/ref_sett index da8e8fe..e053ec2 100644 --- a/doc/user/ref_sett +++ b/doc/user/ref_sett @@ -86,12 +86,10 @@ 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"}. +Lout may be able to use the last modification times of the database +and index files to decide whether the index file needs to be created +afresh, saving you the trouble of removing it. Type {@Code "lout -V"} +to find out whether this is true of your system. } The index file is stored in the same directory as the database file, and it has the same name except diff --git a/doc/user/str b/doc/user/str index 4460e8f..1a285fb 100644 --- a/doc/user/str +++ b/doc/user/str @@ -1,5 +1,5 @@ @Chapter - @Title { Adding Structure to Documents } + @Title { Documents With Structure } @Tag { structure } @Begin @BeginSections diff --git a/doc/user/str_cont b/doc/user/str_cont index da1653c..f14cde7 100644 --- a/doc/user/str_cont +++ b/doc/user/str_cont @@ -57,9 +57,8 @@ single line spacing. @Code "@ContentsFont" also applies only to these them to appear in Bold. @PP @Code "@ContentsPartGapAbove" and @Code "@ContentsPartGapBelow" are -like @Code "@ContentsGapAbove" and @Code "@ContentsGapBelow", except -that they are used before and after contents entries that denote -book parts. +like @Code "@ContentsGapAbove" and @Code "@ContentsGapBelow", only +used before and after contents entries that denote book parts. @PP @Code "@ContentsFormat" determines the format of each entry of contentsformat. @Index @Code "@ContentsFormat" diff --git a/doc/user/str_cros b/doc/user/str_cros index c9caaed..f00747d 100644 --- a/doc/user/str_cros +++ b/doc/user/str_cros @@ -220,8 +220,7 @@ Once again the result is the object to the right, modified by any 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. +Wide Web, if the software displaying your document is capable of it. @PP At present, the @Code "@CrossLink" and @Code "@ExternalLink" symbols behave as though a @Code "@OneCol" symbol encloses the object to their diff --git a/doc/user/str_defs b/doc/user/str_defs index 42ea403..7de300a 100644 --- a/doc/user/str_defs +++ b/doc/user/str_defs @@ -3,12 +3,11 @@ @Tag { definitions } @Begin @PP -Whenever you find yourself typing the same thing repeatedly, you can +Whenever you find yourself typing something 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 +save time by defining your own personal symbol to stand for that +thing. For example, suppose you type `@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 ..." } @@ -18,7 +17,7 @@ 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 +Create a file called @Code "mydefs" in your current mydefs.file @Index { @Code mydefs file } directory, containing definitions like this: @ID @OneRow @Code { @@ -55,13 +54,12 @@ 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 { +@PP 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 @@ -94,8 +92,7 @@ is for, rather than how it does what it does. Here is a good example: "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: +This kind of name is very pleasant to use: @ID @OneRow @Code { "@IndentedDisplay @Poetry {" "Teach me to hear Mermaides singing," @@ -116,8 +113,8 @@ and {@Code "@Colour"} symbols do: "{ @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 +This takes three lines only because it is long; as usual, end of +line is the same as a space. Now @ID @OneRow @Code { "Cheating @HeadingBox {" "The Department uses assignments ... of that student alone." @@ -132,6 +129,5 @@ 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. +of a definition. 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 index 4634103..fb968ac 100644 --- a/doc/user/str_disp +++ b/doc/user/str_disp @@ -13,17 +13,17 @@ has result 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 +To display 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"}; +{@Code "@LeftDisplay"} instead of {@Code "@Display"}. To indent +the 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 +centre the display (like {@Code "@Display"}), and rightdisplay. @Index @Code "@RightDisplay" @Code "@RightDisplay" which right-justifies the display. @PP @@ -88,7 +88,7 @@ default.indent @Index @Code "@DefaultIndent" 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 +indent for {@Code "@IndentedDisplay"}, and (at both margins) for {@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 index c5897de..120331a 100644 --- a/doc/user/str_figs +++ b/doc/user/str_figs @@ -12,10 +12,10 @@ figures. @Index { figures } " @HTree { @Box Lout @FirstSub arrow { yes } @Box PostScript }" "}" } -The @Code "@Figure" symbol places the following object (which in this example is +The @Code "@Figure" symbol places the following object (which in this figure. @Index @Code "@Figure" -created using the advanced graphics features of Chapter {@NumberOf diagrams}) -at the top of the following column or page, +example is created using the {@Code "@Diag"} symbol from +Chapter {@NumberOf diagrams}) at the top of the following column or page, @Figure @Tag { figex } @Caption { Basser Lout } @@ -29,7 +29,7 @@ can see this example at the top of page {@PageOf figex}. Tables are table. @Index @Code "@Table" obtained in the same way using {@Code "@Table"} instead of {@Code "@Figure"}. There is a third symbol called {@Code "@Floater"}. It won't be mentioned -again, but it works exactly like like @Code "@Figure" and {@Code "@Table"}. +again, but it works exactly like @Code "@Figure" and {@Code "@Table"}. @PP @Code "@Figure" and @Code "@Table" each have an @Code "@InitialLanguage" option which determines the language of the figure or table. If this is @@ -50,9 +50,9 @@ 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 +@Code "@Location" option of {@Code "@Figure"}, which determines location. @Index @Code "@Location" -where the figure will appear. Its possible values are +where the figure will appear. Its values are @DP @Tab @Fmta { @Col @Code A ! @Col B } { @@ -102,7 +102,8 @@ from @Code PageFoot only in multi-column documents. } 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}. } +corresponding @Code PageEnd value. +} @Rowa A { AfterLine } B { The figure will appear as a column-width display immediately after @@ -159,7 +160,7 @@ back to a later page than the first possible one. @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 +@ID @OneRow @Tab @Fmta { @Col @Code A ! @Col ! @Col @Code B } { @Rowa @@ -177,7 +178,7 @@ are only default values and you may set @Code "@OnePage" as you wish. 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 { +@ID @OneRow @Code { "@Figure" " @Format { @CurveBox @HExpand @CC @Body }" } diff --git a/doc/user/str_foot b/doc/user/str_foot index 8165a6b..2eea124 100644 --- a/doc/user/str_foot +++ b/doc/user/str_foot @@ -122,9 +122,8 @@ footnotenumbers. @Index @Code "@FootNoteNumbers" it may be {@Code Arabic}, {@Code Roman}, {@Code UCRoman}, {@Code Alpha}, or {@Code UCAlpha}, which give the obvious results. It may also be {@Code Bullets}, which uses sequences of bullets to mark the footnotes, -following a style proposed by typographer Jan Tschichold, and it -may be {@Code Symbols}, which produces the traditional sequence of -daggers and similar symbols. +as proposed by typographer Jan Tschichold, and it may be {@Code Symbols}, +which produces the traditional sequence of daggers and similar symbols. @PP @Code "@FootNoteFont" and @Code "@FootNoteBreak" determine the footnotefont. @Index @Code "@FootNoteFont" diff --git a/doc/user/str_glos b/doc/user/str_glos index 95a91e9..03638cf 100644 --- a/doc/user/str_glos +++ b/doc/user/str_glos @@ -22,7 +22,7 @@ at the end of the document, immediately before any index. @PP To make an entry in the glossary, place something like this in your main text at the point you are defining the term: -@ID @Code @Verbatim { +@ID @OneRow @Code @Verbatim { Object @Glossary { Part of a document occupying a rectangular area; may be a simple word, or a collection of smaller diff --git a/doc/user/str_indx b/doc/user/str_indx index 40c7649..68d1ff1 100644 --- a/doc/user/str_indx +++ b/doc/user/str_indx @@ -35,8 +35,7 @@ To get this into your index, type at the point where you mention Galileo. Nothing will be printed there, but the object following the @Code "@Index" symbol will be placed in index.sym @Index { @Code "@Index" symbol } -the index, with a comma and the correct page number appended -automatically. +the index, plus a comma and the correct page number. @PP The object preceding the @Code "@Index" symbol is a compulsory key which is used for sorting the index entries, @@ -59,8 +58,8 @@ sorting.order @Index { sorting order } if @Code "strcoll()" gets the sorting right for one language, there still remains the problem of sorting multilingual indexes. } -but which is not itself printed anywhere. It is best to construct these -sorting keys from lower-case letters and the . character only, beginning +but which is not itself printed. It is best to construct these +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 @@ -73,9 +72,9 @@ 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 -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 +Our second trick, sub-entries, is also easy, since a sub-entry +is just an ordinary entry with an indent. The symbol is +{@Code "@SubIndex"}, so the second line of our ambitious example is subindex.sym @Index { @Code "@SubIndex" symbol } produced by @ID @Code "galileo.life @SubIndex { life of }" @@ -107,18 +106,17 @@ same page, the @Code "to" option is ignored: you will never get @PP Our fourth 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): +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? +We know how to produce these, using three @Code "@SubIndex" symbols, +one with a @Code "to" option. 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 @@ -130,8 +128,7 @@ three entries, placed in the appropriate places: } 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. +same content ({@Code "trial of"}). @PP Now, having decided that the three entries @ID @OneRow lines @Break { @@ -257,11 +254,10 @@ is complete and an overall plan of the structure of the index can be made. Place index entries for floating figures and tables within their captions. @PP -Large indexes may benefit from {@I spacers} -- empty spaces or +Large indexes may benefit from {@I spacers}: empty spaces or spacers. @Index { spacers in indexes } -even headings between the parts for each letter of the alphabet. One -simple way to get blank line spacers is with {@Code "@RawIndex"}, -like this: +headings between the parts for each letter of the alphabet. One +way to get blank line spacers is with {@Code "@RawIndex"}, like this: @ID @OneRow @Code { "b @RawIndex {}" "c @RawIndex {}" @@ -285,23 +281,23 @@ which letter each index entry belongs under, perhaps by symbols would have been too tedious. } @PP -A more elaborate kind of spacer can be placed into the index with +More elaborate spacers can be inserted with indexspacer. @Index @Code "@IndexSpacer" the @Code "@IndexSpacer" symbol, like this: @ID @Code "a @IndexSpacer A" -This is roughly equivalent to @Code "a @RawIndex A" in that it puts -the entry @Code A at sort position {@Code a}; but it also places -extra space above and below it, and it includes a font change, so -that the @Code A stands out like a heading (you can see the effect -in the index of this document). @Code "@IndexSpacer" also includes -a conditional new page effect, so that the spacer never appears -alone at the bottom of a column. -@PP -You need to change things slightly for the first spacer: +This is similar to @Code "a @RawIndex A" in that it puts the entry +@Code A at sort position {@Code a}; but it also places extra space +above and below it, and it includes a font change, so that the +@Code A stands out like a heading (you can see the effect in the +index of this document). @Code "@IndexSpacer" also includes a +conditional new page, so that the spacer never appears alone at +the bottom of a column. +@PP +The first spacer needs to be slightly different, since no +space is wanted above it: initialindexspacer. @Index @Code "@InitialIndexSpacer" @ID @Code "a @InitialIndexSpacer A" -to tell Lout to omit the unwanted space above it. There is an -@Code "@IndexLetters" symbol which places the 26 spacers +There is an @Code "@IndexLetters" symbol which places the 26 spacers indexletters. @Index @Code "@IndexLetters" @ID @OneRow @Code @Verbatim { a @InitialIndexSpacer A @@ -404,15 +400,13 @@ number of index columns per page, and the gap between them, and are exactly analogous to the @Code "@ColumnNumber" and @Code "@ColumnGap" options described in Section {@NumberOf columns}. @PP -The next three options work together to control the appearance of -running headers +The next three options control the appearance of running headers @FootNote { -Owing to problems behind the scenes, if more than three copies of the -same running header appear on the same page, their horizontal positions -will become confused, probably resulting in the apparent disappearance of -all but the last three. Of course, this is highly unlikely to happen, -since it means there must be a four-column index with a page on which -all four columns have the same running header. +Owing to problems behind the scenes, in the highly unlikely case +where more than three copies of the same running header appear on +the same page, their horizontal positions will become confused, +probably resulting in the apparent disappearance of all but the +last three. } in the index: indexctd. @Index { @Code "@IndexCtd" } @@ -479,11 +473,11 @@ equivalent to Whether you will ever need to vary the appearance of index spacers individually in this way is very doubtful, but the capacity is there. @PP -Lout offers the possibility of having up to three independent indexes -(useful for 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, +Lout offers three independent indexes (useful for author indexes, +etc.). The other two are called index A and index B, and they +precede the main index in the output. Just replace @Code Index +by @Code IndexA to refer to index A, and by @Code IndexB to refer +to index B. For example, @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. There are @@ -496,8 +490,8 @@ be done by placing "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. +in the @Code mydefs file (Section {@NumberOf definitions}). 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_list b/doc/user/str_list index 9747c15..2e56aa1 100644 --- a/doc/user/str_list +++ b/doc/user/str_list @@ -3,7 +3,7 @@ @Tag { lists } @Begin @PP -The @Code "@IndentedList" symbol introduces a sequence of items to be +The @Code "@IndentedList" symbol introduces items to be indentedlist. @Index @Code "@IndentedList" il. @Index @Code "@IL" lists. @Index { lists } @@ -457,9 +457,8 @@ the influence of that symbol. For more information, including another way to insert struts, consult Section {@NumberOf precise}. @PP The @Code "break" option defines a break style (suitable for the -@Code "@Break" symbol) which is to be applied to each item. If -you wanted each item in a ragged style, for example, you could -just write +@Code "@Break" symbol) to be applied to each item. If you want +each item in a ragged style, for example, you could just write @ID @OneRow @Code @Verbatim { @NumberedList break { ragged } diff --git a/doc/user/str_marg b/doc/user/str_marg index f7057c0..246f623 100644 --- a/doc/user/str_marg +++ b/doc/user/str_marg @@ -76,14 +76,13 @@ 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}). +Margin notes work well inside footnotes, figures, and tables, but +badly in multi-column documents unless used sparingly. They do +not appear in plain text output (Section {@NumberOf plain}). @PP -A more radical way to place objects at arbitrary points on the current +The @Code "@Place" symbol can place objects at arbitrary points on +the current page: place. @Index @Code "@Place" -page is provided by the @Code "@Place" symbol: @ID @OneRow @Code { "@Place" " x { right - 1c - xsize }" @@ -156,5 +155,6 @@ 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. +placed object. @Code "@Place" does not take account of the value +of any @Code "@PageOrientation" option. @End @Section diff --git a/doc/user/str_theo b/doc/user/str_theo index 672cd28..da61e11 100644 --- a/doc/user/str_theo +++ b/doc/user/str_theo @@ -83,19 +83,19 @@ are with their default values: "@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 "@TheoremTitleFormat" is used only when the theorem has a +{@Code "@Title"}. It determines how the title is formatted: the +@Code title symbol within it stands for the @Code "@Title" option. +The default value shown places parentheses around the title. +@Code "@TheoremFormat" 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 +nothing and even deletes 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 +spaces into the first paragraph of the body. Another good value is @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}. diff --git a/doc/user/tbl_mult b/doc/user/tbl_mult index 7ab66c9..e716b6a 100644 --- a/doc/user/tbl_mult +++ b/doc/user/tbl_mult @@ -21,10 +21,10 @@ To prevent page breaks within a table, precede the @Code "@Tbl" symbol by {@Code "@OneRow"}: @ID @Code "@CD @OneRow @Tbl ..." @Code "@OneRow" is a general Lout symbol which binds the following -object into a single, unbreakable row. Make sure your table is -small enough to fit on one page when you do this, otherwise an error -message will be printed and it will be scaled to fit. Display symbols -like @Code "@CD" often have this effect anyway. +object into a single, unbreakable row. The table must be small +enough to fit on one page when you do this, otherwise an error +will be printed and it will be scaled to fit. Display symbols +like @Code "@CD" may have this effect anyway. @PP To prevent a page break between two particular rows, but not in general, replace the @Code "@Row" symbol of the second row with @@ -44,18 +44,16 @@ to fit on one page, and it will go wrong on a table containing @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 { +@ID -1px @Break @OneRow @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. +An example appears in Section {@NumberOf tbl_summ}. You can simulate +an indent by an empty cell at the left of each row format. Lout will +expand the rightmost column to the full page width; to prevent this, +add a @Code "|" after the last cell within each {@Code format} option, +creating an empty extra column. @PP One practical problem in multi-page tables is getting the rules right. The simplest way to do this is to set @Code "rulehorizontal" @@ -67,15 +65,15 @@ you to insert a rule after the last line of each page, but not elsewhere. (However, if you are using the @Code "@Table" symbol, its @Code "@Format" option can be used to do this.) @PP -Another practical problem with multi-page tables is that of getting a -heading over every page after the first. This is easy if you know where -the page breaks are going to fall (if you are using {@Code "@NP"}, for -example), but you usually don't. To solve this problem, @Code {"@Tbl"} -offers the @Code "@HeaderRowa" ... @Code "@HeaderRowh" and +Another problem is getting a heading over every page after +the first. This is easy if you know where the page breaks are going +to fall (if you are using {@Code "@NP"}, for example), but you usually +don't. To solve this problem, @Code {"@Tbl"} offers the +@Code "@HeaderRowa" ... @Code "@HeaderRowh" and tables. @RawIndex { tables } tables.headerrow @SubIndex { @Code "@HeaderRow" symbols } headerrow.tables @Index { @Code "@HeaderRow" symbols (tables) } -@Code "@EndHeaderRow" symbols. For example, the multi-page table in +@Code "@EndHeaderRow" symbols. The multi-page table in Section {@NumberOf tbl_summ} is arranged like this: @ID -1px @Break @OneRow @Code @Verbatim { @Tbl diff --git a/doc/user/tbl_plai b/doc/user/tbl_plai index ca20f4b..12ac289 100644 --- a/doc/user/tbl_plai +++ b/doc/user/tbl_plai @@ -3,7 +3,22 @@ @Tag { tbl_plai } @Begin @PP -Tables work well with plain text output (Section {@NumberOf plain}): +@Code "@Tbl" changes the default values of several options when +printing plain text (Section {@NumberOf plain}): +@ID @OneRow @Code @Verbatim { +@Tbl + marginvertical { 2f } + marginhorizontal { 2s } + rulehorizontalwidth { 1f } + ruleverticalwidth { 1s } + rulehorizontalgap { 0f } + ruleverticalgap { 0s } +} +When using plain text it is best 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. +If this is done, the results can be good: tables. @RawIndex { tables } tables.plaintext @SubIndex { plain text output } plain.text.tables @Index { plain text tables } @@ -48,22 +63,7 @@ plain.text.tables @Index { plain text tables } 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 @OneRow @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 +A @Code ruleplainchar option for changing the character used to tables. @RawIndex { tables } tables.ruleplainchar @SubIndex { @Code "ruleplainchar" option } ruleplainchar.tables @Index { @Code "ruleplainchar" option (tables) } @@ -72,13 +72,13 @@ draw rules. For example, @Tbl ruleplainchar { - } } -would be a good choice if you plan to draw only horizontal rules. This -option can be set anywhere as usual. +would be good if you 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 +If you 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 { @@ -86,9 +86,9 @@ the slight asymmetry in the example above; you can correct it with 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. +but rules at the extreme right of the page will still go off the edge, +and rules below the last line will bump 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_setu b/doc/user/tbl_setu index 6caedbb..db5c400 100644 --- a/doc/user/tbl_setu +++ b/doc/user/tbl_setu @@ -9,14 +9,10 @@ tables.setup @SubIndex { setup file } setup.files. @RawIndex { setup files } setup.files.for.tables @SubIndex { for tables } in the @Code { tbl } setup file, in which case the new values become -the default values for every table in the document. This section -explains how to do it. Changing options in the setup file can save a -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 +the default values for every table in the document, which promotes +consistency and can save you a lot of time. 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 @@ -45,10 +41,9 @@ the @Code "@TblSetup" @Code "@Use" clause, which looks like this: # 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: +Only a few of the options are shown here. To change an option, delete +the @Code "#" 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 { none } @@ -56,8 +51,8 @@ surrounding text: # break { } } } -This relative specification of font size is available anywhere, not -just in setup files (Section {@NumberOf fonts}). +Relative font sizes are available anywhere, not just in setup files +(Section {@NumberOf fonts}). @PP Some setup file options contain values which use the @Code "@OrIfPlain" symbol: diff --git a/doc/user/typ b/doc/user/typ index 7ebe52f..aaa1e36 100644 --- a/doc/user/typ +++ b/doc/user/typ @@ -3,17 +3,26 @@ @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 +Different types of documents have different features: title pages in +books, abstracts in technical reports, and so on. Lout offers five +@I { document types } with the appropriate features: ordinary 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. +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. +# @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 } diff --git a/doc/user/typ_apdf b/doc/user/typ_apdf index 232610c..6485a8e 100644 --- a/doc/user/typ_apdf +++ b/doc/user/typ_apdf @@ -26,11 +26,11 @@ is to produce PostScript, and then either pass it through a `distillation' program to produce PDF, or else view it with a PostScript viewer that understands links. @PP -When generating PostScript for subsequent distillation to PDF, the +When generating PostScript for distillation to PDF, the docinfo. @Index @Code "@DocInfo" @Code "@DocInfo" symbol may be useful. Placed anywhere in the -document, it generates PostScript which causes the subsequent PDF to -contain a `document info dictionary' containing the author of the +document, it generates PostScript which causes the PDF to contain +a `document info dictionary' containing the author of the document, its title, and some keywords: @ID @Code @Verbatim { @DocInfo diff --git a/doc/user/typ_book b/doc/user/typ_book index 0f46a47..fa5d33d 100644 --- a/doc/user/typ_book +++ b/doc/user/typ_book @@ -365,6 +365,12 @@ also {@Code "@ColophonInContents"} and {@Code "@ColophonPrefix"} options for determining whether the colophon appears in the table of contents, and its prefix when structured page numbers are used. @PP +In rare combinations of circumstances, another problem behind the +scenes sometimes causes the title of the Colophon to appear, +bizarrely, on the second page of the colophon. If this happens +you can work around it by starting off the body of the colophon +with {@Code "@NP"}. +@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 diff --git a/doc/user/typ_ordi b/doc/user/typ_ordi index 36feefa..49b0397 100644 --- a/doc/user/typ_ordi +++ b/doc/user/typ_ordi @@ -43,8 +43,8 @@ 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 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"}. +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 @@ -111,9 +111,7 @@ 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 }" -"}" +"@FullWidth { @CentredDisplay @Heading { NOTICE TO TRESPASSERS } }" "@PP" "Trespassers are hereby notified that, ..." } diff --git a/doc/user/typ_orga b/doc/user/typ_orga index ce49851..ab8beef 100644 --- a/doc/user/typ_orga +++ b/doc/user/typ_orga @@ -101,8 +101,8 @@ with a name, which you can use with confidence anywhere at all. Second, Lout treats @Code "@Include" in a peculiar way when it appears in the setup part of a document (in definitions, databases, and the @Code "@Use" clauses that appear within setup files): it -reads the file as usual the first time, and silently skips it the -other times. This is done to simplify the handling of files of +reads the file the first time, but silently skips it the other +times. This is done to simplify the handling of files of definitions that depend on other files of definitions, as described in the Expert's Guide @Cite { $kingston1995lout.expert }. @End @Section diff --git a/doc/user/typ_over b/doc/user/typ_over index 8188422..48ee1ad 100644 --- a/doc/user/typ_over +++ b/doc/user/typ_over @@ -3,20 +3,19 @@ @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 +To produce overhead transparencies (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: +# @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. +# } @ID @OneRow @Code { "@SysInclude { slides }" "@OverheadTransparencies" diff --git a/doc/user/typ_plai b/doc/user/typ_plai index 00aa8b9..af0f08f 100644 --- a/doc/user/typ_plai +++ b/doc/user/typ_plai @@ -66,11 +66,11 @@ right. 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; floating 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. +the plain text output to appear unpaginated, that is, in one continous +stream with no page breaks. It is ignored if plain text output is +not in effect, so it can be set to @Code "Yes" in documents intended +for formatting both ways. The usual margins apply; footnotes appear +at the end; floating 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 index fe41acc..0c41ff4 100644 --- a/doc/user/typ_repo +++ b/doc/user/typ_repo @@ -50,8 +50,8 @@ 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: +{@NumberOf paras}), which centres each line, so multi-line titles +make sense: @ID @OneRow @Code { "@Report" " @Title {" @@ -338,9 +338,9 @@ 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: +@Code "@SectionHeadingFont" is the font of 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: @ID @Code "@SectionHeadingFont { Helvetica Base +2p }" produces section headings in the Helvetica font, two points larger than the initial font size. diff --git a/doc/user/vbas b/doc/user/vbas index 0004cfb..0004cfb 100644..100755 --- a/doc/user/vbas +++ b/doc/user/vbas diff --git a/doc/user/vbgr b/doc/user/vbgr index be6461c..be6461c 100644..100755 --- a/doc/user/vbgr +++ b/doc/user/vbgr diff --git a/doc/user/vdia b/doc/user/vdia index 27c456c..27c456c 100644..100755 --- a/doc/user/vdia +++ b/doc/user/vdia diff --git a/doc/user/vequ b/doc/user/vequ index 87cdf93..87cdf93 100644..100755 --- a/doc/user/vequ +++ b/doc/user/vequ diff --git a/doc/user/vfmt b/doc/user/vfmt index 3e6af88..3e6af88 100644..100755 --- a/doc/user/vfmt +++ b/doc/user/vfmt diff --git a/doc/user/vgra b/doc/user/vgra index 60b9b5b..60b9b5b 100644..100755 --- a/doc/user/vgra +++ b/doc/user/vgra diff --git a/doc/user/vpie b/doc/user/vpie index 5f9e2e4..5f9e2e4 100644..100755 --- a/doc/user/vpie +++ b/doc/user/vpie diff --git a/doc/user/vprg b/doc/user/vprg index 81c0abe..81c0abe 100644..100755 --- a/doc/user/vprg +++ b/doc/user/vprg diff --git a/doc/user/vref b/doc/user/vref index 7e85672..7e85672 100644..100755 --- a/doc/user/vref +++ b/doc/user/vref diff --git a/doc/user/vstr b/doc/user/vstr index 7f4e2d0..7f4e2d0 100644..100755 --- a/doc/user/vstr +++ b/doc/user/vstr diff --git a/doc/user/vtbl b/doc/user/vtbl index 68159ce..68159ce 100644..100755 --- a/doc/user/vtbl +++ b/doc/user/vtbl diff --git a/doc/user/vtyp b/doc/user/vtyp index a360b04..a360b04 100644..100755 --- a/doc/user/vtyp +++ b/doc/user/vtyp |