XEROX LISP USERS' TEMPLATE 2 4 1 LISP USERS' TEMPLATE 1 4 By: Frances Grimble and Carol Mueller (Grimble.PA @ Xerox.ARPA) Updated by: Susana Wessling (Wessling.pa@Xerox) Note: This is a long explanation of how to create documentation in TEdit. If you want a short template form to use, copy koto>EasyTemplate.TEdit. This document provides a template and instructions for formatting the Lisp Users' package documentation. It is available on DocumentationTemplate.TEdit. Using TEdit, HRule, and this document, you should be able to duplicate the looks of the current Lisp Users' manual. You can either copy the template to your directory, strip out the existing text, and insert your own, or you can display or print the template and follow the written specifications for formatting your document. The specifications are given in the order in which you would most likely use them to format a document, with the basic text and margins described first, then the various levels of headings, then special elements such as running heads and page numbers. NB: Because the way TEdit handles line leading near rules has changed, these instructions are correct only for the JCAI and subsequent versions of TEdit. RULES FOR CONTENT Documentation should always include the name of the package, the name of the author (and Xerox, Arpanet, CSNET or other electronic mailing address, when available%otherwise US mail address), the names of all other LispUsers packages required, the names of all files which are part of the package (data files, other Lisp files, etc.), and enough detail to allow someone to effectively use it! BASIC SPECIFICATIONS It is wise to apply the specifications for the body text, headings, functions, and variables while you write the document, while the running head and page numbers may be specified afterwards. Font, Type Size, Leading, and Margins First use the Character Looks menu to put the text in a 10-point Modern font. Then, in the Paragraph Looks menu, set the line leading to 4 points and the paragraph leading to 11 points. (Because 11 points paragraph leading is all you need, you should use only one carriage return between paragraphs when typing in text.) Finally, in the Page Layout menu, set the left margin to seven picas, the right margin to six, and the top and bottom margins to eight. Functions, Variables, and Lisp Code Examples It is usual to first give the name of a function, then describe its purpose and each of its arguments. When the name of a function is first given, it is set off like this: (IMAGEFNSCREATE DISPLAYFN IMAGEBOXFN PUTFN GETFN COPYFN) [Function] The function name is in 10-point regular Modern, all caps. Arguments are in 10-point italic Modern, in all caps, mixed case, or lowercase, as they appear in the system. If the function description is more than one line long, the runover arguments should be indented under the function name and the word [Function] placed on the last line of the argument list, like this: (MAKE-ARRAY INDICESLIST &KEY :ELEMENT-TYPE: INITIAL-ELEMENT :INITIAL-CONTENTS :ADJUSTABLE: FILL-POINTER :DISPLACED-TO :DISPLACED-INDEX-OFFSET) [Function] Long function descriptions should have four points leading between lines. To space them correctly, hold down the meta key when typing the carriage returns so that TEdit breaks the lines without creating separate paragraphs. Parentheses are in 10-point regular Modern type. The type of definition is in 10-point Modern, caps and lowercase, enclosed in square brackets, and flushed right with a right tab set to 38.0. Variables look like functions, except that the word ``Variable,'' enclosed in square brackets, follows the variable name. Examples of code should be in 10-point Terminal font (but not function names, commands, file names, and the like). If 10-point Terminal is not available on your printer, use 8-point Terminal. Code examples should have four points line leading and no paragraph leading. Quotation Marks, Bullets, and Dashes We recommend using TEdit's ``expanded abbreviations'' to produce professional-looking quotation marks, bullets, em-dashes%used to separate text phrases%and en-dashes (used to indicate inclusive numbers, as in ``pages 3$6''). To produce a bullet, type a lowercase b, select it, and type control-X. To produce an em-dash, type a lowercase m, select it, and type control-X. To produce an en-dash, type a lowercase n, select it, and type control-X. HEADS There are four levels of heads in the Lisp Users' documentation: chapter (level 1) heads, level 2, level 3, and level 4 heads. Note: A head that falls at the bottom of a page (a "widow") is undesirable. You eliminate a widow by selecting it, then applying the Before option of the New Page command in the Paragraph Looks menu. The Chapter Head The chapter head appears at the beginning of the document and identifies it. The heading "Lisp Users' Template," above, is a correctly formatted Lisp Users' chapter head, which may be used as a template for the one in your document. Copying a Chapter Head From This Template The easiest way to create a chapter head is to bring up this formatting file in one TEdit window, then bring up the Lisp Users' document to format in another. Copy-select the heading from this file into your document file, then delete the words "Lisp Users' Template." Type in the name of your package and press the carriage return to reposition the one-point rule below the head. Then select the head and apply Centered from the Paragraph Looks menu. Your name and ARPANET address (if you have one) should form a separate paragraph centered below the chapter head. First type them in the form used for this document and select the line. Then, in the Paragraph Looks menu, specify 17 points paragraph leading and Centered. Apply. Typing In and Specifying a Chapter Head You may want to read the following instructions on typing in and specifying a chapter head if the one you copy from this formatting file looks incorrect after you copy it. You will probably want to apply only some of these specifications to solve specific problems, though you can use them to create a head from scratch. A chapter head is composed of four lines, each of which is a separate paragraph (see the head on page 1). The text of the head is at the center, with one-point rules directly above and below it. There is a four-point rule outside each one-point rule. You must load the HRule package to create the rules. 1. To create the first four-point rule, place the caret on the line where you want to begin the head and type control-O. The HRule window will appear, asking for a form to evaluate. Type HRULE.CREATE (4). The window will close, and a four-point rule will be created all the way across your document. To correctly position the rule, set the margins in the Paragraph Looks menu to 11.5 and 26.0. Select Centered, then apply. 2. Before creating the next rule, a one-point rule, place the caret at the end of the four-point rule and press the carriage return. You will note that the caret repositions itself in the center of the document, indicating that this region already has centered paragraph looks. You create the one-point rule in the same way as the four-point rule, except you type (1) instead of (4). This rule is initially correctly postioned, but has too much paragraph leading. To correct this problem, select the rule, set both line and paragraph leading to zero, and apply. Make sure the margins are set at 11.5 and 26.0 and that the Centered command is chosen before you change the leading. 3. Now type in the text of the heading, in capital letters. In the Character Looks menu, set the type size to 12 and the style to bold, then apply. Then, in the Paragraph Looks menu, specify six points paragraph leading and apply, first making sure that the margins are correct and the Centered command is chosen. Press the carriage return. 4. Create the second one-point rule in the same way as the first and press the carriage return. You will have to adjust the paragraph leading, as above. 5. Finally, create the second four-point rule and press the carriage return. The Level 2 Head Level 2 heads identify major sections of a document. The level 2 heads for the Lisp Users' documentation are in 10-point bold Modern, all caps, as in ``Heads,'' above. The Level 3 Head Level 3 heads identify subsections of a document. For the Lisp Users' manual, they are in 10-point bold Modern, caps and lowercase. The heading "Level 3 Head," above, is itself a level 3 head. The Level 4 Head Level 4 heads identify the lowest level of subsection in the Lisp Users' documentation. They are in 10-point regular Modern, caps and lowercase, underlined. "Typing In and Specifying a Chapter Head," above, is a level 4 head. RUNNING HEADS Currently the Lisp Users' manual is printed one-sided, so there is only one kind of running head. It looks like this: XEROX PACKAGE NAME 2 The easiest way to create a running head for your Lisp Users' documentation is to copy-select the above running head into the top of your document file and apply it according to the instructions below. If you have problems doing this, you may find help in the instructions on typing in a running head. Applying a Running Head Until you specify that the paragraph is to be a running head, TEdit sees it as just another piece of text. The following procedure tells how to apply a running head to every page of your document. 1. Using the Paragraph Looks menu, select Page Heading and type a name for your heading, for example, the word ``RunningHead.'' 2. In the Page Layout menu, type the same name as the heading type, then give it an X position of 7 picas and a Y position of 62. 3. In the Paragraph Looks menu, use the mouse to select the entire heading, then apply. A small gray box will appear to the left of the heading. 4. In the Page Layout menu, select the First(&Default) page type, then apply. Typing In a Running Head Use the following procedure to create a running head: 1. At the beginning of the document file, type the word ``XEROX'' using all caps and regular 10-point Modern type. 2. In the Paragraph Looks menu, set the ruler to 38 picas and position a right tab at 38 picas in the white portion of the ruler. 3. Select a right tab type, then apply. 4. Press the tab key to put the cursor at the right tab position, then type the words "Lisp Users' Packages" followed by a carriage return. 5. Press control-O to bring up the HRule window. In the window, type HRULE.CREATE(2) to create a two-point rule below the text. 6. Now select the word "XEROX" and use the Character Looks menu to put it in 24-point type and Logo font. Since Logo font is not one of the regular menu selections, button Other, then type the word "Logo" in the space provided. 7. Select the words "Lisp Users' Packages," then Show to make sure this text is in 10-point regular Modern. 8. Select the entire running head, then use the Paragraph Looks menu to give it zero points line leading and zero points paragraph leading. PAGE NUMBERS Page numbers are specified and applied in the Page Layout menu. First, specify the alignment of the page numbers to be centered, with the X position being 26.5 picas and the Y position 3.5. Then specify the character looks to be 10-point regular Modern. Finally, apply the page numbers to the First(&Default) pages. After you submit your document, the documentation department will figure out what page in the Lisp Users' manual it will begin on and instruct TEdit to print your document accordingly. (LIST ((PAGE NIL (FOLIOINFO (ARABIC) STARTINGPAGE# 1) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM) FORMATINFO (ARABIC)) (174 36 288 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL NIL (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (282 42 72 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL NIL (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (282 42 72 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))))) 1HH(1 1 (8( (8(D PAGEHEADING RUNNINGHEAD.  HELVETICA  HELVETICA MODERN ?1(DEFAULTFONT 1 (GACHA 10) (GACHA 8) (TERMINAL 8)) MODERN MODERN MODERN MODERNMODERN LOGO    HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN A0JR7&.'     0 2 z%yD KLLK)'D3[Pw     HRULE.GETFNMODERN 0U  Q6t)m  # -z