\begindata{text,538619688}
\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 Typescript, 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 
Typescript:


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


}\description{\bold{Step 3.}  In Typescript, 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 Typescript:


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

}}
\description{\bold{Step 5. } In Typescript, 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 Typescript:


\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,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,203,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: This software is part of version 6.1 of the 

Andrew User Interface System and is 

the property of IBM, Carnegie Mellon University, 

and the other copyright holders.  The source 

code of this version is for the sole use of 

the individual named in ./config/allsys.h.  

This source code is not to be redistributed.  

Binary object code compiled or derived from 

these sources is not to be distributed to non-

members.  Members may have additional 

distribution rights granted by prior written 

permission of Carnegie Mellon University.



IBM, CARNEGIE MELLON UNIVERSITY, 

AND THE OTHER COPYRIGHT HOLDERS

 DISCLAIM ALL WARRANTIES WITH 

REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANT-

ABILITY AND FITNESS. IN 

NO EVENT SHALL  IBM, CARNEGIE 

MELLON UNIVERSITY, OR ANY OTHER 

COPYRIGHT HOLDER BE LIABLE FOR 

ANY SPECIAL, INDIRECT OR CONSE-

QUENTIAL 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,538619688}
