diff --git a/tmkproject.rst b/tmkproject.rst index 036407e..939bec3 100644 --- a/tmkproject.rst +++ b/tmkproject.rst @@ -1,64 +1,272 @@ -\documentclass[a4paper]{article} -% generated by Docutils -\usepackage{fixltx2e} % LaTeX patches, \textsubscript -\usepackage{cmap} % fix search and cut-and-paste in Acrobat -\usepackage{ifthen} -\usepackage[T1]{fontenc} -\usepackage[utf8]{inputenc} +NAME +---- -%%% Custom LaTeX preamble -% PDF Standard Fonts -\usepackage{mathptmx} % Times -\usepackage[scaled=.90]{helvet} -\usepackage{courier} - -%%% User specified packages and stylesheets -\usepackage{parskip} - -%%% Fallback definitions for Docutils-specific commands - -% hyperlinks: -\ifthenelse{\isundefined{\hypersetup}}{ - \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} - \urlstyle{same} % normal text font (alternatives: tt, rm, sf) -}{} +**tmkproject** - Rapid Project Templating -%%% Body -\begin{document} +SYNOPSIS +-------- -\#!/usr/local/bin/python2.7 +:: -\# \$Id: tmkproject.rst,v 1.126 2012/09/05 17:22:00 tundra Exp $ -\# Author: David Goodger <\href{mailto:goodger@python.org}{goodger@python.org}> -\# Copyright: This module has been placed in the public domain. + tmkproject.sh name type 'description' -``''`` -A minimal front end to the Docutils Publisher, producing LaTeX. -''``'' -% -\begin{description} -\item[{try:}] \leavevmode -import locale -locale.setlocale(locale.LC\_ALL, '') + where, -\item[{except:}] \leavevmode -pass + 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 -\end{description} + tmkproject.sh -v -from docutils.core import publish\_cmdline -% -\begin{description} -\item[{description = ('Generates LaTeX documents from standalone reStructuredText '}] \leavevmode -'sources. ' -'Reads from (default is stdin) and writes to ' -' (default is stdout). See ' -'<\url{http://docutils.sourceforge.net/docs/user/latex.html}> for ' -'the full reference.') + Displays program version and exits -\end{description} -publish\_cmdline(writer\_name='latex', description=description) +DESCRIPTION +----------- -\end{document} +``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.127 2012/09/05 17:23:07 tundra Exp $ + +You can find the latest version of this program at: + + http://www.tundraware.com/Software/tmkproject + + + +