[Buildbot-commits] buildbot/docs buildbot.texinfo,1.68,1.69

[Brian Warner]

Update of /cvsroot/buildbot/buildbot/docs
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv4503/docs

Modified Files:
	buildbot.texinfo 
Log Message:
[project @ accept either a single string or a list for ShellCommand description=]
This fixes SF#1524659, thanks to Paul Winkler for the catch.

Original author: warner at lothar.com
Date: 2006-08-21 00:38:00

Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.68
retrieving revision 1.69
diff -u -d -r1.68 -r1.69
--- buildbot.texinfo	20 Aug 2006 22:25:35 -0000	1.68
+++ buildbot.texinfo	21 Aug 2006 00:43:20 -0000	1.69
@@ -3389,7 +3389,12 @@
 @table @code
 @item command
 a list of strings (preferred) or single string (discouraged) which
-specifies the command to be run
+specifies the command to be run. A list of strings is preferred
+because it can be used directly as an argv array. Using a single
+string (with embedded spaces) requires the buildslave to pass the
+string to /bin/sh for interpretation, which raises all sorts of
+difficult questions about how to escape or interpret shell
+metacharacters.
 
 @item env
 a dictionary of environment strings which will be added to the child
@@ -3455,17 +3460,28 @@
 @item description
 This will be used to describe the command (on the Waterfall display)
 while the command is still running. It should be a single
-imperfect-tense verb, like ``compiling'' or ``testing''.
+imperfect-tense verb, like ``compiling'' or ``testing''. The preferred
+form is a list of short strings, which allows the HTML Waterfall
+display to create narrower columns by emitting a <br> tag between each
+word. You may also provide a single string.
 
 @item descriptionDone
 This will be used to describe the command once it has finished. A
-simple noun like ``compile'' or ``tests'' should be used.
+simple noun like ``compile'' or ``tests'' should be used. Like
+ at code{description}, this may either be a list of short strings or a
+single string.
 
 If neither @code{description} nor @code{descriptionDone} are set, the
 actual command arguments will be used to construct the description.
 This may be a bit too wide to fit comfortably on the Waterfall
 display.
 
+ at example
+f.addStep(ShellCommand, command=["make", "test"],
+          description=["testing"],
+          descriptionDone=["tests"])
+ at end example
+
 @end table
 
 @node Simple ShellCommand Subclasses, Writing New BuildSteps, ShellCommand, Build Steps