diff options
Diffstat (limited to 'doc/user')
| -rw-r--r-- | doc/user/README | 10 | ||||
| -rw-r--r-- | doc/user/all | 7 | ||||
| -rw-r--r-- | doc/user/ap_qck | 2 | ||||
| -rw-r--r-- | doc/user/bas_lang | 1 | ||||
| -rw-r--r-- | doc/user/bgr | 1 | ||||
| -rw-r--r-- | doc/user/bgr_outl | 16 | ||||
| -rw-r--r-- | doc/user/cpp | 89 | ||||
| -rw-r--r-- | doc/user/cpp_chan | 40 | ||||
| -rw-r--r-- | doc/user/cpp_comm | 31 | ||||
| -rw-r--r-- | doc/user/cpp_eiff | 42 | ||||
| -rw-r--r-- | doc/user/cpp_embe | 144 | ||||
| -rw-r--r-- | doc/user/cpp_erro | 39 | ||||
| -rw-r--r-- | doc/user/cpp_lone | 23 | ||||
| -rw-r--r-- | doc/user/cpp_opti | 105 | ||||
| -rw-r--r-- | doc/user/cpp_pipe | 57 | ||||
| -rw-r--r-- | doc/user/cpp_prog | 35 | ||||
| -rw-r--r-- | doc/user/cpp_tabs | 34 | ||||
| -rw-r--r-- | doc/user/dia | 10 | ||||
| -rw-r--r-- | doc/user/dia_node | 51 | ||||
| -rw-r--r-- | doc/user/dia_summ | 99 | ||||
| -rw-r--r-- | doc/user/dia_synt | 573 | ||||
| -rw-r--r-- | doc/user/equ_summ | 5 | ||||
| -rw-r--r-- | doc/user/johnson | 19 | ||||
| -rw-r--r-- | doc/user/johnson.out | 66 | ||||
| -rw-r--r-- | doc/user/mydefs | 13 | ||||
| -rw-r--r-- | doc/user/preface | 4 | ||||
| -rw-r--r-- | doc/user/tbl | 7 | ||||
| -rw-r--r-- | doc/user/tbl_alig | 31 | ||||
| -rw-r--r-- | doc/user/tbl_inde | 13 | ||||
| -rw-r--r-- | doc/user/tbl_mark | 2 | ||||
| -rw-r--r-- | doc/user/tbl_plai | 63 | ||||
| -rw-r--r-- | doc/user/tbl_span | 12 | ||||
| -rw-r--r-- | doc/user/tbl_summ | 6 | ||||
| -rw-r--r-- | doc/user/vcpp | 1 |
34 files changed, 1357 insertions, 294 deletions
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 |