NAME
----

**tmkproject** - Rapid Project Templating


SYNOPSIS
--------

::

  tmkproject.sh [-c] name type 'description'

    where,

      -c             Create project, but do not check into CVS
      name           Name of the project
      type           Programmnig language (pl, py, sh ...)
      'description'  A brief description of the project
                     Must be passed as a single argument

  tmkproject.sh -v

      Displays program version and exits


DESCRIPTION
-----------

``tmkproject`` is a way to quickly produce the code and documentation
skeletons for a new project and to put these under ``CVS`` version
control.  It allows you to "brand" them with your own company and
copyright information, as well specifying a standard license and
pricing (if any).

The package comes with example templates for ``perl``, ``python``, and
``shell scripts``.  These contain some of the standard code you may
want to use with every project.

Also included is an example standard for writing documentation using
the ``Restructured Text`` markdown language.

Finally, a ``makefile`` is included to produce documentation and
release packaging for your project.  Documentation is automatically
produced in a wide variety of formats including ``html``,
``PostScript``, ``pdf``, ``man``, and plain text.

The package comes with a default ``Makefile`` that is useful when
creating a ``FreeBSD`` port of your project.

Because everything is template-driven, it is simple to customize the
"standard" program and documentation templates to suit your needs.  It
is also quite straightforward to add support for additional languages.

For example, you almost certainly will want to change the licensing
terms contained in ``./common/license.txt``.  Once you've edited
that file, every project you create with ``tmkproject`` will have
YOUR licensing terms in it.


REQUIRED ENVIRONMENT
--------------------

``tmkproject`` requires certain tools to be properly installed and
configured in order to operate properly.  The majority of these have
to do with producing documentation in various output formats from a
Restructured Text source document:

  - ``CVS``        (You must have this properly configured for checkin, checkout.)
  - ``Python``
  - ``TeX/LaTex``  (A full implementation w/utilities like TeX Live.)
  - ``docutils``
  - ``enscript``

You also need a modern version of ``make``, like the one from the GNU
project.  Old BSD type ``make`` utilities will not work.

The ``python`` skeleton includes code to parse a configuration file
using the TundraWare Inc. ``tconfpy`` parser.  ``tconfpy`` is not
included in the ``tmkproject`` package distribution, hence
configuration file handling is commented out in the ``python`` code
skeleton.  If you wish to use ``tconfpy``, it is freely available at:

  http://www.tundraware.com/Software/tconfpy


BRANDING & CUSTOMIZATION
------------------------


Each time you run ``tmkproject.sh``, it looks in its own directory for
a file called ``.tmkproject``.  This file contains site-specific
items you may wish to customize.  These are things like the vendor
name, program author's name, the editor to use, and so on.  The
information found in this file is applied to each new project you
create.

Each user can also maintain their own copy of the ``.tmkproject``
file.  By default, after ``tmkproject.sh`` reads the "master" copy in
its own directory, it looks for a copy in the user's home directory.
That way, each user can override the site-wide defaults to suit
themselves.  You can change where ``tmkproject.sh`` looks for the
user's copy by changing the ``USERCONFIGDIR`` variable in the master
copy of ``.tmkproject``.


CREATING A NEW PROJECT
----------------------

Once you've edited ``.tmkproject``, you are ready to create a new
project.  Recall that you do this::

  tmkproject.sh name type 'description`

This will generate a project under the ``PROJECTSDIR`` directory
defined in ``.tmkproject``, and check them in to ``CVS``.

For example:: 

  tmkproject.sh MyFineProject py 'A Free Program That Does Nothing`

Would create the directory ``${PROJECTSDIR}/MyFineProject``.  This
directory would contain all the program, documentation, and licensing
files needed to start the project, along with a ``makefile`` to
support document creation and project packaging.
 
The various program and documentation files would have the description
"A Free Program That Does Nothing" embedded appropriately.


MAKE OPTIONS
------------

