Copyright (c) 1999 W. Michael Petullo <new@flyn.org>
All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

=============================== OVERVIEW =======================================

New is a template system, especially useful in conjunction with a simple
text editor such as vi.  The user maintains templates which may contain
format strings.  At run time, new replaces the format strings in a
template with appropriate values to create a new file.

For example, given the following template:

//   FILE: %(FILE)
// AUTHOR: %(FULLNAME)
//   DATE: %(DATE)

// Copyright (c) 1999 %(FULLNAME) <%(EMAIL)>
// All rights reserved.

new will create:

//   FILE: foo.cpp
// AUTHOR: W. Michael Petullo
//   DATE: 11 September 1999 

// Copyright (c) 1999 W. Michael Petullo <new@flyn.org>
// All rights reserved.

on my computer.

The new program understands plaintext or gzip template files.

Building new also creates a shared library, libtemplate, which allows
the programmer access to new's functionality.

=============================== BUILDING =======================================

To build, cross your fingers and try:

./configure
make
make install

Read the ``INSTALL'' file for generic detailed information on installing
this program.

=============================== NASTY DETAILS ==================================

New first looks for templates in ~/.new/templates.  Second, new looks
for templates in <datadir>/new/template, where datadir 
is defined by autoconf.  This directory is usually /usr/local/share
or /usr/share.

The templates directory contains several subdirectories matching filename
extensions.  This may include directories such as html, cpp, c, and tex.
Within each subdirectory are the actual template files.  The template
file named ``default'' is the default template used for the filename
extension.  Other templates can be used by specifying their filename to
new on the command line (see new (1)).

Certain types of files generally don't have extensions.  In this case, new
looks for a template directory with the same name as the file being
created.  This is useful when using templates to create files with names
such as Makefile and README.

When filling a format pattern, new knows the value for the following
format patterns:

DATE		Today's date.
FILE		The name of the file being created.
FULLNAME	The user's full name (from GECOS field).
EMPTY_STR	The empty string.

In addition, any environment variable can be used as a format pattern.
An alternate string to be used in the case of an environment variable
being undefined can be specified as follows:

%(UNDEFINED:foo)

This will be replaced with ``foo'' in the created file if UNDEFINED is
not a part of one's environment.

A format pattern can also be acted on by a modifier.  The following will
print the value of FOO in capital letters:

%(upper FOO)

The following modifiers are currently available:

upper -- convert to upper case.
lower -- convert to lower case.
basename -- convert to the basename of a filename.
before="str" -- Append the string str before.
after="str" -- Append the string str after.
fn -- tag a " ()" on the end.
c_delim -- print enveloped in a C style deliminator, ie: /* == foo == */.
cpp_delim -- print enveloped in a C++ style deliminator, ie: // == foo.
sh_delim -- print enveloped in a shell script style deliminator, ie: # == foo.
tex_delim -- print eveloped in a LaTeX style deliminator, ie: % == foo.

Several modifiers can act within one format string as illustrated:

%(basename upper FOO)

Modifiers use a stack to be applied.  The first modifier to be applied
is the one farthest to the right.  The last to be applied it the one
farthest to the left.

=============================== PROVIDED TEMPLATES =============================

I have included in the new distribution the templates that I use.
While you may not find them directly useful, they serve as good examples
of how to write new templates.

A few of my templates make references to special environment variables,
which I define in my login scripts:

.in (spec), .spec (default):
RPM_BUILD_ROOT -- Directory to be used for RPM's BuildRoot (/ if undefined).
URL -- URL to be used for RPM's URL (FIXME if undefined).

.am (default):
WEB_DIR -- Directory for publishing to the web; used by `make publish`
clause (/tmp if undefined).

Makefile (rpm), am (default):
RPM_TOP_DIR -- RPM's topdir (/usr/src/redhat or as specified by %_topdir
in .rpmmacros) (/usr/src/redhat if undefined).

.tex (letter):
ADDRESS_1 -- Line one of sender's mailing address (for return address)
(FIXME: return address line one if undefined).
ADDRESS_2 -- Line two of sender's mailing address (FIXME: return address
line two if undefined).
CITY -- City the sender lives in (FIXME: city if undefined).
STATE -- State the sender lives in (FIXME: state if undefined).
ZIP_CODE -- Zip code the sender lives in (FIXME zip if undefined).

.tex (army_letter, army_memo):
ARMY_ADDRESS_1 -- Line one of sender's Army mailing address (for return
address) (FIXME: Army return address line one if undefined).
ARMY_ADDRESS_2 -- Line two of sender's Army mailing address (for return
address) (FIXME: Army return address line two if undefined).
RANK -- Sender's rank (FIXME: rank if undefined).
