Copyright (C) 2003 W. Michael Petullo <mike@flyn.org>

new is A simple template system

= 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 program understands plaintext or gziped template files.

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

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

To build, cross your fingers and try...

 1. ./configure
 2. make
 3. 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).

FIRSTNAME
    The user's first name (from GECOS field).

MIDDLENAME
    The user's middle name (from GECOS field).

LASTNAME
    The user's last 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.

The alternative may be a format pattern, too. If FIRSTNAME is 
defined a Mike, the following:

%(UNDEFINED:%(before="My name is " FIRSTNAME))

will print ``My name is Mike.''

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

%(upper FOO)

It makes sense to use some modifiers with a literal, instead of a 
key which will be replaced by a value. For example:

%(file FOO)

will insert the text contained in a the file whose path is the 
value of the key FOO. But:

%(file "foo")

will insert the contents of the file named 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.

newlines
    Replaces occurrences of " " in the string with new lines

no_newlines
    Replaces occurrences of "\n" in the string with ' '

remove_underscore
    Replaces occurrences of '_' in the string with '-'

file
    Treats the key as the path to a file, which is included

template
    Treats the key as the path to a template, which is filled and included

#
    A comment, this will not appear in destination file %(# Comment.)

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.

