NAME

tmkproject - Rapid Project Templating

SYNOPSIS

tmkproject.sh  name type 'description'

  where,

    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.

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

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.125 2012/06/28 04:51:05 tundra Exp $

You can find the latest version of this program at:

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