\begindata{text,538389648}
\textdsversion{12}
\template{help}
\define{global
}
\chapter{Dogtags: Automatic substitution of information in templates

}
\section{What dogtags are

}\leftindent{
`Dogtags' are single words delimited by <@ @> characters.  Normally used in 
templates, the dogtags, when detected in a file being read, are removed and 
replaced with the appropriate information.  They are probably of little 
importance to you unless you are creating templates.

}
\section{Where dogtags are used

}\leftindent{
Dogtags only function in source code views (such as ctext, m3text, 
plmitext, hlptext, etc).

}
\section{List of available dogtags

}\leftindent{
The following are the currently available dogtags, and examples of what 
information is substituted when the file is loaded:  (note the ending @> 
was omitted to avoid corrupting the examples with actual information next 
time this help file is edited). (also note that <@log is intentionally 
recursive).


<@name          myfile

<@NAME          MYFILE

<@filename      myfile.c

<@pathname      /afs/rchland.ibm.com/usr3/rskm/myfile.c

<@date          Fri Sep 20 1991

<@day           20

<@day0          20

<@mon           9

<@mon0          09

<@year          1991

<@yr            91

<@time          16:10:20

<@programmer    Robert Kemmetmueller

<@userid        rskm

<@file:\italic{filename} \italic{contents of filename}

<@log           <@log

                Fri Sep 20 1991  16:10:21  by Robert Kemmetmueller

                <reason><version><Brief description and why change was 
made.>

}\section{Warnings

}\leftindent{
Note that dogtags have no respect for strings, whitespace, language syntax, 
being inside comments, or anything.  This is by design; it is also why such 
obscure delimiters were chosen.


Remember, in the examples shown above, the ending @> was omitted.  To be 
recognized, a dogtag must have both delimiters; they are case-sensitive and 
cannot have any other characters within the delimiters. (except as noted 
below)}


\leftindent{The <@file:\italic{filename} dogtag, if it has even the 
\italic{tiniest} problem trying to read \italic{filename}, will simply 
remove the dogtag itself and substitute \italic{nothing} in its place.


<@day0 and <@mon0 are indentical to <@day and <@mon, except they pad 
one-digit numbers with a leading zero.

}
\section{Additional Features

}
\leftindent{Dogtags can be justifed (left, center, or right) by judicious 
placement of underscore (`_') characters within the <@ and @> delimiters. 
 The size of the field is determined by the number of underscores; the 
space taken by the delimiters and the dogtag name is discarded, and not 
part of the equation.


Example: To put information into a "box" which should have all its right 
edges in the same place, you would put the following in your template: 
\smaller{(JUST put the underscores in to help you line things up easily; 
add the dogtags and their delimiters only after you've lined things up)}

\example{\smaller{/************************/

/* ____________________ */

/*            ________  */

/*            ________  */

/************************/

}}Then, add the dogtag names and delimiters as appropriate.


\typewriter{<@dogtag____@>} will left-justify the information in a field of 
4 characters.

\typewriter{<@____dogtag@>} will right-justify the information in a field 
of 4 characters.

\typewriter{<@_dogtag___@>} will center the information in a field of 4 
characters. \smaller{(because there are underscores both before AND after 
the dogtag name.  The field size is the sum of both; it is irrelevant how 
many are on which side).}


The underscore can also be used to repeat a single character many times. 
 \smaller{(People who prefer \typewriter{/*-----*/} to 
\typewriter{/*******/} need only replace a single character in their 
modified template)}.  Just use the desired character as the dogtag name.


With the <@file:\italic{filename} dogtag, note that \italic{filename} will 
be expanded.  This means you can use tildes, and do neat tricky stuff with 
environment variables within the filename, or whatever.

}
\section{Recent changes to dogtags

}\leftindent{
Dec.'93: Added individual day/month/yr dogtags.

Nov.'93: Added ability to do substitutions in limited area (for Paste and 
Insert File).

Sep.'93: Added <@file: dogtag

Jan.'93: Added left/right/center justification.

Sept.'91: Added the uppercase <@NAME dogtag.

}
\section{Related tools}  \



\leftindent{Move your mouse cursor to one of the following names and click 
your left mouse button to see the help file for:


\leftindent{\helptopic{ez}

\helptopic{srctext

\helptopic{hlptext}}

\helptopic{templates}}}


\begindata{bp,538210560}
\enddata{bp,538210560}
\view{bpv,538210560,0,0,0}
Copyright 1992, 1994 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,538389648}