From ee019bf5f896912761d4b16516bf562f9ffe52da Mon Sep 17 00:00:00 2001 From: "Robert P. J. Day" Date: Mon, 13 Jan 2014 06:49:33 -0500 Subject: [PATCH] Grammatical cleanup to Tcl Scripting chapter of User's Guide Changes solely to the Tcl Scripting API chapter of the UG: * Some grammatical cleanup * Fix formatting issues (@example and @verbatim formatting) * Add references to missing OSes OpenBSD, NetBSD and eCos. Change-Id: I3ec1a192a0b1e0a207dceb76fd39008d01e287a5 Signed-off-by: Robert P. J. Day Reviewed-on: http://openocd.zylin.com/1872 Tested-by: jenkins Reviewed-by: Spencer Oliver --- doc/openocd.texi | 45 +++++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/doc/openocd.texi b/doc/openocd.texi index 4e29ccfc8..ea3db757e 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -8307,9 +8307,9 @@ if @option{INCLUDE_vTaskDelete} is defined during the build. @cindex Tcl scripts @section API rules -The commands are stateless. E.g. the telnet command line has a concept -of currently active target, the Tcl API proc's take this sort of state -information as an argument to each proc. +Tcl commands are stateless; e.g. the @command{telnet} command has +a concept of currently active target, the Tcl API proc's take this sort +of state information as an argument to each proc. There are three main types of return values: single value, name value pair list and lists. @@ -8317,38 +8317,44 @@ pair list and lists. Name value pair. The proc 'foo' below returns a name/value pair list. -@verbatim - - > set foo(me) Duane - > set foo(you) Oyvind - > set foo(mouse) Micky - > set foo(duck) Donald +@example +> set foo(me) Duane +> set foo(you) Oyvind +> set foo(mouse) Micky +> set foo(duck) Donald +@end example If one does this: - > set foo +@example +> set foo +@end example The result is: - me Duane you Oyvind mouse Micky duck Donald +@example +me Duane you Oyvind mouse Micky duck Donald +@end example Thus, to get the names of the associative array is easy: - foreach { name value } [set foo] { - puts "Name: $name, Value: $value" - } +@verbatim +foreach { name value } [set foo] { + puts "Name: $name, Value: $value" +} @end verbatim -Lists returned must be relatively small. Otherwise a range +Lists returned should be relatively small. Otherwise, a range should be passed in to the proc in question. @section Internal low-level Commands -By low-level, the intent is a human would not directly use these commands. +By "low-level," we mean commands that a human would typically not +invoke directly. -Low-level commands are (should be) prefixed with "ocd_", e.g. +Low-level commands are (should be) prefixed with "ocd_"; e.g. @command{ocd_flash_banks} -is the low level API upon which @command{flash banks} is implemented. +is the low-level API upon which @command{flash banks} is implemented. @itemize @bullet @item @b{mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}> @@ -8376,9 +8382,12 @@ holds one of the following values: @item @b{cygwin} Running under Cygwin @item @b{darwin} Darwin (Mac-OS) is the underlying operating sytem. @item @b{freebsd} Running under FreeBSD +@item @b{openbsd} Running under OpenBSD +@item @b{netbsd} Running under NetBSD @item @b{linux} Linux is the underlying operating sytem @item @b{mingw32} Running under MingW32 @item @b{winxx} Built using Microsoft Visual Studio +@item @b{ecos} Running under eCos @item @b{other} Unknown, none of the above. @end itemize