diff options
Diffstat (limited to 'doc')
45 files changed, 1434 insertions, 326 deletions
diff --git a/doc/expert/README b/doc/expert/README index 9b9c3e0..d066d57 100644 --- a/doc/expert/README +++ b/doc/expert/README @@ -16,4 +16,4 @@ copy of the final outfile.ps is included. There should be no warning messages on the fifth run. Jeffrey H. Kingston -!7 September 1999 +26 February 2000 diff --git a/doc/expert/all b/doc/expert/all index 46471c0..e2a5a78 100644 --- a/doc/expert/all +++ b/doc/expert/all @@ -10,9 +10,9 @@ Lout Document Formatting System } @Author { Jeffrey H. Kingston } - @Edition { Version 3.17 -September, 1999 } - @Publisher { @I { @CopyRight Copyright 1991, 1999, Jeffrey + @Edition { Version 3.18 +February, 2000 } + @Publisher { @I { @CopyRight Copyright 1991, 2000, Jeffrey H. Kingston, Basser Department of Computer Science, The University of Sydney 2006, Australia.} } @InitialLanguage { English } diff --git a/doc/expert/det_gall b/doc/expert/det_gall index e68d58f..e5e6e99 100644 --- a/doc/expert/det_gall +++ b/doc/expert/det_gall @@ -325,24 +325,33 @@ enclose.sym @Index @@Enclose meaning: when components of the galley replace a @@Galley or @@ForceGalley symbol, that symbol is first replaced by @@Enclose @@Galley or @@Enclose @@ForceGalley. For example, -@ID @Code { -"def @Enclose" -" right x" -"{" -" @Box x" -"}" +@ID @Code @Verbatim { +def @Figure into @FigurePlace&&following + right @Body +{ + def @Enclose + right x + { + @Box x + } + + @Body +} } -within some galley definition causes each @@Galley or @@ForceGalley -symbol that receives components of the galley to be replaced by -{@Code "@Box @Galley"} or {@Code "@Box @ForceGalley"}, assuming an -appropriate definition of @Code "@Box". This is useful, for example, -when producing multi-page boxed displays, figures, and tables. +causes each @@Galley or @@ForceGalley symbol that receives components of +galley @Code "@Figure" to be replaced by {@Code "@Box @Galley"} or +{@Code "@Box @ForceGalley"}, assuming an appropriate definition of +@Code "@Box". This is useful, for example, when producing multi-page +boxed displays, figures, and tables. @PP An @@Enclose symbol may have only one parameter, which must be a right parameter. It would not make sense to allow more parameters, since there is no suitable value to assign to them. However, the @@Enclose symbol may contain inner definitions, and it may make use -of any symbol that is available at that point, in the usual way. +of any symbol that is available at that point, in the usual way. The +@@Enclose symbol may be a named parameter (itself with a right parameter) +of the galley symbol, rather than an inner definition as shown above, +if desired. @PP A @Code "following" galley may fail to find a first target lying in a following component of the same galley as its invocation point. This is diff --git a/doc/expert/det_lexi b/doc/expert/det_lexi index e0ad9f1..4f98875 100644 --- a/doc/expert/det_lexi +++ b/doc/expert/det_lexi @@ -98,6 +98,8 @@ do so. The complete list of predefined identifiers is @JL "@CurrFace" @JL "@CurrFamily" @JL "@CurrLang" + @JL "@CurrYUnit" + @JL "@CurrZUnit" @JL "@Database" @JL "@End" @JL "@Enclose" @@ -117,9 +119,9 @@ do so. The complete list of predefined identifiers is @JL "@HLimited" @JL "@HScale" @JL "@HShift" - @JL "@HSpan" } |4.4cx { - "@Include" + "@HSpan" + @JL "@Include" @JL "@IncludeGraphic" @JL "@Insert" @JL "@KernShrink" @@ -142,15 +144,16 @@ do so. The complete list of predefined identifiers is @JL "@OneRow" @JL "@Open" @JL "@Optimize" + @JL "@Outline" @JL "@PAdjust" @JL "@PageLabel" @JL "@PlainGraphic" @JL "@Plus" @JL "@PrependGraphic" @JL "@RawVerbatim" - @JL "@Rotate" } |4.4cx { - "@Rump" + "@Rotate" + @JL "@Rump" @JL "@Scale" @JL "@SetColor" @JL "@SetColour" diff --git a/doc/expert/det_size b/doc/expert/det_size index aea894b..56738ac 100644 --- a/doc/expert/det_size +++ b/doc/expert/det_size @@ -26,6 +26,7 @@ measurement (Section {@NumberOf yunit}); } (also defining the @Code v unit); } @ListItem { Whether to permit hyphenation or not; } @ListItem { What colour the object is to appear in; } +@ListItem { Whether @@Outline is in effect; } @ListItem { The language of the object; } @ListItem { Whether @@VAdjust, @@HAdjust and @@PAdjust are in effect. } @EndList @@ -34,16 +35,16 @@ document. For example, the style of a parameter depends on where it is used; the style of a galley is the style of the first target that it attempts to attach itself to. Of course, the style of any object can be changed by using the @@Font, @@Break, @@Space, @@SetColour or -@@SetColor, and @@Language symbols. +@@SetColor, @@Outline, and @@Language symbols. @PP There are no standard default values for style, except that small capitals -are initially off, the interpretation of white space is initially {@Code -lout}, and the values of the @Code y and @Code z units are zero. Therefore -one must ensure that the root galley or each of its components is enclosed -in @@Font, @@Break, @@SetColour or @@SetColor, and @@Language symbols. From -there the style is passed to incoming galleys and the objects within -them. Enclosure in @@Space is not required because the @Code "s" unit -is also set by @@Font (Section {@NumberOf space}). +and outlining are initially off, the interpretation of white space is +initially {@Code lout}, and the values of the @Code y and @Code z units +are zero. Therefore one must ensure that the root galley or each of its +components is enclosed in @@Font, @@Break, @@SetColour or @@SetColor, and +@@Language symbols. From there the style is passed to incoming galleys +and the objects within them. Enclosure in @@Space is not required because +the @Code "s" unit is also set by @@Font (Section {@NumberOf space}). @PP width. @Index { Width of an object } height. @Index { Height of an object } diff --git a/doc/expert/mydefs b/doc/expert/mydefs index e7f0d15..0a4d364 100644 --- a/doc/expert/mydefs +++ b/doc/expert/mydefs @@ -24,6 +24,8 @@ def @@CurrLang { @Code "@CurrLang" } def @@CurrFamily { @Code "@CurrFamily" } def @@CurrFace { @Code "@CurrFace" } + def @@CurrYUnit { @Code "@CurrYUnit" } + def @@CurrZUnit { @Code "@CurrZUnit" } def @@Database { @Code "@Database" } def @@End { @Code "@End" } def @@Enclose { @Code "@Enclose" } @@ -60,9 +62,10 @@ def @@OneOf { @Code "@OneOf" } def @@OneRow { @Code "@OneRow" } def @@Open { @Code "@Open" } + def @@Outline { @Code "@Outline" } def @@PAdjust { @Code "@PAdjust" } def @@PageLabel { @Code "@PageLabel" } - def @@PlainGraphic { @Code "@PlainGraphic" } + def @@PlainGraphic { @Code "@PlainGraphic" } def @@PrependGraphic { @Code "@PrependGraphic" } def @@RawVerbatim { @Code "@RawVerbatim" } def @@Rotate { @Code "@Rotate" } diff --git a/doc/expert/pre b/doc/expert/pre index 72a4fa3..02320cc 100644 --- a/doc/expert/pre +++ b/doc/expert/pre @@ -10,6 +10,7 @@ @Include { pre_spac } @Include { pre_yuni } @Include { pre_colo } +@Include { pre_outl } @Include { pre_lang } @Include { pre_oner } @Include { pre_wide } diff --git a/doc/expert/pre_outl b/doc/expert/pre_outl new file mode 100644 index 0000000..f62ec9f --- /dev/null +++ b/doc/expert/pre_outl @@ -0,0 +1,21 @@ +@Section + @Title { "@Outline" } + @Tag { outline } +@Begin +@PP +The @@Outline symbol +outline.sym @Index { @@Outline symbol } +causes all the words in the right parameter (which may be an +arbitrary object) to be printed in outline, rather than filled as +is usual. For example, +@ID @Code @Verbatim { @Outline @Box 24p @Font HELP } +produces +@ID @Outline @Box 24p @Font HELP +Outlining is part of the style information, in the same way as +colour, font, underlining, and so forth. Outlining can be applied +to any font likely to be used in practice. At the time of writing, +there is no way to control the thickness of the outline, and +@@Outline has no effect in PDF output. The size of outlined +words is taken by Lout to be the same as if they had not been +outlined, even though they are in reality slightly larger. +@End @Section diff --git a/doc/expert/pre_yuni b/doc/expert/pre_yuni index 7b06b5d..cd5dd17 100644 --- a/doc/expert/pre_yuni +++ b/doc/expert/pre_yuni @@ -1,5 +1,5 @@ @Section - @Title { "@YUnit" and "@ZUnit" } + @Title { "@YUnit", "@ZUnit", "@CurrYUnit", and "@CurrZUnit" } @Tag { yunit } @Begin @PP @@ -21,6 +21,13 @@ but it may begin with @Code "+" or @Code "-" to indicate that value is to be added to or subtracted from the current value. Any negative result of using @Code "-" will be silently replaced by zero. @PP +The @@CurrYUnit and @@CurrZUnit symbols report the value of the @Code y +and @Code z units, in points, truncated to the nearest integer. For example, +@ID @Code "1i @YUnit { The current value of the y unit is @CurrYUnit }" +produces +@ID @Code "1i @YUnit { The current value of the y unit is @CurrYUnit }" +since there are 72 points in one inch (at least, Lout thinks there are). +@PP These units are not used internally by Lout. They are supplied as part of the style information for the convenience of application packages. For example, the Eq equation formatting package uses them diff --git a/doc/expert/preface b/doc/expert/preface index 1150929..9e37913 100644 --- a/doc/expert/preface +++ b/doc/expert/preface @@ -21,7 +21,7 @@ This manual presents Version 3 of Basser Lout, publicly released in September 1994 @Cite { $kingston1995lout.program }. This manual was rendered into PostScript postscript @Index { PostScript } -by Version 3.17 of the Basser Lout interpreter, using the symbols +by Version 3.18 of the Basser Lout interpreter, using the symbols described in the User's Guide @Cite { $kingston1995lout.user }. @DP @Heading { Acknowledgment. } Version 3 has benefited from hundreds of diff --git a/doc/slides/README b/doc/slides/README index a494b7c..66d5a78 100644 --- a/doc/slides/README +++ b/doc/slides/README @@ -15,4 +15,4 @@ after the second run. A copy of the final outfile.ps is included. Jeff Kingston -17 September 1999 +26 February 2000 diff --git a/doc/user/README b/doc/user/README index fd69ccb..2363b0c 100644 --- a/doc/user/README +++ b/doc/user/README @@ -16,9 +16,9 @@ nearly all beginning with "unresolved cross reference". These should gradually go away on later runs. The following shows the error message output on the fifth run for A4 size printing: -lout file "cpp_tabs" (from "cpp" line 24, from "all" line 38): - 53,23: c2lout: C text ended inside a comment - 55,35: c2lout: C text ended inside a comment +lout file "cpp_tabs" (from "cpp" line 80, from "all" line 45): + 56,23: prg2lout 2,1: program text ended within comment + 58,35: prg2lout 2,1: program text ended within comment These two warnings point to two places where a C program text ended inside a comment, which in these cases was deliberate so is no problem. @@ -31,7 +31,7 @@ repeated failure to converge, caused by footnotes and floating figures close to large unbreakable displays. A copy of the final PostScript output file (A4 paper size) is -stored at "ftp://ftp.cs.su.oz.au/jeff/lout/lout.3.17.user.ps.gz". +stored at "ftp://ftp.cs.su.oz.au/jeff/lout/lout-3.18.user.ps.gz". Jeffrey H. Kingston -17 September 1999 +23 February 2000 diff --git a/doc/user/all b/doc/user/all index 1b131f6..ef7fcdf 100644 --- a/doc/user/all +++ b/doc/user/all @@ -6,6 +6,7 @@ @SysInclude { pas } @SysInclude { diag } @SysInclude { cprint } +@SysInclude { eiffel } @SysInclude { book } # @Include { letterbook } # for testing Letter size formatting @@ -19,10 +20,10 @@ Lout Document Formatting System } @Author { Jeffrey H. Kingston } - @Edition { Version 3.17 -September, 1999 } + @Edition { Version 3.18 +February, 2000 } @Publisher { -Copyright @CopyRight 1991, 1999 Jeffrey H. Kingston, +Copyright @CopyRight 1991, 2000 Jeffrey H. Kingston, Basser Department of Computer Science, The University of Sydney 2006, Australia. ISBN 0 86758 951 5. } diff --git a/doc/user/ap_qck b/doc/user/ap_qck index 92ea7ad..092673d 100644 --- a/doc/user/ap_qck +++ b/doc/user/ap_qck @@ -56,8 +56,8 @@ " @PageHeaders { Simple }" " @FirstPageNumber { 1 }" " @ColumnNumber { 1 }" +" @Abstract { ... }" "//" -"@Abstract ... @End @Abstract" "@Section ... @End @Section" "@Appendix ... @End @Appendix" } diff --git a/doc/user/bas_lang b/doc/user/bas_lang index 3b32a94..01fbf2d 100644 --- a/doc/user/bas_lang +++ b/doc/user/bas_lang @@ -45,6 +45,7 @@ Hungarian Magyar Italian Italiano Norwegian Norsk Polish Polski +Portuguese Português Russian Slovenian Slovenia Slovenija Spanish Espa{@Char ntilde}ol diff --git a/doc/user/bgr b/doc/user/bgr index 9452ff0..86e0af4 100644 --- a/doc/user/bgr +++ b/doc/user/bgr @@ -10,6 +10,7 @@ get them. @BeginSections @Include { bgr_colo } @Include { bgr_boxs } +@Include { bgr_outl } @Include { bgr_rota } @Include { bgr_scal } @Include { bgr_incl } diff --git a/doc/user/bgr_outl b/doc/user/bgr_outl new file mode 100644 index 0000000..af11eb1 --- /dev/null +++ b/doc/user/bgr_outl @@ -0,0 +1,16 @@ +@Section + @Title { Outlined words } + @Tag { outline } +@Begin +@PP +The @@Outline symbol +outline.sym @Index { @@Outline symbol } +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 +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. +@End @Section diff --git a/doc/user/cpp b/doc/user/cpp index 9b413ed..0e7748a 100644 --- a/doc/user/cpp +++ b/doc/user/cpp @@ -1,27 +1,86 @@ @Chapter - @Title { C and C++ Programs } + @Title { Computer Programs } @Tag { cprint } @Begin @LP -This chapter describes how to typeset C and C++ program text using the -cp. @Index @Code "@CP" -c. @Index { C++ } -@Code "@CP" symbol in conjunction with the @Code c2lout filter. The -@Code "@CP" symbol looks after printing keywords in bold, variables -in italic, and so on, depending on a style you choose. It does not lay -out programs in the sense of choosing indenting, it preserves the layout -you give to the program. From now on, `C' means `C or C++' wherever -it occurs. +This chapter describes how to typeset computer program text using Lout +in conjunction with the @Code prg2lout +prg2lout. @Index { @Code prg2lout filter program } +@FootNote { +Prior to Version 3.18 of Lout, this chapter described how to typeset +programs written in the C programming language using the +@Code c2lout filter, and Eiffel programs using the @Code eif2lout +filter. These have now been withdrawn and replaced by {@Code prg2lout}, +which handles multiple languages. Ordinary Lout documents require no +modifications as a result of this change. +} +filter program, which is always installed wherever Lout is. @PP -It is possible to simply print out one or more C files; we call this -@I { stand-alone mode }. Alternatively, the C program text may be printed -as part of a larger Lout document; we call this @I { embedded mode }. +It is possible to simply print out one or more program files independently +of any document. Alternatively, the program text may be printed as part of +a larger Lout document. Either way, Lout does not lay out the programs in +the sense of choosing line breaks and indenting; it uses whatever line +breaks and indenting you give to the program. What Lout does do is cope +with characters in the program text that it would ordinarily either reject +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, etc. +@PP +At the time of writing, the available programming languages are: +eiffel. @Index { Eiffel program printing } +c. @Index { C and C++ program printing } +blue. @Index { Blue program printing } +@CD @Tbl + mv { 0.5vx } + af { Italic } + arb { yes } + aformat { @Cell A | @Cell B | @Cell C | @Cell D | @Cell E } + bformat { @Cell A | @Cell @Code B | @Cell @Code C | @Cell @Code D | @Cell E } +{ +@Rowa + A { Language name } + B { Setup file name } + C { Lout symbol } + D { Default style } + E { ` ' escapes } +@Rowb + A { C, C++ } + B { cprint } + C { "@CP" } + D { fixed } + E { No } +@Rowb + A { Eiffel } + B { eiffel } + C { "@Eiffel" } + D { varying } + E { Yes } +@Rowb + A { Blue } + B { blue } + C { "@Blue" } + D { varying } + E { Yes } +} +C and C++ are handled together since, for formatting purposes, they +differ only in that C++ has some additional keywords plus an extra +way to make comments. Whenever we mention C from now on, we mean +both C and C++. The second to fifth columns of this table will be +explained at various points later in this chapter. +@PP +The list of languages is likely to expand, because the @Code "prg2lout" +program has been designed to make it easy to add new languages. Consult +the instructions at the top of the source file of that program if you +want to try it yourself. @BeginSections @Include { cpp_lone } @Include { cpp_embe } +@Include { cpp_opti } @Include { cpp_chan } -@Include { cpp_comm } @Include { cpp_tabs } -@Include { cpp_eiff } +@Include { cpp_comm } +@Include { cpp_prog } +@Include { cpp_pipe } +@Include { cpp_erro } @EndSections @End @Chapter diff --git a/doc/user/cpp_chan b/doc/user/cpp_chan index ddedd51..bee0493 100644 --- a/doc/user/cpp_chan +++ b/doc/user/cpp_chan @@ -1,27 +1,28 @@ @Section - @Title { Changing the default values } + @Title { Changing the appearance of all programs simultaneously } @Tag { cpsetup } @Begin @PP -We have just seen that the @Code "@CP" symbol has many options for -changing the appearance of the C text. However, most people would -not want to have a different style for every C text in their document; -they want to define the style once at the start, and have all their -C texts come out in that style without laboriously setting options -on every @Code "@CP" symbol. This is done by copying the setup file -and changing it. +We have just seen that the {@Code "@CP"}, {@Code "@Eiffel"} etc. symbols +have many options for changing the appearance of the program text. However, +most people would not want to have a different style for every program text +in their document; they want to define the style once at the start, and have +all their program texts come out in that style without laboriously setting +options on every symbol. You do this by copying the setup file and +changing it. @PP For general information about how to make your own setup file, consult Section {@NumberOf setup}. The options that determine the default -values are in the @Code "@CPSetup" @Code "@Use" clause near the end of +values are in the @Code "@Use" clause which occupies most of the setup +file. Here is the @Code "@Use" clause from {@Code cprint}: cprint. @Index @Code "@CPSetup" -the @Code "cpsetup." setup file: -@ID @Code @Tab - vmargin { 0.5vx } - @Fmta { @Col A ! @Col B ! @Col C} - @Fmtb { @Col { " #" A } ! @Col { "{" B } ! @Col "}" } +@ID @Code @Tbl + mv { 0.5vx } + aformat { @Cell A | @Cell B | @Cell C } + bformat { @Cell { " #" A } | @Cell { "{" B } | @Cell "}" } { @Rowa A { "@Use { @CPSetup" } +@Rowb A { "pipe" } B { } @Rowb A { "style" } B { fixed } @Rowa @@ -65,13 +66,13 @@ the @Code "cpsetup." setup file: @Rowa A { "}" } } -These show the default font families, font faces, font sizes, line +This shows the default font families, font faces, font sizes, line spacings, and tab settings in force for the three styles, and also that the default style is {@Code "fixed"}. Notice that the font family name for @Code "fixed" style is {@Code "Courier"}, but for the other styles is empty. This causes the @Code "fixed" style to always switch to Courier, and the other styles to use the same font family as in the surrounding -document. +document. The @Code pipe option will be explained in Section {@NumberOf pipes}. @PP To change a default value, delete the preceding @Code "#" and change the part between braces. For example, suppose you are happy with @Code "fixed" @@ -80,4 +81,11 @@ except that you want bold keywords. Then one line needs to be changed, to Or suppose you like @Code "varying" as it stands, but would like it to be the default style rather than {@Code "fixed"}. Again, only one line needs to be changed, to {@Code "style { varying }"}. +@PP +The setup files for the other languages are identical to this one, except +that the symbol after @Code "@Use" is different, and some of the +default values may be different. Changing an option affects only the +language of that setup file; if you have multiple languages you can +have multiple setup files and change their options quite independently +of each other. @End @Section diff --git a/doc/user/cpp_comm b/doc/user/cpp_comm index f877c06..96ac110 100644 --- a/doc/user/cpp_comm +++ b/doc/user/cpp_comm @@ -1,20 +1,27 @@ @Section - @Title { Lout inside C comments } + @Title { Embedding Lout commands within program comments } @Tag { cpcomm } @Begin @PP -It is possible to embed Lout text inside C and C++ comments, by -starting off the comment with an @Code "@" character. The entire -comment after the @Code "@" character should be Lout text. For -example, to force Lout to start a new page at some point within a C -program, place +It is possible to embed Lout text inside program comments. How this +is done could in principle vary from language to language, but in +every language supported so far it is done by starting off the comment +with an @Code "@" character. If the language has several ways to get +a comment, this will work every way. The entire comment after the @Code "@" +character should then be Lout text. For example, to force Lout to start +a new page at some point within a C program, place @ID @Code "/*@ @NP */" -at that point. Or you could make a heading like this: -@ID @Code "/*@ @Display @Heading { treeprint() } */" -Other possible uses for this feature include index entries and margin -notes. Incredible as it may seem, you can even write +at that point. (In this case you can also simply include a formfeed +formfeed. @Index { formfeed in program texts } +character, control-L, without any comment; whatever the language, a formfeed +in program text is taken to be a request to start a new page.) Or, to +make a heading in an Eiffel program, do this: +@ID @Code "--@ @Display @Heading { treeprint() }" +(Eiffel comments begin with @Code "--" and end at the end of the +line.) Other possible uses for this feature include index entries and +margin notes. Incredible as it may seem, you can even write @ID @Code "/*@ @CD @Heading { Function @CP { treeprint() } } */" with a @Code "@CP" symbol and some C code inside the Lout code -inside the C code. You probably can't go further, however, since -that would require a C comment inside a C comment. +inside the C code. You probably can't go further, however, at least +not in C, since that would require a C comment inside a C comment. @End @Section diff --git a/doc/user/cpp_eiff b/doc/user/cpp_eiff deleted file mode 100644 index d0ec6df..0000000 --- a/doc/user/cpp_eiff +++ /dev/null @@ -1,42 +0,0 @@ -@Section - @Title { Eiffel program printing } - @Tag { eiffel } -@Begin -@PP -There is an @Code "@Eiffel" symbol for typesetting Eiffel programs -in conjuction with a filter called {@Code "eif2lout"}. Apart from -the change of language, everything is identical to C printing. The -file and symbol names are different, of course: -@ID @OneRow @Tab - vmargin { 0.5vx } - @Fmta { @Col A ! @Col B } -{ -@Rowa - A { @Code cprint } - B { @Code eiffel } -@Rowa - A { @Code c2lout } - B { @Code eif2lout } -@Rowa - A { @Code "@CP" } - B { @Code "@Eiffel" } -@Rowa - A { @Code "@CPSetup" } - B { @Code "@EiffelSetup" } -} -but everything works in an exactly analogous way: you place -@ID @Code "@SysInclude { eiffel }" -at the top of your document, enclose Eiffel program texts in -@Code "@Eiffel { ... }", embed Lout into Eiffel using comments -beginning with {@Code "--@"}, and so on. The default style has been -changed to {@Code varying}, so as to conform to the style guidelines -in the standard Eiffel reference @Cite { $meyer1992eiffel }. Some care -has gone into making this conformance strict; in particular, if you -enclose identifiers within comments in ` and ', as the style guidelines -say you should, they will come out in italics; in fact, arbitrary text -between ` and ' within comments will be set as Eiffel code. -@PP -The files needed for Eiffel printing are distributed separately from -Basser Lout. You can get them from the author's @Code ftp directory -(see the preface of this guide). -@End @Section diff --git a/doc/user/cpp_embe b/doc/user/cpp_embe index 8ca2dfc..0cefc84 100644 --- a/doc/user/cpp_embe +++ b/doc/user/cpp_embe @@ -1,11 +1,11 @@ @Section - @Title { Embedded mode } + @Title { Typesetting computer programs as part of a larger document } @Tag { embedded } @Begin @PP -When the C program texts are to be embedded in a larger Lout document, -the procedure is somewhat different. You need to include the -@Code "cprint" setup file, like this: +When the program texts are to be part of a larger Lout document, +the procedure is somewhat different. You need to include the setup file +appropriate to your language, like this: @ID @OneRow @Code { "@SysInclude { cprint }" "@SysInclude { doc }" @@ -13,9 +13,13 @@ the procedure is somewhat different. You need to include the "..." "@End @Text" } -This file includes everything needed to set up for C program formatting. +The @Code cprint setup file includes everything needed to set up for C +program formatting; for the other languages, consult the second column +of the table at the start of this chapter. @PP -The C parts of the document are enclosed in @Code "@CP { ... }" like this: +The program texts within the Lout document are enclosed in braces +preceded by the Lout symbol from the third column of the table, like +this for the C language: @ID @OneRow @Code { "@IndentedDisplay @CP {" "#include <stdio.h>" @@ -31,9 +35,10 @@ The C parts of the document are enclosed in @Code "@CP { ... }" like this: "}" "}" } -Although C programs violate the rules of legal Lout input in many ways, -these rules are suspended by the @Code "@CP" symbol, allowing the C -text to be incorporated with absolutely no modifications. The result is +Although computer programs violate the rules of legal Lout input in many ways, +these rules are suspended by the {@Code "@CP"}, {@Code "@Eiffel"} etc. symbols, +allowing the program text to be incorporated with absolutely no +modifications. The result is @ID @OneRow @CP { #include <stdio.h> @@ -49,104 +54,29 @@ struct tnode *p; } We have chosen to use the @Code "@IndentedDisplay" symbol from Section {@NumberOf displays} to obtain an indented display, but in fact -@Code "@CP" may appear anywhere at all. When including a C text within -a paragraph, use @Code "@OneCol @CP { ... }" to prevent it being broken -across two lines, if desired. +{@Code "@CP"}, {@Code "@Eiffel"} and the rest may appear anywhere at +all: the result is an object in the usual way, which may go +anywhere. When including a program text within a paragraph, use +@Code "@OneCol @CP { ... }" (or @Code "@OneCol @Eiffel { ... }" etc. for +other languages) to prevent it being broken across two lines, if desired. @PP -In cases where the C text has unbalanced braces, it is necessary to -use the alternative form @Code "@CP @Begin ... @End @CP" so that -Lout does not confuse C braces with Lout braces. +In cases where the program text has unbalanced braces, it is necessary to +use the alternative form @Code "@CP @Begin ... @End @CP" (or the +equivalent for other languages), so that Lout does not confuse program +braces with Lout braces. In that case the program text must not +contain {@Code "@End"}; and in either case the program text must not +include @Code "@Include" or @Code "@SysInclude" unless you are really +including a file at that point (which is allowed, and follows the +rules given for @Code "@Verbatim" in Section {@NumberOf verbatim}). @PP -The @Code "@CP" symbol has a @Code "style" option for changing the -printing style. The default value of @Code "style" is {@Code "fixed"}, -which produces the style shown above. To obtain a varying-width font -style, use @Code "style { varying }" like this: -@ID @OneRow @Code { -"@CP" -" style { varying }" -"{" -"#include <stdio.h>" -"" -"treeprint(p) /* print tree p recursively */" -"struct tnode *p;" -"{" -" if (p != NULL) {" -" treeprint(p->left);" -" printf(\"%4d %s\\n\", p->count, p->word);" -" treeprint(p->right);" -" }" -"}" -"}" -} -The result in this case will be -@ID @OneRow @CP style { varying } -{ -#include <stdio.h> - -treeprint(p) /* print tree p recursively */ -struct tnode *p; -{ - if (p != NULL) { - treeprint(p->left); - printf("%4d %s\n", p->count, p->word); - treeprint(p->right); - } -} -} -There is also a third style called @Code "style { symbol }" which is -similar to @Code "varying" except that it uses characters from the -Adobe Symbol font to produce a more mathematical-looking result: -@ID @OneRow @CP style { symbol } -{ -#include <stdio.h> - -treeprint(p) /* print tree p recursively */ -struct tnode *p; -{ - if (p != NULL) { - treeprint(p->left); - printf("%4d %s\n", p->count, p->word); - treeprint(p->right); - } -} -} -The @Code "@CP" symbol has additional options which allow a finer -control over the style. Here they all are, with their default values: -@ID @OneRow @Code { -"@CP" -" style { fixed }" -" font { Courier }" -" strings { Base }" -" identifiers { Base }" -" comments { Base }" -" keywords { Base }" -" numbers { Base }" -" operators { Base }" -" size { -1.0p }" -" line { 1.0vx }" -" tabin { 8 }" -" tabout { 8s }" -"{" -" ..." -"}" -} -We are already familiar with {@Code "style"}. After that comes -{@Code "font"}, which determines the font family to use, followed -by six options giving the particular faces within that family in which to -print C strings, identifiers, comments, keywords, numbers, and -operators. {@Code "Base"} means the basic face; other commonly available -choices are {@Code "Slope"} and {@Code "Bold"}. These options may all be -set to different faces if desired. The default values shown are correct -for @Code "style { fixed }" only; the other styles have other defaults -(Section {@NumberOf cpsetup}). -@PP -The @Code "size" option is the font size to use, and @Code "line" is the -inter-line spacing. The default values specify that @Code "size" is -to be one point smaller than in the surrounding document; this was done -to compensate for Courier's relatively large appearance compared -to other fonts of the same nominal size. Again, these defaults are -different for different values of {@Code "style"}. -@PP -The @Code "tabin" and @Code "tabout" options are the subject of -Section {@NumberOf tabs}. +If your Lout document contains program texts in several languages, +simply add one @Code "@SysInclude" line for each of them and proceed +as before. If your programming language is not currently supported, +a viable alternative is +@ID @Code "@F @Verbatim { ... }" +These symbols cause the text between braces to be set verbatim in +a fixed-width font, as explained elsewhere in this guide. This fallback +method will not handle tab and formfeed characters very well. Again, +use @Code "@Begin" and @Code "@End @Verbatim" instead of braces if +your program text contains unbalanced braces. @End @Section diff --git a/doc/user/cpp_erro b/doc/user/cpp_erro new file mode 100644 index 0000000..ff89591 --- /dev/null +++ b/doc/user/cpp_erro @@ -0,0 +1,39 @@ +@Section + @Title { Error messages } + @Tag { cpp_erro } +@Begin +@PP +In order to understand the error messages produced by program +printing, it is necessary to understand that Lout's first step when +given a program text is to pass it to the separate {@Code prg2lout} +program for analysis. This separate program is the source of most +of the error messages associated with program printing. +@PP +The {@Code prg2lout} program is quite happy to format a fragment of a +computer program: there is no need to supply a complete routine, or +a complete statement, or any such thing. However, it will complain if +you supply only a fragment of one lexical unit, such as a comment or +string without its terminating delimiter. It will also complain if +there is a character that cannot be classified as part of an identifier, +number, etc. according to the rules of the language as they have been +given to @Code prg2lout by the implementer. Irrespective of the +language rules, @Code prg2lout always interprets spaces, tabs, newlines, +and formfeed characters in the usual way. +@PP +If an error message is generated by {@Code prg2lout}, it will contain +a line and column number counting from the start of the program text +involved. Lout will precede this error message with a file name, +line number, and column number pointing to the Lout symbol +({@Code "@CP"}, {@Code "@Eiffel"} etc.) whose program text caused the +error message, like this: +@ID @Code @Verbatim { +lout file "cpp_tabs" (from "cpp" line 80, from "all" line 45): + 56,23: prg2lout 2,1: program text ended within comment +} +This is an actual message produced when formatting this chapter. The +program text in question has only one line, containing an incomplete comment, +so when @Code "prg2lout" tried to start the second line and found nothing, +it complained as shown. In general, then, you have to add +{@Code "prg2lout"}'s line number to Lout's line number, and use some +initiative, to find the precise point of the problem. +@End @Section diff --git a/doc/user/cpp_lone b/doc/user/cpp_lone index 8d8e367..a377d86 100644 --- a/doc/user/cpp_lone +++ b/doc/user/cpp_lone @@ -1,21 +1,22 @@ @Section - @Title { Stand-alone mode } + @Title { Typesetting computer programs independently of any document } @Tag { alone } @Begin @PP -Printing of C files in stand-alone mode is accomplished by the following -c2lout @Index { @Code "c2lout" filter } -Unix pipeline: -@ID @Code "c2lout options C-files | lout -s > out.ps" -As usual with Lout, the output will be a PostScript file. Each input -file will begin on a new page of the output, starting with its name -in bold type. The options provide control over the final appearance, -as follows: +Printing of program files independently of any document is accomplished by +the following Unix pipeline: +@ID @Code "prg2lout -l language options files | lout -s > out.ps" +where @Code language stands for any one of the programming language +names in the first column of the table above. As usual with Lout, the +output will be a PostScript file. Each input file will begin on a new +page of the output, starting with its name in bold type. The options +provide control over the final appearance, as follows: @WideTaggedList @TI { {@Code-p}{@I style} } { Select a printing style. Your choices are {@Code -pfixed}, -{@Code -pvarying}, and {@Code -psymbol}, with the default being -{@Code -pfixed}. Consult Section {@NumberOf embedded} for examples +{@Code -pvarying}, and {@Code -psymbol}, with the default value +varying with the language as given in the fourth column of the +table above. Consult Section {@NumberOf embedded} for examples of these styles. } @TI { @Code -n } { diff --git a/doc/user/cpp_opti b/doc/user/cpp_opti new file mode 100644 index 0000000..538bda2 --- /dev/null +++ b/doc/user/cpp_opti @@ -0,0 +1,105 @@ +@Section + @Title { Changing the appearance of a program } + @Tag { cpp_opti } +@Begin +@PP +The {@Code "@CP"}, {@Code "@Eiffel"} etc. symbols have a number of +options for changing the appearance of the printed program. These +options are the same for all symbols, although their default values +may vary. The @Code "style" option changes the printing style; its +value may be {@Code "fixed"} (fixed-width font), {@Code "varying"} +(varying-width font), or {@Code "symbol"} (varying-width font with +mathematical symbols used for some operators). Its default value +depends on the language, and may be found in the fourth column of +the table at the start of this chapter. The example in the previous +section was in @Code fixed style; we can switch styles like this: +@ID @OneRow @Code { +"@CP" +" style { varying }" +"{" +"#include <stdio.h>" +"" +"treeprint(p) /* print tree p recursively */" +"struct tnode *p;" +"{" +" if (p != NULL) {" +" treeprint(p->left);" +" printf(\"%4d %s\\n\", p->count, p->word);" +" treeprint(p->right);" +" }" +"}" +"}" +} +The result in this case will be +@ID @OneRow @CP style { varying } +{ +#include <stdio.h> + +treeprint(p) /* print tree p recursively */ +struct tnode *p; +{ + if (p != NULL) { + treeprint(p->left); + printf("%4d %s\n", p->count, p->word); + treeprint(p->right); + } +} +} +If we use @Code "style { symbol }" we get this: +@ID @OneRow @CP style { symbol } +{ +#include <stdio.h> + +treeprint(p) /* print tree p recursively */ +struct tnode *p; +{ + if (p != NULL) { + treeprint(p->left); + printf("%4d %s\n", p->count, p->word); + treeprint(p->right); + } +} +} +with mathematical symbols replacing some of the operators. +@PP +The {@Code "@CP"}, {@Code "@Eiffel"} etc. symbols have additional options +which allow a finer control over the style. Here they all are, with their +default values: +@ID @OneRow @Code { +"@CP [ or @Eiffel, @Blue, etc. ]" +" style { fixed }" +" font { Courier }" +" strings { Base }" +" identifiers { Base }" +" comments { Base }" +" keywords { Base }" +" numbers { Base }" +" operators { Base }" +" size { -1.0p }" +" line { 1.0vx }" +" tabin { 8 }" +" tabout { 8s }" +"{" +" ..." +"}" +} +We are already familiar with {@Code "style"}. After that comes +{@Code "font"}, which determines the font family to use, followed +by six options giving the particular faces within that family in which to +print strings, identifiers, comments, keywords, numbers, and +operators. {@Code "Base"} means the basic face; other commonly available +choices are {@Code "Slope"} and {@Code "Bold"}. These options may all be +set to different faces if desired. The default values shown are correct +for @Code "style { fixed }" only; the other styles have other defaults +(Section {@NumberOf cpsetup}). +@PP +The @Code "size" option is the font size to use, and @Code "line" is the +inter-line spacing. The default values specify that @Code "size" is +to be one point smaller than in the surrounding document; this was done +to compensate for Courier's relatively large appearance compared +to other fonts of the same nominal size. Again, these defaults are +different for different values of {@Code "style"}. +@PP +The @Code "tabin" and @Code "tabout" options are the subject of +Section {@NumberOf tabs}. +@End @Section diff --git a/doc/user/cpp_pipe b/doc/user/cpp_pipe new file mode 100644 index 0000000..afbb87e --- /dev/null +++ b/doc/user/cpp_pipe @@ -0,0 +1,57 @@ +@Section + @Title { Reading and selecting program text from separate files } + @Tag { pipes } +@Begin +@PP +We have said that program text within @Code "@CP { ... }" and the other +symbols is passed directly to @Code prg2lout for analysis. However, +there is an exception. The program text may contain an +@Code "@Include" or @Code "@SysInclude" command, which, as for the +@Code "@Verbatim" symbol (Section {@NumberOf verbatim}), causes Lout +to take the program text from a file: +@ID @Code { +"@Eiffel" +"{" +" @Include { \"/usr/staff/jeff/Eiffel/hash.e\" }" +"}" +} +The included file is not examined for balanced braces or @Code "@End" or +{@Code "@Include"}; it is treated entirely verbatim and passed straight +on to {@Code prg2lout}. There may be several @Code "@Include" commands, +and any amount of program text as well, within @Code "@CP { ... }" and +the rest. +@PP +When including files in this way it often happens that only part of an +actual program file is wanted for display. Rather than placing the +wanted part in a separate file, which is error-prone and tedious when +the program is changing, Unix users can use the @Code "pipe" option +to pipe the entire file through an arbitrary sequence of Unix commands, +which may be used to make the wanted selection before the program text +is passed to {@Code prg2lout}. +@PP +For example, suppose that all your Eiffel routines begin with the +routine name one tab stop from the left margin and end at the first +following @Eiffel { end } indented two tab stops. Then +@ID @Code { +"@Eiffel" +" pipe { \"sed -n /^.insert/,/^..end/p\" }" +"{" +" @Include { \"/usr/staff/jeff/Eiffel/hash.e\" }" +"}" +} +will select just the @Eiffel { insert } routine from the @Code { hash.e } +file. Assuming that your program text has been laid out in a +disciplined manner, every line of the selection will begin with a +tab character that is not wanted in this display, so an even better +pipe is +@ID @Code { +"@Eiffel" +" pipe { \"sed -n /^.insert/,/^..end/p | cut -c2-\" }" +"{" +" @Include { \"/usr/staff/jeff/Eiffel/hash.e\" }" +"}" +} +since it cuts away the unwanted tab characters. Unfortunately, we +can't show the result of this on an actual example, since that would +prevent this manual from being formatted on a non-Unix system. +@End @Section diff --git a/doc/user/cpp_prog b/doc/user/cpp_prog new file mode 100644 index 0000000..a049e3d --- /dev/null +++ b/doc/user/cpp_prog @@ -0,0 +1,35 @@ +@Section + @Title { Embedding program text within program comments } + @Tag { cpp_prog } +@Begin +@PP +The standard reference for the Eiffel language @Cite { $meyer1992eiffel } +specifies that identifiers within comments may or should be enclosed +in ` and ' so that they may be noticed and printed in an italic +font: +@ID lines @Break @F @Verbatim { +@ID @Eiffel { +deposit(amount: REAL) is + -- deposit `amount' dollars +} +} +produces +@ID @Eiffel { +deposit(amount: REAL) is + -- deposit `amount' dollars +} +This has been generalized in Lout: arbitrary text within an +Eiffel comment between ` and ' will be treated as Eiffel text and +printed accordingly. Some other languages may also offer this +feature: see the fifth column of the table at the start of this +chapter. In principle the precise means of getting it could vary +from language to language, but the languages available at the moment +either do not have it at all, or else they use ` and ' like Eiffel. +@PP +On the subject of Eiffel, the Eiffel reference @Cite { $meyer1992eiffel } +has some quite detailed style guidelines, and these have been closely +followed in the implementation of the @Code "@Eiffel" symbol. In +particular, @Code "@Eiffel" prints dots larger than usual when they +denote feature calls, as the example @OneCol @Eiffel { account.deposit(20) } +shows. +@End @Section diff --git a/doc/user/cpp_tabs b/doc/user/cpp_tabs index 1157a51..3a04bfa 100644 --- a/doc/user/cpp_tabs +++ b/doc/user/cpp_tabs @@ -1,28 +1,31 @@ @Section - @Title { Tab characters } + @Title { Dealing with tab characters in programs } @Tag { tabs } @Begin @PP -Tab characters provide a convenient way to indent and align parts of C -tab.c @Index { tab characters in C programs } -programs. With care, this alignment can be preserved in the final +Tab characters provide a convenient way to indent and align parts of +tab.c @Index { tab characters in programs } +computer programs. With care, this alignment can be preserved in the final print even with varying-width fonts. @PP -The distance between two tab stops in the input file is by default taken +The distance between two tab stops in the program text is by default taken to be 8 characters, which is standard for Unix. This can be changed with the @Code "tabin" option. For example, @ID @Code "@CP tabin { 4 }" -informs Lout that tab stops occur every 4 characters in the input file. +informs Lout that tab stops occur every 4 characters in the program +text. All the symbols ({@Code "@CP"}, {@Code "@Eiffel"}, etc.) and +their setup files have this option and the next; but to save repetition +we will stick with C for the rest of this section. @PP -The distance between two tab stops in the output file (on the printed -page) is quite a different thing, and it is determined by the value of -the @Code "tabout" option, which must be a Lout length. For example, +The distance between two tab stops on the printed page is quite a different +thing, and it is determined by the value of the @Code "tabout" option, which +must be a Lout length. For example, @ID @Code "@CP tabout { 0.5i }" requests that tab stops be placed at half-inch intervals. In other -words, a distance of one tab stop in the input will be equivalent to a -distance of half an inch in the output. For example, +words, a distance of one tab stop in the program text will be equivalent to a +distance of half an inch on the printed page. For example, @ID @Code "@CP style { varying } tabout { 3f }" -might produce the following, where tab characters in the input file +might produce the following, where tab characters in the program text have been used for indenting and also to align the comments: @ID @OneRow @CP style { varying } tabout { 3f } { struct tnode { /* the basic node */ @@ -37,7 +40,7 @@ it is the default value of @Code "tabout" for the @Code { varying } and @Code { symbol } styles (Section {@NumberOf cpsetup}). In a 12 point font this is 36 points, or half an inch. @PP -If @Code "tabout" is made too small, there is a danger that the +If @Code "tabout" is too small, there is a danger that the alignment might fail. For example, @ID @Code "@CP style { varying } tabout { 0.2i }" produces @@ -56,7 +59,8 @@ wider than this. This causes @CP { /* } to be shifted further to the right than expected, and the alignment is lost. The only solution is to increase {@Code "tabout"}. @PP -In stand-alone mode there are @Code "-t" and @Code "-T" options -equivalent to @Code "tabin" and @Code "tabout" respectively. For +When typesetting computer program texts independently of any document, +there are @Code "-t" and @Code "-T" options to the @Code "prg2lout" +program equivalent to @Code "tabin" and @Code "tabout" respectively. For example, @Code "-T0.5i" produces a half-inch tab width. @End @Section diff --git a/doc/user/dia b/doc/user/dia index 4029cec..6462c88 100644 --- a/doc/user/dia +++ b/doc/user/dia @@ -6,6 +6,13 @@ This chapter describes how to use the @@Diag symbol diag. @Index { @@Diag } @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 @@ -29,7 +36,7 @@ diag. @Index @Code "@Diag" // @Arrow from { E } to { D } } @@Diag offers nodes and links, arrows, labels, positioning using coordinates, -and tree diagrams. +tree diagrams, and syntax diagrams. @BeginSections @Include { dia_intr } @Include { dia_node } @@ -38,6 +45,7 @@ and tree diagrams. @Include { dia_labe } @Include { dia_posi } @Include { dia_tree } +@Include { dia_synt } @Include { dia_erro } @Include { dia_defi } @Include { dia_geom } diff --git a/doc/user/dia_node b/doc/user/dia_node index b72c6e2..8980978 100644 --- a/doc/user/dia_node +++ b/doc/user/dia_node @@ -79,10 +79,53 @@ document. As the number of nodes increases, it becomes very tedious and error-prone to duplicate options at all the nodes. Giving each option just once, at the @Code "@Diag" symbol or in the setup file, saves time and makes it easy to change all the nodes into squares or any other shape -later on. Any setup file option may be overridden in a diagram by -giving the option to its @Code "@Diag" symbol; any @Code "@Diag" option -or setup file option may be overridden at any node by giving the option -again there. +later on. Any setup file option may be overridden in a diagram by giving +the option to its @Code "@Diag" symbol; any @Code "@Diag" option or setup +file option may be overridden at any node by giving the option again there. +@PP +Sometimes a diagram contains several different node types, each with +its own combination of options (for example, the syntax diagrams of +Section {@NumberOf dia_synt} have three node types). To handle these +cases there are three alternative versions of the @Code "@Node" +symbol, called {@Code "@ANode"}, {@Code "@BNode"}, and +anode.fig @Index { @Code "@ANode" in @Code "@Diag" } +bnode.fig @Index { @Code "@BNode" in @Code "@Diag" } +cnode.fig @Index { @Code "@CNode" in @Code "@Diag" } +{@Code "@CNode"}. These have exactly the same options as +{@Code "@Node"}, but the @I default values of these options +are different, in that they come from @Code "@Diag" options, +or else setup file options, that have an extra letter in front +of their name: @Code { a }, @Code { b }, or @Code { c }. Here is +a small example (see later in this section for the @Code font option): +@ID @OneRow { +@Code @Verbatim { +@Diag + aoutline { box } + afont { Italic } + boutline { curvebox } + bfont { Bold } +{ + @ANode identifier + @DP + @BNode keyword +} +} +||7ct +@Diag + aoutline { box } + afont { Italic } + boutline { curvebox } + bfont { Bold } +{ + @ANode identifier + @DP + @BNode keyword +} +} +Note that when giving an option directly to {@Code "@ANode"}, +{@Code "@BNode"}, and {@Code "@CNode"}, the initial @Code { a }, +@Code { b }, or @Code { c } 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 diff --git a/doc/user/dia_summ b/doc/user/dia_summ index b9dc9e9..4539785 100644 --- a/doc/user/dia_summ +++ b/doc/user/dia_summ @@ -1212,6 +1212,93 @@ The @Code "@HTree" option has a similar @Code "treevindent" option, which may be {@Code "top"}, {@Code ctr}, {@Code foot}, or any length from Section {@NumberOf objects}. @PP +Here are all the syntax diagrams symbols, used within {@Code "@SyntaxDiag"} +usually but also available within {@Code "@Diag"}. To begin with we have +the six starter symbols: +@CD @SyntaxDiag { +@Tbl + aformat { @Cell @Code A | @Cell B | @Cell | @Cell @Code C | + @Cell D | @Cell | @Cell @Code E | @Cell F } +{ +@Rowa + A { "@StartRight ..." } + B { @StartRight @ACell "..." } + C { "@StartUp ..." } + D { @StartUp @ACell "..." } + E { +"@StartRightRight" + "A { ... }" + "B { ... }" +} + F { @StartRightRight A { @ACell A } B { @ACell B } } +@Rowa + A { "@StartLeft ..." } + B { @StartLeft @ACell "..." } + C { "@StartDown ..." } + D { @StartDown @ACell "..." } + E { +"@StartRightDown" + "A { ... }" + "B { ... }" +} + F { @StartRightDown A { @ACell A } B { @ACell B } } +} +} +And here are all the syntax diagram types, shown in all four directions +(right, up, left, and down). @Code "@Sequence" and @Code "@Select" may +have up to twelve options, {@Code "A"} to {@Code "L"}. +@IndentedList + +@LI @SyntaxDiag { @Four code { "@ACell ..." } @ACell "..." } + +@LI @SyntaxDiag { @Four code { "@BCell ..." } @BCell "..." } + +@LI @SyntaxDiag { @Four code { "@CCell ..." } @CCell "..." } + +@LI @SyntaxDiag { @Four code { "@Skip" } @Skip } + +@LI @SyntaxDiag { @Four code { +"@Sequence" + "A { ... }" + "B { ... }" + "C { ... }" +} @Sequence A { @ACell A } B { @ACell B } C { @ACell C } } + +@LI @SyntaxDiag { @Four code { +"@Select" + "A { ... }" + "B { ... }" + "C { ... }" +} @Select A { @ACell A } B { @ACell B } C { @ACell C } } + +@LI @SyntaxDiag { @Four code { "@Optional ..." } @Optional @ACell "..." } + +@LI @SyntaxDiag { @Four code { "@OptionalDiverted ..." } + @OptionalDiverted @ACell "..." } + +@LI @SyntaxDiag { @Four code { "@Diverted ..." } @Diverted @ACell "..." } + +@LI @SyntaxDiag { @Four code { +"@Loop" + "A { ... }" + "B { ... }" +} @Loop A { @ACell A } B { @ACell B } } + +@LI @SyntaxDiag { @Four code { "@Repeat ..." } @Repeat @ACell "..." } + +@LI @SyntaxDiag { @Four code { +"@LoopOpposite" + "A { ... }" + "B { ... }" +} @LoopOpposite A { @ACell A } B { @ACell B } } + +@LI @SyntaxDiag { @Four code { "@RepeatOpposite ..." } + @RepeatOpposite @ACell "..." } + +@LI @SyntaxDiag { @Four code { "@RepeatDiverted ..." } + @RepeatDiverted @ACell "..." } + +@EndList The @Code "@Diag" symbol and to the {@Code "@DiagSetup"} setup file symbol have all of the options of {@Code "@Node"}, {@Code "@Link"}, {@Code "@Tree"}, and {@Code "@HTree"}. They also have the following @@ -1240,8 +1327,16 @@ options: B { 0.5f } C { any length from Section {@NumberOf objects} } @Rowa - A { " treevsep" } - B { 0.5f } + A { " syntaxgap" } + B { 0.35f } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " syntaxbias" } + B { 1.0f } + C { any length from Section {@NumberOf objects} } +@Rowa + A { " syntaxradius" } + B { 0.3f } C { any length from Section {@NumberOf objects} } } @DP diff --git a/doc/user/dia_synt b/doc/user/dia_synt new file mode 100644 index 0000000..6cef550 --- /dev/null +++ b/doc/user/dia_synt @@ -0,0 +1,573 @@ +@Section + @Tag { dia_synt } + @Title { Syntax diagrams } +@Begin +@PP +A variant of the @@Diag symbol, called {@Code "@SyntaxDiag"}, +syntax.diag @Index { @Code "@SyntaxDiag" symbol } +syntax.diagrams @Index { syntax diagrams } +railroad.diagrams @Index { railroad diagrams } +produces syntax diagrams (sometimes called railroad diagrams): +@CD @SyntaxDiag + title { call-chain } +{ + @StartRight @Sequence + A { @Optional @Sequence + A { @BCell "super" } + B { @CCell "!" } + } + B { @Loop + A { @Sequence + A { @ACell identifier } + B { @Optional @Sequence + A { @CCell "(" } + B { @Loop + A { @ACell expression } + B { @CCell "," } + } + C { @CCell ")" } + } + } + B { @CCell "." } + } +} +These are used to define the syntax of computer programming languages, +although they could be put to other uses. We'll explain how to get +syntax diagrams first. At the end of this section is an explanation of +how to change the formats of things, which people who use these diagrams +for other purposes will probably need to do. +@PP +A syntax diagram can be @I { right-moving }, which means it starts +at the left and heads right (like the example above), or it can be +@I { down-moving }, starting at the top and heading downwards. The +@Code "@StartRight" and @Code "@StartDown" symbols are used at the start +of the diagram to say which of these directions is wanted: +@ID @OneRow @Code @Verbatim { +@SyntaxDiag + title { call-chain } +{ + @StartRight ... +} +} +where @Code { ... } stands for the rest of the diagram, as we are about +to describe. For completeness there are also @Code "@StartLeft" and +@Code "@StartUp" symbols, but diagrams never start off in these directions. +@PP +The @Code title option is optional; if given, the effect is as shown +(this option is also available with {@Code "@Diag"}). Subsequent +examples will omit the enclosing {@Code "@SyntaxDiag { ... }"}. +@PP +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 +has to go inside the cell: +@ID @OneRow { +@Code @Verbatim { @StartRight @BCell loop } +|7ct +@SyntaxDiag { +@StartRight @BCell loop +} +} +Lout will insert the appropriate arrows, taking account of which +direction (right, up, left, or down) the diagram is currently +moving. This is true for all the syntax diagram symbols; we +won't mention it again. +@FootNote { +This wonderfully useful effect is achieved by a dirty trick, one +of whose consequences is that if you see an error message +similar to `@Code { replacing unknown "@Case" option 0p by 1p }' +it means you've forgotten the initial @Code "@StartRight" or +whatever. +} +@PP +Occasionally, instead of a cell one wants the horizontal or +vertical line to continue uninterrupted. For this there is +the @Code "@Skip" symbol: +@ID @OneRow { +@Code @Verbatim { @StartDown @Skip } +|7ct +@SyntaxDiag { +@StartDown @Skip +} +} +Some examples of its use in practice appear below. +@PP +There are three main ways to build up larger syntax diagrams out +of smaller ones: @I { sequencing }, @I { selection }, and +@I { looping }. For sequencing there is the @Code "@Sequence" symbol: +@ID @OneRow { +@Code @Verbatim { +@StartRight @Sequence + A { @BCell loop } + B { @ACell statements } + C { @BCell end } +} +||7ct +@SyntaxDiag { +@StartRight @Sequence + A { @BCell loop } + B { @ACell statements } + C { @BCell end } +} +} +This is what the sequence looks like in the other three directions: +@CD @OneRow @SyntaxDiag { +@Tbl + mh { 1f } + mv { 0i } + iv { top } + aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A | + @Cell mr { 0i } @StartDown A } +{ +@Rowa A { +@Sequence + A { @BCell loop } + B { @ACell statements } + C { @BCell end } +} +} } +Whatever the direction, the arrows go from option @Code A to option @Code B +to option @Code C and so on. You can have up to twelve items in the +sequence, in options @Code A to {@Code L}; if more than twelve are needed, +just place another sequence inside any one of these options: where one +syntax diagram is allowed, any syntax diagram is allowed, provided there +is enough space on the page (Lout makes a total mess of any diagram that +is too wide to fit on the page). +@PP +After sequencing comes selection, which is obtained with the +@Code "@Select" symbol: +@ID @OneRow { +@Code @Verbatim { +@StartRight @Select + A { @ACell asst } + B { @ACell call-chain } + C { @Sequence + A { @BCell assert } + B { @ACell condition } + } +} +||7ct +@SyntaxDiag { +@StartRight @Select + A { @ACell asst } + B { @ACell call-chain } + C { @Sequence + A { @BCell assert } + B { @ACell condition } + } +} +} +This example shows right-moving selection of three alternatives, +the third being a sequence of things. Here is the same example +in the other three directions: +@CD @OneRow @SyntaxDiag { +@Tbl + mh { 1f } + mv { 0i } + iv { top } + aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A | + @Cell mr { 0i } @StartDown A } +{ +@Rowa A { +@Select + A { @ACell asst } + B { @ACell call-chain } + C { @Sequence + A { @BCell assert } + B { @ACell condition } + } +} } } +When building up complex diagrams like this, it pays to keep the indenting +perfect in the source document. As with sequences, there can be +up to twelve alternatives, in options from @Code A to {@Code L}. +@PP +To say that something is @I optional is to select either that thing or +nothing: +@ID @OneRow { +@Code @Verbatim { +@StartRight @Select + A { @Skip } + B { @ACell parameters } +} +||7ct +@SyntaxDiag { +@StartRight @Select + A { @Skip } + B { @ACell parameters } +} +} +Since this case is so common, there is an @Code "@Optional" symbol for it: +@ID @OneRow { +@Code @Verbatim { +@StartRight @Optional +@ACell parameters +} +||7ct +@SyntaxDiag { +@StartRight @Optional +@ACell parameters +} +} +@Code "@Optional" is exactly like @Code "@Select" with option @Code A +set to @Code "@Skip" and option @Code B set to the syntax diagram +following the @Code "@Optional" symbol. Here is the same example in +the other three directions: +@CD @OneRow @SyntaxDiag { +@Tbl + mh { 1f } + mv { 0i } + iv { top } + aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A | + @Cell mr { 0i } @StartDown A } +{ +@Rowa A { +@Optional @ACell parameters +} } } +There is another kind of `optional' layout, {@Code "@OptionalDiverted"}: +@ID @OneRow { +@Code @Verbatim { +@StartDown @OptionalDiverted +@Sequence + A { @BCell creation } + B { @ACell parameters } +} +||7ct +@SyntaxDiag { +@StartDown @OptionalDiverted @Sequence + A { @BCell creation } + B { @ACell parameters } +} +} +Here is the same example in the other three directions: +@CD @OneRow @SyntaxDiag { +@Tbl + mh { 1f } + mv { 0i } + iv { top } + aformat { @Cell ml { 0i } @StartRight A | @Cell @StartUp A | + @Cell mr { 0i } @StartLeft A } +{ +@Rowa A { +@OptionalDiverted @Sequence + A { @BCell creation } + B { @ACell parameters } +} } } +The optional material goes in a direction perpendicular to what +it would have otherwise: right-moving if previously up or down, and +down-moving if previously left or right. +@PP +Another, related symbol is {@Code "@Diverted"}; it is similar to +@Code "@OptionalDiverted" but without the path which produces nothing: +@ID @OneRow { +@Code @Verbatim { +@StartDown @Diverted @Sequence + A { @BCell creation } + B { @ACell parameters } +} +||7ct +@SyntaxDiag { +@StartDown @Diverted @Sequence + A { @BCell creation } + B { @ACell parameters } +} +} +Here is the same example in the other three directions: +@CD @OneRow @SyntaxDiag { +@Tbl + mh { 1f } + mv { 0i } + iv { top } + aformat { @Cell ml { 0i } @StartRight A | @Cell @StartUp A | + @Cell mr { 0i } @StartLeft A } +{ +@Rowa A { +@Diverted @Sequence + A { @BCell creation } + B { @ACell parameters } +} } } +This symbol is a great aid to packing a big syntax diagram into a +compact shape. +@PP +That covers sequencing and selection; now for looping. The @Code "@Loop" +symbol produces a loop, with option @Code A going forwards and option +@Code B centred and going backwards: +@ID @OneRow { +@Code @Verbatim { +@StartRight @Loop + A { @Sequence + A { @ACell identifier } + B { @CCell : } + C { @ACell type } + } + B { @CCell , } +} +||7ct +@SyntaxDiag { +@StartRight @Loop + A { @Sequence + A { @ACell identifier } + B { @CCell : } + C { @ACell type } + } + B { @CCell , } +} +} +Here is the same example in the other three directions: +@CD @OneRow @SyntaxDiag { +@Tbl + mh { 1f } + mv { 0i } + iv { top } + aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A | + @Cell mr { 0i } @StartDown A } +{ +@Rowa A { +@Loop + A { @Sequence + A { @ACell identifier } + B { @CCell : } + C { @ACell type } + } + B { @CCell , } +} } } +One common case of looping is to have nothing on the way back. We could +get this by placing @Code "@Skip" in option {@Code B} of {@Code "@Loop"}, +but there is an even easier way, the {@Code "@Repeat"} symbol: +@ID @OneRow { +@Code @Verbatim { +@StartRight @Repeat +@ACell statement +} +||7ct +@SyntaxDiag { +@StartRight @Repeat +@ACell statement +} +} +Here is the same example in the other three directions: +@CD @OneRow @SyntaxDiag { +@Tbl + mh { 1f } + mv { 0i } + iv { top } + aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A | + @Cell mr { 0i } @StartDown A } +{ +@Rowa A { +@Repeat +@ACell statement +} } } +Occasionally it looks better to have the empty returning arrow go on +the opposite side of the forward part; for that, there are +@Code "@LoopOpposite" and @Code "@RepeatOpposite" symbols: +@ID @OneRow { +@Code @Verbatim { +@StartRight @LoopOpposite + A { @Sequence + A { @ACell identifier } + B { @CCell : } + C { @ACell type } + } + B { @CCell , } +} +||7ct +@SyntaxDiag { +@StartRight @LoopOpposite + A { @Sequence + A { @ACell identifier } + B { @CCell : } + C { @ACell type } + } + B { @CCell , } +} +} +Here is the same example in the other three directions: +@CD @OneRow @SyntaxDiag { +@Tbl + mh { 1f } + mv { 0i } + iv { top } + aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A | + @Cell mr { 0i } @StartDown A } +{ +@Rowa A { +@LoopOpposite + A { @Sequence + A { @ACell identifier } + B { @CCell : } + C { @ACell type } + } + B { @CCell , } +} } } +@Code "@RepeatOpposite" is particularly useful around a large +{@Code "@Select"}: +@ID @OneRow { +@Code @Verbatim { +@StartRight @RepeatOpposite +@Select + A { @ACell asst } + B { @ACell call-chain } + C { @BCell return } + D { @Sequence + A { @BCell assert } + B { @ACell condition } + } + E { @ACell conditional } + F { @ACell selection } + G { @ACell loop } +} +||7ct +@SyntaxDiag { +@StartRight @RepeatOpposite +@Select + A { @ACell asst } + B { @ACell call-chain } + C { @BCell return } + D { @Sequence + A { @BCell assert } + B { @ACell condition } + } + E { @ACell conditional } + F { @ACell selection } + G { @ACell loop } +} +} +since it clearly distinguishes the loop from the selection. +@PP +Finally, the @Code "@RepeatDiverted" symbol combines the two ideas +of repetition and diversion: +@ID @OneRow { +@Code @Verbatim { +@StartDown @RepeatDiverted +@ACell statement +} +||7ct +@SyntaxDiag { +@StartDown @RepeatDiverted +@ACell statement +} +} +Here is the same example in the other three directions: +@CD @OneRow @SyntaxDiag { +@Tbl + mh { 1f } + mv { 0i } + iv { top } + aformat { @Cell ml { 0i } @StartRight A | @Cell @StartUp A | + @Cell mr { 0i } @StartLeft A } +{ +@Rowa A { +@RepeatDiverted +@ACell statement +} } } +There is no {@Code "@LoopDiverted"} symbol, for good reason. +@PP +Every syntax diagram, from the simplest to the most complex, has +one arrow going into it, and one coming out. There are no exceptions +to this rule. In most syntax diagrams, these two arrows lie on the +same (invisible) line and point in the same direction, and this is +the direction that we say the diagram is moving. There are two symbols +that produce syntax diagrams that lack this second property. Because +of this lack, these symbols cannot be used at arbitrary places in a +complex diagram; they can only be used instead of the @Code "@StartRight" +or @Code "@StartDown" symbols at the beginning of a diagram. The first +symbol, {@Code "@StartRightDown"}, prints its option @Code A right-moving +and its option @Code B down-moving like this: +@ID @OneRow { +@Code @Verbatim { +@StartRightDown + A { @ACell A } + B { @ACell B } +} +||7ct +@SyntaxDiag { +@StartRightDown + A { @ACell A } + B { @ACell B } +} +} +The second symbol, {@Code "@StartRightRight"}, prints both options +right-moving like this: +@ID @OneRow { +@Code @Verbatim { +@StartRightRight + A { @ACell A } + B { @ACell B } +} +||7ct +@SyntaxDiag { +@StartRightRight + A { @ACell A } + B { @ACell B } +} +} +As usual, the options to these symbols may contain arbitrarily complex +syntax diagrams. +@PP +Finally, a few words about changing things. The @Code "@SyntaxDiag" +symbol used the {@Code "@ANode"}, {@Code "@BNode"}, and {@Code "@CNode"} +symbols of @@Diag to construct its three types of cells. In fact, the +@Code "@SyntaxDiag" symbol is nothing more than this: +@ID @OneRow @Code @Verbatim { +@Diag + avalign { mark } + avstrut { yes } + amargin { 0.2f } + aoutline { box } + afont { Italic } + bvalign { mark } + bvstrut { yes } + bmargin { 0.2f } + boutline { curvebox } + bfont { Bold } + cvalign { mark } + cvstrut { yes } + cmargin { 0.2f } + coutline { circle } + chsize { 1f } + arrowlength { 0.4f } +} +So any of the other @Code "@Diag" options can be used freely with +{@Code "@SyntaxDiag"}; and the format of the three cell types can be +changed by using @Code "@Diag" instead of {@Code "@SyntaxDiag"}, and +choosing new values for these (and other) options. +@PP +If there are more than three cell types, it is necessary to fall back +on the {@Code "@XCell"} symbol, which produces a cell without nominating +any particular cell type. After @Code "@XCell" there must be a regular +@Code "@Diag" node, like this: +@ID @OneRow { +@Code @Verbatim { +@StartRight @XCell @Ellipse INIT +} +|7ct +@SyntaxDiag { +@StartRight @XCell @Ellipse INIT +} +} +This way there is no limit to the number of different kinds of cells. Also, +since (for example) @Code "@ACell" is merely an abbreviation for +@ID @OneRow @Code @Verbatim { @XCell @ANode } +any node options may follow {@Code "@ACell"}, {@Code "@BCell"}, and +{@Code "@CCell"}. The appearance of the arrows can be changed in the usual +way, by setting options as has been done above for {@Code "arrowlength"}. +@PP +There are three options specifically related to syntax diagrams: +@ID @OneRow @Code @Verbatim { +@SyntaxDiag + syntaxgap { 0.35f } + syntaxbias { 1.0f } + syntaxradius { 0.3f } +} +The @Code syntaxgap option determines the spacing between the various +elements; changing it causes the syntax diagrams to be set tighter or +looser in a consistent way. The default value shown is 0.35 times the +current font size. The @Code syntaxbias and @Code syntaxradius +options affect the appearance of curved lines, as in @Code "@RVLCurve" +and its relatives. These options are also available with {@Code "@Diag"}, +and in the setup file. Note however that these options cannot be given to +individual elements in a syntax diagram, only to the diagram as a whole. +@End @Section diff --git a/doc/user/equ_summ b/doc/user/equ_summ index bcfbeb3..b1e6fbc 100644 --- a/doc/user/equ_summ +++ b/doc/user/equ_summ @@ -37,6 +37,9 @@ and full names. The auxiliary symbols are: @Rowa A { @Code "big x" } B { Make @Code x larger } +@Rowa + A { @Code "small x" } + B { Make @Code x smaller } } Here are all the parameterized symbols, shown in groups of equal precedence, with the precedence itself at right: @@ -262,6 +265,7 @@ ragged @Break { "propto" @Dbl @Eq { propto } "models" @Dbl @Eq { models } "doteq" @Dbl @Eq { doteq } +"trieq" @Dbl @Eq { trieq } "perp" @Dbl @Eq { perp } "notsub" @Dbl @Eq { notsub } "notin" @Dbl @Eq { notin } @@ -504,6 +508,7 @@ ragged @Break { "exists" @Dbl @Eq { exists } "neg" @Dbl @Eq { neg } "circle" @Dbl @Eq { circle } +"filledcircle" @Dbl @Eq { filledcircle } "square" @Dbl @Eq { square } "ldots" @Dbl @Eq { ldots } "cdots" @Dbl @Eq { cdots } diff --git a/doc/user/johnson b/doc/user/johnson new file mode 100644 index 0000000..aaedd4c --- /dev/null +++ b/doc/user/johnson @@ -0,0 +1,19 @@ +@SysInclude { fig } +@SysInclude { diag } +@SysInclude { eq } +@SysInclude { tbl } +@SysInclude { doc } +@Doc @Text @Begin +@QD @Tbl + rule { yes } +{ +@Row format { @StartVSpan @Cell A | @StartHSpan @Cell B | @HSpan } + A { @SomeText } + B { @SomeText } +@Row format { @VSpan | @Cell B | @StartVSpan @Cell C } + B { @SomeText } + C { @SomeText } +@Row format { @StartHSpan @Cell A | @HSpan | @VSpan } + A { @SomeText } +} +@End @Text diff --git a/doc/user/johnson.out b/doc/user/johnson.out new file mode 100644 index 0000000..ead54ef --- /dev/null +++ b/doc/user/johnson.out @@ -0,0 +1,66 @@ + + + + + + + ................................................... + . . . + . Johnson . Johnson suddenly uttered, in . + . suddenly . a strong determined tone, an . + . uttered, . apophegm, at which many will . + . in a strong . start: `Patriotism is the . + . determined . last refuge of a scoundrel.' . + . tone, an . . + . apophegm, at . . + . which many .................................. + . will start: . . . + . `Patriotism . Johnson . Johnson . + . is the last . suddenly . suddenly . + . refuge of a . uttered, . uttered, . + . scoundrel.' . in a strong . in a strong . + . . determined . determined . + . . tone, an . tone, an . + . . apophegm, at . apophegm, at . + . . which many . which many . + . . will start: . will start: . + . . `Patriotism . `Patriotism . + . . is the last . is the last . + . . refuge of a . refuge of a . + . . scoundrel.' . scoundrel.' . + . . . . + . . . . + .................................. . + . . . + . Johnson suddenly uttered, in . . + . a strong determined tone, an . . + . apophegm, at which many will . . + . start: `Patriotism is the . . + . last refuge of a scoundrel.' . . + . . . + . . . + ................................................... + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/user/mydefs b/doc/user/mydefs index 2ef9639..727bb27 100644 --- a/doc/user/mydefs +++ b/doc/user/mydefs @@ -39,6 +39,7 @@ def @@OneCol { @Code "@OneCol" } def @@OneRow { @Code "@OneRow" } def @@Open { @Code "@Open" } + def @@Outline { @Code "@Outline" } def @@PAdjust { @Code "@PAdjust" } def @@PrependGraphic { @Code "@PrependGraphic" } def @@Rotate { @Code "@Rotate" } @@ -189,7 +190,7 @@ which many will start: `Patriotism is the last refuge of a scoundrel.' def @AmberLight { @OneRow @Tbl - aformat { @Cell A } + aformat { @Cell indentvertical { align } A } marginhorizontal { 0i } marginvertical { 0i } strut { no } @@ -201,3 +202,13 @@ which many will start: `Patriotism is the last refuge of a scoundrel.' @Rowa A { @OpenCircle } } } + + import @DiagSetup @Diag + def @Four named code { } right x + { + 3.8c @Wide @Code code ||0.3c + 2.7c @Wide @StartRight x ||0.3c + 2.7c @Wide @StartUp x ||0.3c + 2.7c @Wide @StartLeft x ||0.3c + 2.2c @Wide @StartDown x + } diff --git a/doc/user/preface b/doc/user/preface index eada554..9b3e964 100644 --- a/doc/user/preface +++ b/doc/user/preface @@ -16,9 +16,9 @@ with the software. Lout is distributed free of charge under the GNU Public License. The gnu. @Index { GNU Public License } primary source is directory -@ID @Code "ftp://ftp.cs.su.oz.au/jeff/lout" +@ID @Code "ftp://ftp.cs.usyd.edu.au/jeff/lout" in which may be found a gzipped tar file containing the main distribution -(currently {@Code "lout-3.17.tar.gz"}), and various other things including +(currently {@Code "lout-3.18.tar.gz"}), and various other things including a PostScript version of this guide. The distribution contains source code, libraries, documentation, license, and installation instructions. @PP diff --git a/doc/user/tbl b/doc/user/tbl index 230c69e..5ed15e1 100644 --- a/doc/user/tbl +++ b/doc/user/tbl @@ -27,6 +27,13 @@ matrix atleft { ( } atright { ) } { n above k } a sup k b sup n-k } As the example shows, the tables may contain spanning columns, aligned columns, and rules, and the cells may contain arbitrary objects. +@FootNote { +There has been a slight change to {@Code "@Tbl"}, starting with Version +3.18: if you want columns whose entries are aligned (on decimal points, +equals signs, etc.), or the analogous thing with rows, you have to ask +for it now, whereas before it happened automatically. See +Section {@NumberOf tbl_alig} for the details. +} @BeginSections @Include { tbl_intr } # introduction diff --git a/doc/user/tbl_alig b/doc/user/tbl_alig index 24b6864..0032e86 100644 --- a/doc/user/tbl_alig +++ b/doc/user/tbl_alig @@ -7,19 +7,21 @@ Columns of numbers are often presented with decimal points aligned: aligned.columns @Index { aligned columns in tables } @CD @OneRow @Tbl marginvertical { 0.5vx } - aformat { @Cell A } + aformat { @Cell indent { align } A } { @Rowa A { 5^.46 } marginabove { 0i } @Rowa A { 3^.4159 } @Rowa A { 5772^ } marginbelow { 0i } } -You can produce this by placing a @Code "^" symbol, which is used -generally throughout Lout for alignment, just before the alignment point in +To produce this you need two steps. First, indicate that you want +an aligned column, using @Code "indent { align }" on the relevant +cell; and second, place a @Code "^" symbol, which is used generally +throughout Lout for alignment, just before the alignment point in each entry: @ID @OneRow @Code @Verbatim { @Tbl marginvertical { 0.5vx } - aformat { @Cell A } + aformat { @Cell indent { align } A } { @Rowa A { 5^.46 } @Rowa A { 3^.4159 } @@ -27,12 +29,17 @@ each entry: } } The equals signs of equations can be aligned in the same way (see the -example at the start of this chapter). Aligned cells should have no -@Code indent option. +example at the start of this chapter). @PP -Owing to problems behind the scenes, getting a heading over the top -of an aligned column is a problem with no ideal solution. What most -people want is for the heading to be centred in the column, and the +Owing to problems behind the scenes, in a column in which one cell is +labelled {@Code "indent { align }"}, all the other cells have to be +so labelled, otherwise Lout make a mess of things. This is a problem +when we want to get a heading over the top of an aligned column: if +we follow the rule, the @I heading gets aligned, which is wrong; but +if we don't, Lout makes a mess of things. There is no ideal solution +to this problem. +@PP +What most people want is for the heading to be centred in the column, and the aligned entries to be centred in the column as a block, but Lout cannot do this. One approximation is to make the heading cell a spanning cell with centring, like this: @@ -51,14 +58,14 @@ an empty second column. } @Rowb A { 5772^ } } } -The spanning frees the heading from alignment, permitting -@Code "indent { ctr }" to work: +The spanning quarantines the centred cell from the aligned cells, +permitting @Code "indent { ctr }" to work: @CD @OneRow @Tbl marginvertical { 0.5vx } aformat { @StartHSpan @Cell indent { ctr } @B A | } bformat { @Cell A | } { -@Rowa A { Heading } marginabove { 0i } +@Rowa A { V } marginabove { 0i } @Rowb A { 5^.46 } @Rowb A { 3^.4159 } @Rowb A { 5772^ } marginbelow { 0i } diff --git a/doc/user/tbl_inde b/doc/user/tbl_inde index 75a3471..22f89cc 100644 --- a/doc/user/tbl_inde +++ b/doc/user/tbl_inde @@ -10,19 +10,18 @@ horizontally. For example, horizontally centres the entry within the cell. The other possible values centred.entries @Index { centred entries in tables } right.justified.entries @Index { right justified entries in tables } -of this option are {@Code "left"}, {@Code "right"}, or any length (for +of this option are {@Code "left"} (the default value), {@Code "right"}, +{@Code "align"} (Section {@NumberOf tbl_alig}), or any length (for example, {@Code 2f}) meaning that much indent. @PP There is a corresponding @Code "indentvertical" option for vertical indenting within the cell. It takes the same values except that @Code "left" is -renamed {@Code "top"}, and @Code "right" is renamed {@Code foot}. -A common problem with vertical placement is that words that lack -ascenders (parts of letters that rise up) or descenders (parts that -sink down) can easily become misaligned with words that -don't. Looking at +renamed {@Code "top"}, @Code "right" is renamed {@Code foot}. A common +problem with vertical placement is that words that lack ascenders (parts +of letters that rise up) or descenders (parts that sink down) can easily +become misaligned with words that don't. Looking at @CD @Tbl aformat { @Cell A | @Cell B | @Cell C } - marginvertical { 0i } { @Rowa A { resume } diff --git a/doc/user/tbl_mark b/doc/user/tbl_mark index 8761979..fcd4768 100644 --- a/doc/user/tbl_mark +++ b/doc/user/tbl_mark @@ -44,7 +44,7 @@ import @TblSetup def @AmberLight { @OneRow @Tbl - aformat { @Cell A } + aformat { @Cell indentvertical { align } A } margin { 0i } strut { no } paint { no } rule { no } diff --git a/doc/user/tbl_plai b/doc/user/tbl_plai index 0813717..d887b86 100644 --- a/doc/user/tbl_plai +++ b/doc/user/tbl_plai @@ -7,35 +7,40 @@ Tables work well with plain text output (Section {@NumberOf plain}): plain.text.tables @Index { plain text tables } @CD @OneRow -1px @Break @F @Verbatim { ................................................... -. . . -. Johnson . Johnson suddenly uttered an . -. suddenly . apophegm, at which many will . -. uttered an . start: `Patriotism is the . -. apophegm, at . last refuge of a scoundrel.' . -. which many . . -. will start: . . -. `Patriotism ................................. -. is the last . . . -. refuge of a . Johnson . Johnson . -. scoundrel.' . suddenly . suddenly . -. . uttered an . uttered an . -. . apophegm, at . apophegm, at . -. . which many . which many . -. . will start: . will start: . -. . `Patriotism . `Patriotism . -. . is the last . is the last . -. . refuge of a . refuge of a . -. . scoundrel.' . scoundrel.' . -. . . . -. . . . -................................... . -. . . -. Johnson suddenly uttered an . . -. apophegm, at which many will . . -. start: `Patriotism is the . . -. last refuge of a scoundrel.' . . -. . . -. . . +. . . +. Johnson . Johnson suddenly uttered, in . +. suddenly . a strong determined tone, an . +. uttered, . apophegm, at which many will . +. in a strong . start: `Patriotism is the . +. determined . last refuge of a scoundrel.' . +. tone, an . . +. apophegm, at . . +. which many .................................. +. will start: . . . +. `Patriotism . Johnson . Johnson . +. is the last . suddenly . suddenly . +. refuge of a . uttered, . uttered, . +. scoundrel.' . in a strong . in a strong . +. . determined . determined . +. . tone, an . tone, an . +. . apophegm, at . apophegm, at . +. . which many . which many . +. . will start: . will start: . +. . `Patriotism . `Patriotism . +. . is the last . is the last . +. . refuge of a . refuge of a . +. . scoundrel.' . scoundrel.' . +. . . . +. . . . +.................................. . +. . . +. Johnson suddenly uttered, in . . +. a strong determined tone, an . . +. apophegm, at which many will . . +. start: `Patriotism is the . . +. last refuge of a scoundrel.' . . +. . . +. . . ................................................... } This table was produced by a separate run of Lout and pasted into this diff --git a/doc/user/tbl_span b/doc/user/tbl_span index 5621961..ec568dc 100644 --- a/doc/user/tbl_span +++ b/doc/user/tbl_span @@ -134,12 +134,12 @@ The names given to the entries ({@Code "A"}, {@Code "B"}, {@Code "C"}, etc.) are quite irrelevant: having a @Code "@Cell D" in one row and a @Code "@Cell D" in another does not mean that the cells will appear in the same column. -@PP -There is an asymmetry in the spiral above: the first column -occupies slightly more space than the other two. This arises -because the left margin of the leftmost column is excluded from the -calculation of how much space is available. This anomaly might be -corrected some day. +# @PP +# There is an asymmetry in the spiral above: the first column +# occupies slightly more space than the other two. This arises +# because the left margin of the leftmost column is excluded from the +# calculation of how much space is available. This anomaly might be +# corrected some day. @PP There is a @Code "@StartHVSpan" symbol which combines the effects of @Code "@StartHSpan" and {@Code "@StartVSpan"}. You need to diff --git a/doc/user/tbl_summ b/doc/user/tbl_summ index 6fed734..53f957e 100644 --- a/doc/user/tbl_summ +++ b/doc/user/tbl_summ @@ -58,10 +58,12 @@ plain text } D { any length e.g. @Code 3c } @Rowa A { indent i } - D { {@Code left}, {@Code ctr}, {@Code mctr}, {@Code right}, or any length } + B { @Code left } + D { {@Code left}, {@Code ctr}, {@Code align}, {@Code mctr}, {@Code right}, or any length } @Rowa A { indentvertical iv } - D { {@Code top}, {@Code ctr}, {@Code mctr}, {@Code foot}, or any length } + B { @Code top } + D { {@Code top}, {@Code ctr}, {@Code align}, {@Code mctr}, {@Code foot}, or any length } @Rowa A { strut s } B { yes } diff --git a/doc/user/vcpp b/doc/user/vcpp new file mode 100644 index 0000000..b7c18ca --- /dev/null +++ b/doc/user/vcpp @@ -0,0 +1 @@ +vi cpp cpp_lone cpp_embe cpp_opti cpp_chan cpp_tabs cpp_comm cpp_prog cpp_pipe cpp_erro |