[Buildbot-commits] buildbot/docs buildbot.texinfo,1.48,1.49

[Brian Warner]

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

Modified Files:
	buildbot.texinfo 
Log Message:
Revision: arch at buildbot.sf.net--2004/buildbot--dev--0--patch-567
Creator:  Brian Warner <warner at lothar.com>

update some docs

	* docs/buildbot.texinfo (Build Properties): explain the syntax of
	property interpolation better

	* README (INSTALLATION): remove old '-v' argument from recommended
	trial command line

	* docs/buildbot.texinfo (ShellCommand): add docs for description=
	and descriptionDone= arguments. Thanks to Niklaus Giger for the
	patch. SF#1475494.


Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -d -r1.48 -r1.49
--- buildbot.texinfo	21 May 2006 21:28:26 -0000	1.48
+++ buildbot.texinfo	23 May 2006 11:46:21 -0000	1.49
@@ -3001,6 +3001,21 @@
 @item timeout
 if the command fails to produce any output for this many seconds, it
 is assumed to be locked up and will be killed.
+
+ at 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''.
+
+ at item descriptionDone
+This will be used to describe the command once it has finished. A
+simple noun like ``compile'' or ``tests'' should be used.
+
+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.
+
 @end table
 
 @node Simple ShellCommand Subclasses,  , ShellCommand, Build Steps
@@ -3090,7 +3105,7 @@
 arbitrary at footnote{Build properties are serialized along with the
 build results, so they must be serializable. For this reason, the
 value of any build property should be simple inert data: strings,
-numbers, lists, tuples, and dictionaries. They should not include
+numbers, lists, tuples, and dictionaries. They should not contain
 class instances.} object. For example:
 
 @example
@@ -3124,9 +3139,15 @@
 
 The @code{WithProperties} function does @code{printf}-style string
 interpolation, using strings obtained by calling
- at code{build.getProperty(propname)}. You can also use python
-dictionary-style string interpolation by using the @code{%(propname)s}
-syntax:
+ at code{build.getProperty(propname)}. Note that for every @code{%s} (or
+ at code{%d}, etc), you must have exactly one additional argument to
+indicate which build property you want to insert.
+
+
+You can also use python dictionary-style string interpolation by using
+the @code{%(propname)s} syntax. In this form, the property name goes
+in the parentheses, and WithProperties takes @emph{no} additional
+arguments:
 
 @example
 s(ShellCommand,
@@ -3136,6 +3157,9 @@
  )
 @end example
 
+Don't forget the extra ``s'' after the closing parenthesis! This is
+the cause of many confusing errors.
+
 Note that, like python, you can either do positional-argument
 interpolation @emph{or} keyword-argument interpolation, not both. Thus
 you cannot use a string like