diff --git a/TODO b/TODO index ed02d58..fb87c65 100644 --- a/TODO +++ b/TODO @@ -1,2 +1,3 @@ - Change -v option to use PrintStdout() instead of print - Change Python skeleton to automatically include OPTIONSLIST into the help menu +- Fix document generation with latest version of restructured text diff --git a/tmkproject.rst b/tmkproject.rst index aa23b0a..036407e 100644 --- a/tmkproject.rst +++ b/tmkproject.rst @@ -1,271 +1,64 @@ -NAME ----- +\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} -**tmkproject** - Rapid Project Templating +%%% Custom LaTeX preamble +% PDF Standard Fonts +\usepackage{mathptmx} % Times +\usepackage[scaled=.90]{helvet} +\usepackage{courier} +%%% User specified packages and stylesheets +\usepackage{parskip} -SYNOPSIS --------- +%%% 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.sh name type 'description' - where, +%%% Body +\begin{document} - 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 +\#!/usr/local/bin/python2.7 - tmkproject.sh -v +\# \$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. - Displays program version and exits +``''`` +A minimal front end to the Docutils Publisher, producing LaTeX. +''``'' +% +\begin{description} +\item[{try:}] \leavevmode +import locale +locale.setlocale(locale.LC\_ALL, '') +\item[{except:}] \leavevmode +pass -DESCRIPTION ------------ +\end{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. +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.') -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. +\end{description} -Also included is an example standard for writing documentation using -the ``Restructured Text`` markdown language. +publish\_cmdline(writer\_name='latex', description=description) -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.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 - - - - +\end{document}