generate the man file directly from the output of "pycam --help" (via "help2man")

git-svn-id: https://pycam.svn.sourceforge.net/svnroot/pycam/trunk@597 bbaffbd6-741e-11dd-a85d-61de82d9cad9

Makefile

-# BEWARE: this makefile is solely used for preparing a release - it is not useful for compiling/installing the program
+# export SVN_REPO_BASE=. if you want to use the local version instead of trunk
+# from the subversion repository.
 
 # use something like "VERSION=0.2 make" to override the VERSION on the command line
 VERSION ?= $(shell sed -n "s/^.*[\t ]*VERSION[\t ]*=[\t ]*[\"']\([^\"']*\)[\"'].*/\1/gp" src/pycam/__init__.py)
@@ -21,7 +22,7 @@ DISTUTILS_PLAT_NAME = $(shell $(PYTHON_EXE) setup.py --help build_ext | grep -q
 # turn the destination directory into an absolute path
 ARCHIVE_DIR := $(shell pwd)/$(ARCHIVE_DIR_RELATIVE)
 
-.PHONY: zip tgz win32 clean dist svn_export upload create_archive_dir
+.PHONY: zip tgz win32 clean dist svn_export upload create_archive_dir man
 
 dist: zip tgz win32
 	@# remove the tmp directory when everything is done
@@ -30,6 +31,9 @@ dist: zip tgz win32
 clean:
 	@rm -rf "$(EXPORT_DIR)"
 
+man: svn_export
+	@make -C "$(EXPORT_DIR)/man"
+
 svn_export: clean
 	@if svn info &>/dev/null;\
 		then svn export --quiet "$(SVN_REPO_BASE)" "$(EXPORT_DIR)";\
@@ -39,13 +43,13 @@ svn_export: clean
 create_archive_dir:
 	mkdir -p "$(ARCHIVE_DIR)"
 
-zip: create_archive_dir svn_export
+zip: create_archive_dir man svn_export
 	cd "$(EXPORT_DIR)"; $(PYTHON_EXE) setup.py sdist --format zip --dist-dir "$(ARCHIVE_DIR)"
 
-tgz: create_archive_dir svn_export
+tgz: create_archive_dir man svn_export
 	cd "$(EXPORT_DIR)"; $(PYTHON_EXE) setup.py sdist --format gztar --dist-dir "$(ARCHIVE_DIR)"
 
-win32: create_archive_dir svn_export
+win32: create_archive_dir man svn_export
 	# this is a binary release
 	cd "$(EXPORT_DIR)"; $(PYTHON_EXE) setup.py bdist --format wininst --dist-dir "$(ARCHIVE_DIR)" $(DISTUTILS_PLAT_NAME)
 

debian/control

@@ -3,7 +3,7 @@ Section: python
 Priority: extra
 Maintainer: Sebastian Kuzminsky <seb@highlab.com>
 Build-Depends: python, debhelper (>= 7), cdbs, patchutils
-Build-Depends-Indep: python-support
+Build-Depends-Indep: python-support, help2man
 Standards-Version: 3.8.4
 Homepage: http://sourceforge.net/projects/pycam/
 

man/Makefile

+.PHONY: clean
+
+pycam.1: ../pycam pycam.1.inc
+	help2man --no-info --name="Toolpath Generation for 3-Axis CNC machining" \
+		--section=1 --manual="PyCAM manual" --include=pycam.1.inc --output=pycam.1 ../pycam
+
+clean:
+	@rm -f pycam.1
+

man/pycam.1

-.TH PyCAM 1 "April 02010" "PyCAM" "PyCAM manual"
-.SH NAME
-pycam \- start the graphical user interface of the \fBPyCAM\fR Toolpath Generator
-for 3-Axis CNC machining
-.SH SYNOPSIS
-.B pycam
-[\fIoptions\fR] [\fISTL_input\fR [\fIGCode_output\fR]]
-.SH DESCRIPTION
-.PP
-\fBPyCAM\fR is a toolpath generator for 3-axis CNC machining. 
-.PP
-You can configure different cutter shapes and differen path strategies for preparing
-multiple passes.
-.PP
-The output of \fBPyCAM\fR is G-Code suitable for EMC2 or other machine controllers.
-.SH OPTIONS
-The following options control the behaviour of \fBPyCAM\fR:
-.TP
-\fB\-h\fR, \fB\-\-help\fR
-show the available options and exit
-.TP
-\fB\-\-gui\fR
-don't create the outputfile on the fly - just preset the output filename and show the GUI
-.TP
-\fB\-\-gtk\fR
-use the new GTK interface (default)
-.TP
-\fB\-\-tk\fR
-use the (old) Tk interface
-.TP
-\fB\-c\fR, \fB\-\-config\fR=\fBCONFIG_FILE\fR
-load a task settings file (requires the GTK interface)
-.TP
-\fB\-\-task\fR=\fBTASK\fR
-choose a specific task from task settings by number
-(requires the GTK interface)
-.TP
-\fB\-\-disable-ode\fR
-disable experimental ODE collision detection
-.SH ENVIRONMENT VARIABLES
-.IP PYCAM_DATA_DIR
-Override the default location of the GTK interface definition files.
-.IP PYTHONPATH
-You may want to define this variable in case that you installed the
-\fBPyCAM\fR python package in a non-default location.
-.SH AUTHOR
-Written by Lars Kruse
-.SH REPORTING BUGS
-See http://sourceforge.net/tracker/?group_id=237831&atid=1104176
-.SH COPYRIGHT
-Copyright \(co 02010 Lars Kruse
-.br
-This is free software. You may redistribute copies of it under the terms of the
-GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO
-WARRANTY, to the extent permitted by law.

man/pycam.1.inc

+[ENVIRONMENT]
+.IP PYCAM_DATA_DIR
+Override the default data directory of PyCAM. This allows
+you to provide customized logos, menu files or non-default sample files.
+.IP PYTHONPATH
+You may want to define this variable in case that you installed the
+\fBPyCAM\fR python package in a non-default location.
+
+[REPORTING BUGS]
+See http://sourceforge.net/tracker/?group_id=237831&atid=1104176
+
+[SEE ALSO]
+Take a look at the output of \fBpycam --help\fR to get a slightly better
+formatted list of options. The manual that you are reading right now is
+derived from this output.
+
+Take a look at the wiki for more information about PyCAM:
+http://sourceforge.net/apps/mediawiki/pycam/
+

pycam

@@ -36,6 +36,7 @@ import pycam.Toolpath.Generator
 import pycam.Toolpath
 from pycam import VERSION
 import pycam.Utils.log
+import logging
 
 log = pycam.Utils.log.get_logger()
 
@@ -100,17 +101,16 @@ def get_default_model():
 
 # check if we were started as a separate program
 if __name__ == "__main__":
-    parser = OptionParser( prog="PyCAM", version="PyCAM v%s" % VERSION,
+    parser = OptionParser(prog="PyCAM",
             usage="usage: %prog [options] [inputfile]\n\n" \
                     + "Use any of the '--export-???' parameters to disable " \
                     + "the graphical user interface (GUI).\n" \
-                    + "When starting the GUI (default) all arguments except " \
-                    + "'inputfile' are ignored.\n" \
+                    + "When starting the GUI (the default) all arguments " \
+                    + "except 'inputfile' are ignored.\n" \
                     + "'inputfile' may be an STL or DXF file.",
-            epilog="Use any of the '--export-???' parameters to enable " \
-                    + "non-interactive mode. Otherwise all options (except " \
-                    + "'inputfile') are silently ignored and the GUI is " \
-                    + "started.")
+            epilog="Take a look at the wiki for more information: " \
+                    + "http://sourceforge.net/apps/mediawiki/pycam/.\n" \
+                    + "Bug reports: http://sourceforge.net/tracker/?group_id=237831&atid=1104176")
     group_general = parser.add_option_group("General options")
     group_export = parser.add_option_group("Export formats",
             "Export the resulting toolpath or meta-data in various formats. " \
@@ -137,6 +137,9 @@ if __name__ == "__main__":
             + "place during the mill operation. The support grid can be " \
             + "removed manually afterwards. The support grid can have a " \
             + "rectangular profile. By default the support grid is disabled.")
+    group_external_programs = parser.add_option_group("External programs",
+            "Some optional external programs are used for format conversions.")
+    # general options
     group_general.add_option("-c", "--config", dest="config_file",
             default=None, action="store", type="string",
             help="load a task settings file")
@@ -159,6 +162,13 @@ if __name__ == "__main__":
     group_general.add_option("", "--disable-psyco", dest="disable_psyco",
             default=False, action="store_true", help="disable the Psyco " \
                     + "just-in-time-compiler even when it is available")
+    group_general.add_option("-q", "--quiet", dest="quiet",
+            default=False, action="store_true", help="show only warnings and " \
+            + "errors.")
+    group_general.add_option("-v", "--version", dest="show_version",
+            default=False, action="store_true", help="show the current " \
+            + "version of PyCAM and exit")
+    # export options
     group_export.add_option("", "--export-gcode", dest="export_gcode",
             default=None, action="store", type="string",
             help="export the generated toolpaths to a file")
@@ -166,6 +176,7 @@ if __name__ == "__main__":
             dest="export_task_config", default=None, action="store",
             type="string",
             help="export the current task configuration (mainly for debugging)")
+    # tool options
     group_tool.add_option("", "--tool-shape", dest="tool_shape",
             default="cylindrical", action="store", type="choice",
             choices=["cylindrical", "spherical", "toroidal"],
@@ -187,6 +198,7 @@ if __name__ == "__main__":
             default=1, action="store", type="int",
             help="tool ID - to be used for tool selection via GCode " \
             + "(default: 1)")
+    # process options
     group_process.add_option("", "--process-path-direction",
             dest="process_path_direction", default="x", action="store",
             type="choice", choices=["x", "y", "xy"],
@@ -220,6 +232,7 @@ if __name__ == "__main__":
             dest="process_engrave_offset", default=0.0, action="store",
             type="float", help="engrave along the contour of a model with a " \
             + "given distance (only for 'engrave' strategy)")
+    # bounds settings
     group_bounds.add_option("", "--bounds-type", dest="bounds_type",
             default="relative-margin", action="store", type="choice",
             choices=["relative-margin", "fixed-margin", "custom"],
@@ -233,6 +246,7 @@ if __name__ == "__main__":
             default="", action="store", type="string",
             help="comma-separated x/y/z combination of the upper boundary " \
             + "(e.g. '12,5.5,0')")
+    # support grid settings
     group_support_grid.add_option("", "--enable-support-grid",
             dest="support_grid_enabled", default=False, action="store_true",
             help="enable the support grid")
@@ -246,6 +260,15 @@ if __name__ == "__main__":
     group_support_grid.add_option("", "--support-grid-thickness",
             dest="support_grid_thickness", default=0.5, action="store",
             type="float", help="width of the support grid profile")
+    # external program settings
+    group_external_programs.add_option("", "--location-inkscape",
+            dest="external_program_inkscape", default="", action="store",
+            type="string", help="location of the Inkscape executable. " \
+            + "This program is required for importing SVG files.")
+    group_external_programs.add_option("", "--location-pstoedit",
+            dest="external_program_pstoedit", default="", action="store",
+            type="string", help="location of the PStoEdit executable. " \
+            + "This program is required for importing SVG files.")
     (opts, args) = parser.parse_args()
 
     if len(args) > 0:
@@ -253,6 +276,24 @@ if __name__ == "__main__":
     else:
         inputfile = None
 
+    if opts.quiet:
+        log.setLevel(logging.WARNING)
+
+    # show version and exit
+    if opts.show_version:
+        if opts.quiet:
+            # print only the bare version number
+            print VERSION
+        else:
+            print "PyCAM %s" % VERSION
+            print "Copyright (C) 2008-2010 Lode Leroy"
+            print "Copyright (C) 2010 Lars Kruse"
+            print
+            print "License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>."
+            print "This is free software: you are free to change and redistribute it."
+            print "There is NO WARRANTY, to the extent permitted by law."
+        sys.exit(0)
+
     if not opts.disable_psyco:
         try:
             import psyco