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

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.

BRANDING & CUSTOMIZATION

Each time you run mkproject.sh, it looks in its own directory for a file called .mkprojectrc. 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 .mkprojectrc file. By default, after mkproject.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 mkproject.sh looks for the user's copy by changing the USERCONFIGDIR variable in the master copy of .mkprojectrc.

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 .mkprojectrc, 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)
__COPYOWNER__     Copyright string (.mkprojectrc)
__COPYRIGHT__     Full copyright string (internal)
__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`` (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 (.mkprojectrc)
__WEBSITE__       Website where updates can be found (.mkprojectrc)

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.

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.113 2012/06/05 16:50:16 tundra Exp $

You can find the latest version of this program at:

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