
README

W. Michael Petullo
     _________________________________________________________________

   Table of Contents

   [1]COPYRIGHT
   [2]OVERVIEW
   [3]BUILDING
   [4]NASTY DETAILS
   [5]PROVIDED TEMPLATES

COPYRIGHT

   Copyright  1999 W. Michael Petullo

   <[6]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 [7]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 [8]gziped template files.

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

BUILDING

   Procedure 1. 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.

   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_underscores
          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.

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_CODEi
          Zip code the sender lives in (FIXME zip if undefined).

References

   1. file://localhost/tmp/xmlto.8A56ua/README.proc#id2751316
   2. file://localhost/tmp/xmlto.8A56ua/README.proc#id2750466
   3. file://localhost/tmp/xmlto.8A56ua/README.proc#id2751740
   4. file://localhost/tmp/xmlto.8A56ua/README.proc#id2751149
   5. file://localhost/tmp/xmlto.8A56ua/README.proc#id2798841
   6. mailto:new@flyn.org
   7. http://www.vim.org/
   8. http://www.gnu.org/software/gzip/gzip.html
