NAME

mkproject - Rapid Project Templating

SYNOPSIS

mkproject.sh  name type cost 'description'

  where,

    name           Name of the project
    type           Programmnig language (pl, py, sh ...)
    cost           What you wish to charge ($0.99 ...)
    'description'  A brief description of the project
                   Must be passed as a single argument

DESCRIPTION

mkproject 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 mkproject will have YOUR licensing terms in it.

REQUIRED ENVIRONMENT

mkproject 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.)

docutils

TeX/LaTex (A full implementation w/utilities.)

enscript

flip

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

BRANDING

Before using mkproject, you have to customize it with your site-specific information. You do this by editing the .mkprojectrc file. This branding information is then passed on to every project you create thereafter.

CREATING A NEW PROJECT

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

mkproject.sh name type cost 'description`

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

For example::

mkproject.sh MyFineProject py $0.98  'A Cheap 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``MyFineProject-license.txt`` would have the price of $0.98 embedded in it. The various program and documentation files would have the description "A Cheap Program That Does Nothing" embedded appropriately.

MAKE OPTIONS

Projects created by mkproject 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 mkproject.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 - mkproject 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 mkproject will fill in when it creates a new project. You can see examples of how these are used in the example skeletons provided with mkproject.

The major tokens of interst are:

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

__AUTHOR__        Program author's name  (.mkprojectrc)
__COPYRIGHT__     Full copyright string (.mkprojectrc)
__COST__          Cost (command line argument)
__DESCRIPTION__   Project description (command line argument)
__EDITOR__        Name of editor (.mkprojectrc)
__EDITARGS__      Editor arguments (.mkprojectrc)
__EMAILSUPPORT__  Email support address (.mkprojectrc)
__ID__            CVS version string, ``$Id``
__INTERPRETER__   "Hash bang" string for the selected language.
__LANGUAGE__      Name of the language
__LICENSE__       Full name of the license file
__PROJECTNAME__   Name of the project (command line argument)
__RESERVED__      Reference to the license file for terms of use
__TYPE__          Program type (command line argument)
__UPDATES__       Reference to the update website (.mkprojectrc)
__VENDORNAME__    Name of the project vendor (.mkprojectrc)
__WEBSITE__       Website where updates can be found (.mkprojectrc)

OTHER

None.

BUGS AND MISFEATURES

None known as of this release.

COPYRIGHT AND LICENSING

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

AUTHOR

Tim Daneliuk
mkproject@tundraware.com

DOCUMENT REVISION INFORMATION

$Id: tmkproject.rst,v 1.108 2012/06/02 05:09:25 tundra Exp $

You can find the latest version of this program at:

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