\begindata{text,538496316}
\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 \bold{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{\italic{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.  \



\italic{\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{a) create the EZ document with a special filename extension \



b) 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{\bold{ez} \italic{filename\bold{.extension}}

}
EZ automatically gives you the template associated with the extension. 
 This works because Andrew system administrators have created mappings 
between extensions and templates\leftindent{.  \


}
If you use an extension that is not mapped (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.  \



See the\italic{  \helptopic{initfiles}}  help file for more information on 
"mapping" extensions.

}
\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{tpl} 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{.tpl} 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{\bold{addfiletype .man text "template=man"}}


You can then use the \bold{.man} extension to get the man template. \


}
You can see a complete list of the templates available by listing the 
contents of


\leftindent{/usr/andrew/lib/tpls}

}}
\section{Changing style definitions}

\leftindent{
It is possible to change the definitions of existing styles in a particular 
EZ document by using the 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 a command window, type}


\leftindent{\leftindent{\bold{ez \italic{template-name}.tpl}}

}
\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.

}
\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{\bold{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.  \


}}
\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 a command window:


\leftindent{\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 \typewriter{cd templates} in a command window. }\



}\description{\bold{Step 3.}  In a command window, type:}

\leftindent{
\leftindent{\bold{cp  /usr/andrew/lib/templates/\italic{name}.tpl 
 \italic{template}\italic{-name}.tpl}}

}
\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.  Some 
of these are listed above in the section titled \bold{Descriptions of some 
of the available templates.

}
\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{\leftindent{cp /usr/andrew/lib/tpls/default.tpl jbRohelp.tpl}

}}}
\leftindent{\description{\bold{Step 4.}  When the prompt returns, type }\



\leftindent{\leftindent{\bold{chmod  +w  \italic{template-name}.tpl}

}}
\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 a command window:


\typewriter{\leftindent{chmod  +w  jbRohelp.tpl}

}}
\description{\bold{Step 5. } In a command window, type}


\bold{\leftindent{\leftindent{ez  \italic{template-name}.tpl}}}


\leftindent{\bold{Example.}  jbRo would use EZ to edit his template by 
typing the following command in a command window:


\leftindent{\typewriter{ez jbRohelp.tpl}}

}\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{\leftindent{\bold{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:


\leftindent{\typewriter{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{\typewriter{\leftindent{BE2TemplatePath: 
/afs/andrew.cmu.edu/usr1/jbRo/templates:/usr/andrew/lib/t}\leftindent{pls

}}}}
\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: \



\leftindent{\bold{BE2TemplatePath: \italic{<full pathname to templates 
directory>}:/usr/andrew/lib/tpls}


}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 \bold{Show Help 
on Selected Word} from the pop-up menu to see the help document for:

\leftindent{
\italic{\helptopic{ez}}                        (An introduction to Andrew's 
text editor)          \


\italic{\helptopic{initfiles}      }\


\italic{\helptopic{preferences}  }        (Customizing many Andrew 
features)

\italic{\helptopic{insets}    }               (The software packages 
available on Andrew)

\italic{\helptopic{ez-extensions}}      (More on how filename extensions 
work in EZ)}


\begindata{bp,538526464}
\enddata{bp,538526464}
\view{bpv,538526464,1,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,538496316}
