@Section @Title { Setup files } @Tag { setup } @Begin @PP As mentioned briefly in Section {@NumberOf start}, each Lout document begins with an instruction to include (i.e. to read) a @I { setup file }: setup.file @Index { setup file } sysinclude. @Index @Code "@SysInclude" system.include @Index { system include directory } doc.file @Index { @Code "doc" file } @ID @Code "@SysInclude { doc }" The setup file's name in this example is @Code { doc }, and the @Code Sys in @Code "@SysInclude" means that @Code doc is stored in the @I { Lout system include directory }, which is where all the standard setup files are kept. Each document type (Chapter {@NumberOf types}) has its own setup file. @PP To change the overall format of a document, you need to create your own setup file by copying and modifying one of the standard ones. We will assume that you are making an ordinary document, with the @Code doc setup file, but a similar procedure works for any setup file. @PP You first need to find out the name of the Lout system include directory, by typing @ID @Code "lout -V" in Unix. This causes Lout to print out various facts about itself. Then, supposing that this tells you that the Lout system include directory is @Code { "/usr/lout/include" }, type the Unix command @ID @Code "cp /usr/lout/include/doc mydoc" to place a copy of the @Code doc setup file in your directory, mydoc.file @Index { @Code "mydoc" file } renaming it @Code {mydoc}. Since @Code "doc" is read-only, you may also need to change the mode of @Code mydoc to be writable (by @Code "chmod +w mydoc" in Unix). Now replace @ID @Code "@SysInclude { doc }" at the beginning of your document by @ID @Code "@Include { mydoc }" and Lout will read @Code mydoc as the setup file instead of @Code { doc }. Since the two files are at present identical, this has changed nothing so far; but now any changes you make to @Code mydoc will affect your document. Notice the use of @Code "@Include" rather than @Code { "@SysInclude" }; @Code "@Include" will search your current directory for @Code { mydoc }, whereas @Code "@SysInclude" searches only the system directory. @PP The remainder of this section is a tour through @Code {doc}, explaining the various parts and how to modify them. The first lines that actually do anything are these: @ID @OneRow @Code { "@SysInclude { fontdefs }" "@SysInclude { langdefs }" "@SysInclude { dl }" "@SysInclude { docf }" } We already know that @Code "@SysInclude" causes Lout to read a file from the Lout system include directory. Files @Code fontdefs and @Code langdefs fontdefs.file @Index { @Code "fontdefs" file } langdefs.file @Index { @Code "langdefs" file } tell Lout what fonts and languages there are. File @Code "dl" contains dl.file @Index { @Code "dl" file } the definition of the DocumentLayout package, in which all the symbols of the first four chapters of this guide are defined. File @Code "docf" contains extra definitions specific to docf.file @Index { @Code "docf" file } ordinary documents (as distinct from technical reports, books, or the other document types of Chapter {@NumberOf types}). So this fourth line will be different in the setup files for those other types. @PP Now let's look at the next six lines of {@Code "doc"}: @ID @OneRow @Code { "# @SysInclude { tab }" "# @SysInclude { eq }" "# @SysInclude { fig }" "# @SysInclude { graph }" "# @SysInclude { cprint }" "# @SysInclude { pas }" } These lines, each beginning with {@Code "#"}, are @I { comments }: when Lout encounters a @Code "#" character not enclosed in double quotes, it ignores it and everything following it up to and including the end of that line. So these lines do nothing as they stand, but by deleting one or more @Code "#" characters you can have the @Code "@SysInclude" lines for these files, which contain the definitions of Lout's specialized formatting packages, in your setup file, rather than at the beginning of your document. @PP The next line is @ID @Code { "@Include { mydefs }" } This searches your current directory for a file called @Code { mydefs }, which (as Section {@NumberOf definitions} explains) is intended to hold your own personal set of definitions of new symbols. It does no harm if there is no @Code "mydefs" file in your current directory, because @Code "@Include" then searches the Lout system include directory for it, and there is an empty @Code mydefs file there. When using your own setup file, you might prefer to delete @Code "@Include { mydefs }" and put your definitions in its place, so that you have one file of setup-type material rather than two. @PP Next we come to the main thing: the DocumentLayout @Code "@Use" use. @Index @Code "@Use" clause. It looks like this: @ID @OneRow @Code { "@Use { @DocumentLayout" " # @InitialFont { Times Base 12p }" " # @InitialBreak { adjust 1.20fx hyphen }" " # @InitialLanguage { English }" " # @InitialColour { black }" " # @HeadingFont { Bold }" " # @ParaGap { 1.30vx }" "}" } @Code "@DocumentLayout" is a symbol, and @Code { "@InitialFont" }, document.layout @Index @Code "@DocumentLayout" @Code { "@InitialBreak" }, etc. are its options. There are over one hundred options altogether; the display above just shows the first six. You change the overall format of your document by changing these options. @PP As it stands, the options are all hidden within comments, so the default values (shown within braces) are in force. To change an option, delete the @Code "#" and change the value between braces. For example, to set the document in Helvetica 10 point font, change the @Code { "@InitialFont" } line to @ID @Code "@InitialFont { Helvetica Base 10p }" We won't go through all the options now, since they are the subject of following sections. @PP The standard setup files are all much the same up to this point; the main variation is that in some files, some options are already set. The @Code "slides" setup file, for example, contains @ID @Code "@InitialFont { Times Base 20p }" so that overhead transparencies will have a large font size. However, now comes a second @Code "@Use" clause whose symbol and options depend on the document type. For ordinary documents (i.e. in the @Code "doc" setup file) this clause is @ID @OneRow @Code { "@Use { @OrdinaryLayout" " # @IndexWord { index }" " # @AppendixWord { appendix }" " # @SectionNumbers { Arabic }" " # @SubSectionNumbers { Arabic }" " # @SubSubSectionNumbers { Arabic }" " # @AppendixNumbers { UCAlpha }" " # @SubAppendixNumbers { Arabic }" " # @SubSubAppendixNumbers { Arabic }" " # @SectionHeadingFont { Bold }" "}" } Once again this is just some of the options. In the @Code slides setup file for overhead transparencies, we find this: @ID @OneRow @Code { "@Use { @OverheadLayout" " # @DateLine { No }" " # @ContentsWord { contents }" " # @FirstLectureNumber { 1 }" " # @FirstOverheadNumber { 1 }" " # @LectureNumbers { Arabic }" " # @OverheadNumbers { Arabic }" " # @TitlePageFont { Helvetica Base 1.5f }" " # @LectureHeadingFont { Bold 1.20f }" " # @OverheadHeadingFont { Bold }" " # @LectureInContents { Yes }" " # @OverheadInContents { No }" " # @ReferencesInContents { Yes }" "}" } In general this second @Code "@Use" clause assigns values to options specific to the document type we are using, whereas the first @Code "@Use" clause assigns values to options that are relevant to many or all document types. @PP The setup files used with C and C++ program printing ({@Code "cdoc"}, {@Code "creport"}, etc.) contain a third @Code "@Use" clause, providing options specific to printing C and C++ programs. The setup file ends with a comment identifying the spot where database declarations should database.dec @Index { database declarations, where to put } be put, and one such declaration, for reference printing styles. @End @Section