Projects created by ``tmkproject`` are controlled by a ``makefile``
that allows you to do everything from produce documentation
to package everything for release.  The ``makefile`` supports
the following major targets::

  docs      Produce project documentation is a wide variety of formats
            including html, PostScript, pdf, man format, and plain text.

  release   Create a release tarball in the project's ./Releases
            directory.  The tarball will contain both the name
            and version number of the project.

  clean     Remove the intermediate files created during
            the documentation production process.

  scrub     Remove (almost) everything, except for the makefile itself
            and the support/release directories.

  init      Scrub the working directory and checkout the last
            committed copies from the CVS repository.

  version   Display the current version of the project.


HOW TO ADD A NEW LANGUAGE
-------------------------

You can add new language support pretty trivially:

- Edit ``tmkproject.sh`` and add a stanza to the ``case`` statement
  near the top to define the ``INTERPRETER`` and ``LANGUAGE``
  variables appropriately for the new language.

- Create a new directory named after the language type - usually it is
  the suffix used to name source files in that language.  Under this
  directory, place any files or templates you want as defaults for
  every project of that type.  At a minimum, you *must* include a file
  named ``program.typesuffix``.  This should be your default skeleton
  code for that language.  Do *not* include the initial header block -
  ``tmkproject`` will insert it for you.

- In ``common/makefile`` add an ``enscript`` (or other pretty printer
  program) stanza to pretty print your program code.

SUBSTITUTION TOKENS
-------------------

When writing your own skeleton code and documentation files, there are
a number of tokens you can use which ``tmkproject`` will fill in when
it creates a new project. You can see examples of how these are used
in the example skeletons provided with ``tmkproject``.

The major tokens of interst are::


       Token                       Replaced By
       -----                       -----------

    __AUTHOR__        Program author's name  (.tmkproject)
    __COPYOWNER__     Copyright string (.tmkproject)
    __COPYRIGHT__     Full copyright string (internal)
    __DESCRIPTION__   Project description (command line argument)
    __EDITOR__        Name of editor (.tmkproject)
    __EDITARGS__      Editor arguments (.tmkproject)
    __EMAILSUPPORT__  Email support address (.tmkproject)
    __FULLNAME__      The full name of the program w/type suffix
    __ID__            CVS version string, ``$Id`` (internal)
    __INTERPRETER__   "Hash bang" string for the selected language.
    __LANGUAGE__      Name of the language (internal)
    __LICENSE__       Full name of the license file (internal)
    __PROJECTNAME__   Name of the project (command line argument)
    __RESERVED__      "All Rights Reserved ..." string (internal) 
    __TYPE__          Program type (command line argument)
    __UPDATES__       Reference to the update website (internal)
    __VENDORNAME__    Name of the project vendor (.tmkproject)
    __WEBSITE__       Website where updates can be found (.tmkproject)

You can also define additional substitution tokens of your own by
editing the ``tokens`` file provided with the program distribution.
This file is read every time you generate a new project.  The
left-hand column is the name of the substitution token and the
right-hand column is the substitution text.

The right-hand entry can be any combination of variable references
(assuming they are defined) and literal text. *Bear in mind that this
has to make sense to* ``sed`` *which is used to do the actual
substitutions!* For example, you will see ``$`` and ``/`` escaped so
that ``sed`` does the right thing.  This escaping has to be done
appropriately in both the ``tokens`` file and anywhere a variable is
defined that is referenced in a substitution token definition.  For
example, ``__WEBSITE__`` refers to ``${WEBSITE}`` which actually gets
defined in ``.tmkproject``.  If you look there, you will see that all
the forward slashes have been escaped in anticipation of the fact that
we're going to feed the string to ``sed``.


OTHER
-----

None.


BUGS AND MISFEATURES
--------------------

None known as of this release.


COPYRIGHT AND LICENSING
-----------------------

**tmkproject** is Copyright (c) 2012 TundraWare Inc., Des Plaines, IL 60018 USA

For terms of use, see the ``tmkproject-license.txt`` file in the
program distribution.


AUTHOR
------

::

   Tim Daneliuk
   tmkproject@tundraware.com


DOCUMENT REVISION INFORMATION
-----------------------------

::

  $Id: tmkproject.rst,v 1.128 2012/09/06 15:56:08 tundra Exp $

You can find the latest version of this program at:

  http://www.tundraware.com/Software/tmkproject