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. Documention 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.
- When writing your 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``::
Token Replaced By
----- -----------
__AUTHOR__ The name of the program's author defined in``.mkprojectrc``
__COPYRIGHT__ The full copyright string defined in``.mkprojectrc``
__COST__ The cost passed on the command line
__DESCRIPTION__ The project description passed on the command line
__EDITOR__ The name of the editor defined in``.mkprojectrc``
__EDITARGS__ The editor arguments defined in``.mkprojectrc``
__EMAILSUPPORT__ The email support address defined in``.mkprojectrc``
__ID__ The CVS version string, ``$Id``
__INTERPRETER__ The "hash bang" string used for the selected language.
__LANGUAGE__ The name of the language
__LICENSE__ The full name of the license file
__PROJECTNAME__ The name of the project passed on the command line
__RESERVED__ A reference to the license file for terms of use
__TYPE__ The program type passed on the command line
__UPDATES__ A reference to the website that has updates defined in``.mkprojectrc``
__VENDORNAME__ The name of the project vendor defined in``.mkprojectrc``
__WEBSITE__ The website where updates can be found defined in``.mkprojectrc``
OTHER
-----
None.
BUGS AND MISFEATURES
--------------------
None known as of this release.
COPYRIGHT AND LICENSING
-----------------------
**mkproject** is Copyright (c) 2012 TundraWare Inc., Des Plaines, IL 60018 USA
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.102 2012/06/01 22:18:44 tundra Exp $
You can find the latest version of this program at:
http://www.tundraware.com/Software/mkproject
tundra