\begindata{text,538351624} \textdsversion{12} \template{help} \define{global } \chapter{Templates for text documents} \leftindent{ This help document defines templates, describes many of the templates available on Andrew, and explains how to create your own templates. It includes the following sections: \leftindent{What templates are Applying templates to documents Descriptions of some of EZ's templates Changing style definitions Creating a template without styles} \leftindent{Creating a template with styles Setting a template path An example of creating a template Related Tools}\bigger{ }} \section{What templates are }\leftindent{ A template is a set of ready-made formatting information or instructions that you can apply to a text document. Templates can include two main types of information: \leftindent{\bold{Style specifications}, which determine what formatting styles (such as boldface and centering) can be applied to a document, and exactly how they change the appearance of the text to which you apply them. Thus templates help lend a standard appearance to documents by making a style always look the same. \bold{Set text}, which is text that you want to include over and over in many documents. A template saves you time in this case because you only have to type that text once. } EZ makes available to you an extensive set of templates. Most of these include style specifications only, but some also include set text (the template used for creating memos is an example). See the section below on \bold{Descriptions of some of EZ's templates}. You can see a complete list of the available templates by listing the contents of \leftindent{/usr/andrew/lib/tpls } You can also create your own templates and store them in a personal template directory. See the sections below on \bold{Creating your own templates} and \bold{Setting a template path} for details.} \section{Applying templates to documents} \leftindent{There are two ways to apply a template to a text document: \leftindent{You can create the EZ document with a special filename extension. You can apply a template to an existing file.} }\leftindent{ \bold{Using special extensions. } Whenever you create a file with one of a set of special \italic{extensions }, using the command }\leftindent{ \leftindent{\typewriter{ez filename.extension}} EZ automatically gives you the template associated with the extension. This works because Andrew system administrators have created mappings between extensions and templates in the global.ezinit file. Users at Carnegie Mellon can see the list of mappings by looking at \leftindent{/usr/local/lib/global.ezinit } If you use an extension that does not match any of the entries in the global.ezinit file (or no extension at all), your text document will receive the template called \bold{default}. This template provides a wide range of styles, adequate for most purposes. The format of the entries in the global.ezinit file is fairly self-explanatory, but you can see the \italic{\helptopic{initfiles}} help document to learn exactly what they mean. That document also explains how you can create your own .ezinit file with additional mappings between extensions and templates, since not all the available templates have associated extensions by default (nor do any of the templates you make yourself, of course). Note that not all the entries in the global.ezinit concern templates--many refer to \italic{\helptopic{insets}} , which are software packages for editing information in different formats. } \leftindent{\bold{Applying a template to an existing file. } You can change the template applied to an existing text document by choosing \bold{Add Template} from the \italic{File} menu card. Type the name of the template you want at the prompt on the message line and press Enter. Any styles you previously applied will be "redefined" to conform in appearance to the style specifications of the template you have just added. Depending on which template you added, new options may also appear, and some templates reorder menu cards. Note that adding a template in this manner overrides any extension on the filename. Suppose you create a file with no extension (thus giving it the \bold{default }template), add the \bold{help} template, apply some styles (either before or after adding the new template), and then save the file. The next time you edit the file, you will get the \bold{help} template even though the extension indicates the default template, as long as there is at least one styled region in the document. Note also that if the original template in a document includes some styles that are not defined for the template you add using \bold{Add Template}, they will not "disappear" from the menus--they will still be defined and available as under the original template. } \section{Descriptions of some of the available templates } \leftindent{The following list describes the important features of many of the templates available in EZ. You can access many of them by putting the proper extensions on your filenames (because of the mappings in th\formattingnote{\formattingnote{\formattingnote{\formattingnote{\ \formattingnote{e global.ez}}}}}init file), and the others by using the \bold{Add Template} menu option. Remember, too, that you can add more mappings to templates in your own .ezinit file; see the \italic{\helptopic{initfiles}} help document for instructions. }\leftindent{\description{\bold{default } The default template is the regular set of styles for EZ, as described in the \bold{Pop-up Menu Meanings} section of the \italic{ez} help document. You get the default template if your filename extension does not match any in the global.ezinit file (or in your own .ezinit). } \description{\bold{ctext }The ctext template is a component of the ctext inset, a package intended for C program files. It defines styles that put function names in bold, italicize comments and perform indenting. Use the \bold{.c} and\bold{ .h} extensions to get the ctext template. See the \italic{\helptopic{ctext}} help document for more information. } \description{\bold{help} The help template provides set text for the section headings used in Andrew Help system documents. It also redefines and adds a few styles. Use the \bold{.help} and \bold{.overview} extensions to get the help template. } \description{\bold{letter} The letter template provides set text indicating where you might want to place the different parts of a business letter. It also indents the margins slightly compared to regular text, and uses the 10 point AndySans font. Use the \bold{.letter} extension to get the letter template.} \description{\bold{memo} The memo template has set text headings at the top for a CMU inter-office memo. It also adds some styles to the \italic{Font} card (the ones used in making the set text headings). Use the \bold{.memo} extension to get the memo template. } \description{\bold{template} The template template is a blank file which you can use to create your own template. It contains no style specifications of its own, which allows you to import the styles from the existing template that best suits your purposes. Use the \bold{.template} extension to get the template template. See the section below on \bold{Creating your own templates}. \bold{man} The man template includes the troff commands you need to format a UNIX manual page correctly, interspersed with brief instructions on what information to include under each header. The man template is not included in the global.ezinit. To be able to use it, add the following line to your .ezinit (see the \italic{\helptopic{initfiles}} help document for more details about addfiletype entries): \leftindent{\leftindent{addfiletype .man text "template=man"} You can then use the \bold{.man} extension to get the man template. }}} \section{Changing style definitions} \leftindent{ It is possible to change the definitions of existing styles in a particular EZ document by using the \italic{ lookz }inset. For example, you can change the \bold{Bigger} style in a particular document to add 4 points to the prevailing font, rather than the 2 point addition you get with the \bold{default} template. You can also use Lookz to create an entirely new style, or to reorder the items on a menu card. See the \italic{\helptopic{lookz}} help document for instructions. The changes to style definitions that you make with Lookz apply only to that one document. You cannot use it to redefine styles in a template that you want to apply to many documents. To change style definitions in a template, you must use an editor other than EZ on the template file itself, which allows you to see the datastream specifications written out for each style. It is not recommended that the average user attempt to redefine styles in this way, as it is quite easy to disable the entire template if a mistake is made. } \section{Creating a template without styles } \leftindent{If you want more templates than those provided by the system, you can make your own and use them in your documents. The only reason for most users to make their own templates is to include set text. The simplest kind of template you can make has no formatting styles on the set text in it, nor does it make available selected-region (that is, style) menu cards that allow users to add styles to documents created with that template. If such a template is sufficient for you, follow the instructions in this section. If you want to apply styles, follow the instructions in the next section. (The next section also presents an example of how to create a template with styles. The example applies to creating a template without styles, if you omit steps 3 and 4 of the example, and ignore the part about adding styles in example step 6.) }\leftindent{ \description{\bold{Step \description{1.}} If this is the first time you are creating a template, create a directory to store your templates by using the \bold{mkdir} command while in your home directory. You can name the templates directory anything you wish. }\leftindent{\description{ }}}\leftindent{\description{\bold{Step 2.} Move into your templates directory (using \bold{cd}). } \description{\bold{Step 3.} In Typescript, type} \leftindent{\leftindent{\typewriter{ez template-name.template}} } \leftindent{where \italic{template-name} is the name of your new template. Do not put a period at the front of \italic{template-name}. To avoid confusion, do not give your template any of the extension/template names that are already mapped in the global.ezinit file. Some of these are listed above in the section titled \bold{Descriptions of some of the available templates}, and Carnegie Mellon users can see a complete listing in \leftindent{/usr/local/lib/global.ezinit} } \description{\bold{Step 4. } Type in the set text you want in the template, and save it.} \description{\bold{Step 5.} Add an addfiletype line to your .ezinit file, to map your new template to an extension. Be sure to read the warning at the top of the \italic{\helptopic{initfiles}} help document before doing this, especially if you have not customized your .ezinit file before. The line should read: } \leftindent{\leftindent{addfiletype .extension text "template=template-name"} where \italic{.extension} (note the period in front) is the extension you want to put on files to create them with your new template, and \italic{template-name} is the name of your template (do not put the .template extension on it). It is least confusing if \italic{extension }and \italic{template-name} are the same. }} \leftindent{\description{\bold{Step 6.} Make sure that your \italic{\helptopic{preferences} }file includes a line that tells EZ where to find your new template. If this is the first time you have created a template, follow the instructions in the section below titled \bold{Setting a template path}. For any further templates you create, either make sure that they are in the directory specified in this preference, or that you amend the preference to include all the relevant directories. }} \section{Creating a template with styles} \leftindent{As explained in the section above on \bold{Changing style definitions}, it is not possible to use EZ to redefine or invent new styles for a template. You can, however, "import" the styles from an existing template, so that the set text in your own template can have styles on it, and so that users of your new template can apply styles in documents they create with the template. To make styles available, you need to perform two more steps than for a style-less template; otherwise the procedure is very similar. (To change style definitions in a template, you must use an editor other than EZ on the template file itself, which allows you to see the datastream specifications written out for each style. It is not recommended that the average user attempt to redefine styles in this way, as it is quite easy to disable the entire template if a mistake is made.) The following general instructions also include example actions that an imaginary user with userid jbRo would use to create his own template for the help files that go with programs he writes. He wants to make the styles from the regular \bold{default} template available in his template, so he follows the steps for making a template with styles: } \leftindent{\description{\bold{Step \description{1.}} If this is the first time you are creating a template, create a directory to store your templates by using the \bold{mkdir} command while in your home directory. You can name the templates directory anything you wish.} \leftindent{\bold{Example. } jbRo would move to his home directory and create a new directory called "templates" by typing the following command in Typescript: \typewriter{mkdir templates} } \description{\bold{Step 2.} Move into your templates directory (using \bold{cd}). } \leftindent{\bold{Example.} jbRo would move to his new "templates" directory by typing the following in Typescript: \typewriter{cd templates}} \description{\bold{Step 3.} In Typescript, type:} \leftindent{ \typewriter{cp /usr/andrew/lib/tpls/\italic{name}.template template\italic{-name}.template} } \leftindent{where \italic{name} is the name of the existing template whose styles you want to copy, and \italic{template-name} is the name of your new template (do not put a period in front). A good choice for \italic{name} is the default template, which has many useful styles in it. The command shown here may appear on two lines, but do not put line breaks (carriage returns) in your command. To avoid confusion, do not give your template any of the extension/template names that are already mapped in the global.ezinit file. Some of these are listed above in the section titled \bold{Descriptions of some of the available templates}, and Carnegie Mellon users can see the complete listing in /usr/local/lib/global.ezinit. \bold{Example. } jbRo would use the following single-line command to copy the styles from the default template into his own template, which he names "jbRohelp.template": \typewriter{cp /usr/andrew/lib/tpls/default.template jbRohelp.template }}} \leftindent{\description{\bold{Step 4.} When the prompt returns, type } \leftindent{\typewriter{chmod +w \italic{template-name}.template} } \leftindent{This enables you to edit your template, which at this point is Read Only because you copied it from a system directory. \bold{Example. }jbRo would type the following command in Typescript: \typewriter{chmod +w jbRohelp.template }} \description{\bold{Step 5. } In Typescript, type} \leftindent{\typewriter{ez template-name.template}} \leftindent{\bold{Example.} jbRo would use EZ to edit his template by typing the following command in Typescript: \typewriter{ez jbRohelp.template} }\description{ \bold{Step 6.} Type in the set text you want in the template, apply styles to it if desired, and save the file. } \description{\bold{Step 7.} Add an addfiletype line to your .ezinit file, to map your new template to an extension. Be sure to read the warning at the top of the \italic{\helptopic{initfiles}} help document before doing this, especially if you have not customized your .ezinit file before. The line should read: } \leftindent{addfiletype \italic{.extension} text "template=\italic{template-name}" where \italic{.extension} (note the period in front) is the extension you want to put on files to create them with your new template, and \italic{template-name} is the name of your template (do not put the .template extension on it). It is least confusing if \italic{extension }and \italic{template-name} are the same. \bold{Example.} jbRo would add the following line to his .ezinit file, following the suggestion that he make the extension the same as the template name: addfiletype .jbRohelp text "template=jbRohelp" }} \leftindent{\description{\bold{Step 8.} Make sure that your \italic{\helptopic{preferences} }file includes a line that tells EZ where to find your new template. If this is the first time you have created a template, follow the instructions in the section below titled \bold{Setting a template path}. For any further templates you create, either make sure they are in the directory specified in this preference, or that you amend the preference to include all the relevant directories. } \leftindent{\bold{Example.} jbRo would add the following single line to his preferences file, so that EZ will know where to look for his new template. His usr# group is 1. } \leftindent{BE2TemplatePath: /afs/andrew.cmu.edu/usr1/jbRo/templates:/usr/andrew/lib/tpls\leftindent{\bold{ }}}} \section{Setting a template path} \leftindent{ If you want EZ to use your new template, you must tell it to look in your templates directory before looking in the normal system directories. You do this with the \bold{BE2TemplatePath} preference in your \italic{ \helptopic{preferences} }file. The line to add is: BE2TemplatePath: \italic{}:/usr/andrew/lib/tpls Using the "full" pathname means not starting with just the tilde (~) and your user id. You can put as many directories as you want in this path, yours as well as those of other users who have made templates. Always use the full pathname and separate each one with a colon. Remember that EZ searches for a requested template in the order specified in the path, stopping when it finds a match. Always end the path with /usr/andrew/lib/tpls, to make sure you get the system templates. }\section{Related Tools} Select (highlight) one of the italicized names and choose "Show Help on Selected Word" from the pop-up menu to see the help document for: \leftindent{ \italic{\helptopic{ez} \helptopic{initfiles} \helptopic{preferences} \helptopic{insets} \helptopic{ez-extensions} }} \begindata{bp,537558784} \enddata{bp,537558784} \view{bpv,537558784,339,0,0} Copyright 1992 Carnegie Mellon University and IBM. All rights reserved. \smaller{\smaller{$Disclaimer: Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $ }}\enddata{text,538351624}