aboutsummaryrefslogtreecommitdiffstats
path: root/doc/expert/det_lexi
diff options
context:
space:
mode:
authorJeffrey H. Kingston <jeff@it.usyd.edu.au>2010-09-14 19:21:41 +0000
committerJeffrey H. Kingston <jeff@it.usyd.edu.au>2010-09-14 19:21:41 +0000
commit71bdb35d52747e6d7d9f55df4524d57c2966be94 (patch)
tree480ee5eefccc40d5f3331cc52d66f722fd19bfb9 /doc/expert/det_lexi
parentb41263ea7578fa9742486135c762803b52794105 (diff)
downloadlout-71bdb35d52747e6d7d9f55df4524d57c2966be94.tar.gz
Lout 3.17.
git-svn-id: http://svn.savannah.nongnu.org/svn/lout/trunk@2 9365b830-b601-4143-9ba8-b4a8e2c3339c
Diffstat (limited to 'doc/expert/det_lexi')
-rw-r--r--doc/expert/det_lexi253
1 files changed, 253 insertions, 0 deletions
diff --git a/doc/expert/det_lexi b/doc/expert/det_lexi
new file mode 100644
index 0000000..e0ad9f1
--- /dev/null
+++ b/doc/expert/det_lexi
@@ -0,0 +1,253 @@
+@Section
+ @Tag { lexical }
+ @Title { Lexical structure (words, spaces, symbols) and macros }
+@Begin
+@PP
+The input to Lout consists of a sequence of @I {textual units},
+textual.unit @Index {Textual unit }
+which may be
+either {@I{white spaces}},
+@I identifiers,
+@I delimiters,
+or
+@I {literal words}. Each
+is a sequence of @I characters chosen from:
+letter @Index { Letter character }
+other @Index { Other character }
+quote @Index { Quote character }
+escape @Index { Escape character }
+comment.char @Index { Comment character }
+underscore.char @Index { Underscore character }
+@ID @Tab
+ vmargin { 0.5vx }
+ @Fmta { @Col A ! @Col B }
+{
+@Rowa A { letter } B { @Code "@ab-zAB-Z_" }
+@Rowa A { white space } B { @I { space formfeed tab newline } }
+@Rowa A { quote } B { @Code "\"" }
+@Rowa A { escape } B { @Code "\\" }
+@Rowa A { comment } B { @Code "#" }
+@Rowa A { other } B { @Code "!$%&'()*+,-./0123456789:;<=>?[]^`{|}~" }
+}
+Notice that @Code "@" and @Code "_" are classed as letters. Basser
+Lout accepts the accented letters of the ISO-LATIN-1 character set
+(depending on how it is installed), and these are also classed as
+letters. The ten digits are classed as `other' characters, and in
+fact the `other' class contains all 8-bit characters (except octal 0)
+not assigned to previous classes.
+@PP
+A @I {white space} is a sequence of one or more white space characters.
+white.space @Index { White space }
+formfeed @Index { Formfeed }
+space.f @Index { Space }
+ Lout treats the formfeed character exactly like the space character;
+it is useful for getting page breaks when printing Lout source code.
+@PP
+A @I delimiter is a sequence of one or more `other' characters which
+delimiter @Index { Delimiter }
+is the name of a symbol. For example, @Code "{" and @Code "//" are
+delimiters. When defining a delimiter, the name must be enclosed
+in quotes:
+@ID @Code {
+"def \"^\" { {} ^& {} }"
+}
+but quotes are not used when the delimiter is invoked. A delimiter may
+have delimiters and any other characters adjacent, whereas identifiers
+may not be adjacent to letters or other identifiers. The complete list
+of predefined delimiters is
+@ID @OneRow @Code {
+{
+ "/"
+ @JL "//"
+ @JL "^/"
+ @JL "^//"
+} |2.2cx {
+ "|"
+ @JL "||"
+ @JL "^|"
+ @JL "^||"
+} |2.2cx {
+ "&"
+ @JL "^&"
+} |2.2cx {
+ "&&"
+ @JL "{"
+ @JL "}"
+}
+}
+A longer delimiter like @Code "<=" will be recognised in
+preference to a shorter one like {@Code "<"}.
+@PP
+An @I identifier is a sequence of one or more letters which is the name of a
+identifier @Index { Identifier }
+symbol. It is conventional but not essential to begin identifiers with
+{@Code "@"}; Basser Lout will print a warning message if it finds an
+unquoted literal word (see below) beginning with {@Code "@"}, since such
+words are usually misspelt identifiers. The ten digits are not letters
+and may not appear in identifiers; and although the underscore character
+is a letter and may be used in identifiers, it is not conventional to
+do so. The complete list of predefined identifiers is
+@ID @OneRow @Code {
+{ "@BackEnd"
+ @JL "@Background"
+ @JL "@Begin"
+ @JL "@Break"
+ @JL "@Case"
+ @JL "@Common"
+ @JL "@Char"
+ @JL "@CurrFace"
+ @JL "@CurrFamily"
+ @JL "@CurrLang"
+ @JL "@Database"
+ @JL "@End"
+ @JL "@Enclose"
+ @JL "@Filter"
+ @JL "@FilterErr"
+ @JL "@FilterIn"
+ @JL "@FilterOut"
+ @JL "@Font"
+ @JL "@ForceGalley"
+ @JL "@Galley"
+ @JL "@Graphic"
+ @JL "@HAdjust"
+ @JL "@HContract"
+ @JL "@HCover"
+ @JL "@HExpand"
+ @JL "@High"
+ @JL "@HLimited"
+ @JL "@HScale"
+ @JL "@HShift"
+ @JL "@HSpan"
+} |4.4cx {
+ "@Include"
+ @JL "@IncludeGraphic"
+ @JL "@Insert"
+ @JL "@KernShrink"
+ @JL "@Key"
+ @JL "@Language"
+ @JL "@LClos"
+ @JL "@LEnv"
+ @JL "@LInput"
+ @JL "@LVis"
+ @JL "@LUse"
+ @JL "@Meld"
+ @JL "@Merge"
+ @JL "@Minus"
+ @JL "@Moment"
+ @JL "@Next"
+ @JL "@NotRevealed"
+ @JL "@Null"
+ @JL "@OneCol"
+ @JL "@OneOf"
+ @JL "@OneRow"
+ @JL "@Open"
+ @JL "@Optimize"
+ @JL "@PAdjust"
+ @JL "@PageLabel"
+ @JL "@PlainGraphic"
+ @JL "@Plus"
+ @JL "@PrependGraphic"
+ @JL "@RawVerbatim"
+ @JL "@Rotate"
+} |4.4cx {
+ "@Rump"
+ @JL "@Scale"
+ @JL "@SetColor"
+ @JL "@SetColour"
+ @JL "@Space"
+ @JL "@StartHSpan"
+ @JL "@StartHVSpan"
+ @JL "@StartVSpan"
+ @JL "@SysDatabase"
+ @JL "@SysInclude"
+ @JL "@SysIncludeGraphic"
+ @JL "@SysPrependGraphic"
+ @JL "@Tag"
+ @JL "@Tagged"
+ @JL "@Target"
+ @JL "@Underline"
+ @JL "@Use"
+ @JL "@VAdjust"
+ @JL "@VContract"
+ @JL "@VCover"
+ @JL "@Verbatim"
+ @JL "@VExpand"
+ @JL "@VLimited"
+ @JL "@VScale"
+ @JL "@VShift"
+ @JL "@VSpan"
+ @JL "@Wide"
+ @JL "@Yield"
+ @JL "@YUnit"
+ @JL "@ZUnit"
+}
+}
+plus the names of the parameters of @@Moment. The symbols @@LClos, @@LEnv,
+lclos @Index { @@LClos symbol }
+lenv @Index { @@LEnv symbol }
+linput @Index { @@LInput symbol }
+lvis @Index { @@LVis symbol }
+luse @Index { @@LUse symbol }
+@@LInput, @@LVis and @@LUse appear in cross reference databases generated
+by Lout and are not for use elsewhere.
+@PP
+A sequence of characters which is neither a white space, an identifier, nor a
+delimiter, is by default a @I {literal word}, which means that it will
+word @Index { Word }
+literal.word @Index { Literal word }
+quoted.word @Index { Quoted word }
+pass through Lout unchanged. An arbitrary sequence of characters
+enclosed in double quotes, for example @Code "\"{ }\"", is also a
+literal word. Space characters may be included, but not tabs or
+newlines. There are special character sequences, used only between
+quotes, for obtaining otherwise inaccessible characters:
+@ID @Tab
+ vmargin { 0.5vx }
+ @Fmta { @Col A ! @Col B }
+{
+@Rowa A { @Code "\\\"" } B { produces @Code "\"" }
+@Rowa A { @Code "\\\\" } B { "\\" }
+@Rowa A { @Code "\\ddd" } B { the character whose ASCII code is }
+@Rowa A { } B { the up to three digit octal number {@Code ddd} }
+}
+So, for example, @Code "\"\\\"@PP\\\"\"" produces {@Code "\"@PP\""}.
+@PP
+When the comment character
+comment @Index { Comment }
+@Code "#" is encountered, everything from
+that point to the end of the line is ignored. This is useful for
+including reminders to oneself, like this:
+@ID @OneRow @Code {
+"# Lout user manual"
+"# J. Kingston, June 1989"
+}
+for temporarily deleting parts of the document, and so on.
+@PP
+@I Macros
+macro @Index { Macro }
+provide a means of defining symbols which stand for a
+sequence of textual units rather than an object. For example, the macro
+definition
+@ID @Code {
+"macro @PP { //1.3vx 2.0f @Wide &0i }"
+}
+makes Lout replace the symbol @Code "@PP" by the given textual units
+before assembling its input into objects. A similar macro to this
+one is used to separate the paragraphs of the present document. The
+enclosing braces and any spaces adjacent to them are dropped, which can
+be a problem: @Code "@PP2i" has result {@Code "//1.3vx 2.0f @Wide &0i2i"}
+which is erroneous.
+@PP
+The meaning of symbols used within the body of a macro is determined by
+where the macro is defined, not by where it is used. Due to implementation
+problems, @@Open symbols will not work within macros. Named and body
+parameters will work if the symbol that they are parameters of is also
+present. There is no way to get a left or right brace into the body of
+a macro without the matching brace.
+@PP
+Macros may be nested within other definitions and exported, but they may
+not be parameters. They may not have parameters or nested definitions
+of their own, and consequently a preceding @Code export clause (Section
+{@NumberOf visibility}) would be pointless; however, an @Code import
+clause is permitted.
+@End @Section