From 804c0b2ad321247e50910511f691d987d8141081 Mon Sep 17 00:00:00 2001
From: David Brownell <dbrownell@users.sourceforge.net>
Date: Thu, 28 Jan 2010 14:03:29 -0800
Subject: [PATCH] doc clarifications for server flags

The "-f" is a shortcut for "-c" ... and providing any "-c" options
means the "openocd.cfg" file isn't implicitly used.  Both the User's
Guide and the manual page were weak on these points, which has led
to some confusion.

Also update the manual page to include highlights of the search path
mechanism, including the facts that it exists and that "-s" adds to it.
Stop saying only the current directory is involved; the OpenOCD
script library is quite significant.

(Missing: complete manpage coverage of the search path, including a
FILES section listing all components and saying where the script
library is found.)

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
---
 doc/openocd.1    | 30 +++++++++++++++++++-----------
 doc/openocd.texi |  7 ++++---
 2 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/doc/openocd.1 b/doc/openocd.1
index 68b695738..3720d4264 100644
--- a/doc/openocd.1
+++ b/doc/openocd.1
@@ -22,19 +22,23 @@ please check the \fIopenocd\fR info page for the complete list.
 .SH "OPTIONS"
 .TP
 .B "\-f, \-\-file <filename>"
-Use configuration file
-.BR <filename> .
+This is a shortcut for a \fB\-c "[script \fI<filename>\fB]"\fR
+command, using a search path to load the configuration file
+.IR <filename> .
 In order to specify multiple config files, you can use multiple
 .B \-\-file
-arguments. If this option is omitted, the config file
+arguments. If no such \fB\-c\fR
+options are included, the first config file
 .B openocd.cfg
-in the current working directory will be used.
+in the search path will be used.
 .TP
 .B "\-s, \-\-search <dirname>"
-Search for config files and scripts in the directory
-.BR <dirname> .
-If this option is omitted, OpenOCD searches for config files and scripts
-in the current directory.
+Add
+.I <dirname>
+to the search path used for config files and scripts.
+The search path begins with the current directory,
+then includes these additional directories before other
+components such as the standard OpenOCD script libraries.
 .TP
 .B "\-d, \-\-debug <debuglevel>"
 Set debug level. Possible values are:
@@ -52,13 +56,17 @@ The default level is
 .TP
 .B "\-l, \-\-log_output <filename>"
 Redirect log output to the file
-.BR <filename> .
+.IR <filename> .
 Per default the log output is printed on
 .BR stderr .
 .TP
 .B "\-c, \-\-command <cmd>"
-Run the command
-.BR <cmd> .
+Add the command
+.I <cmd>
+to a list of commands executed on server startup.
+Note that you will need to explicitly invoke
+.I init
+if the command requires access to a target or flash.
 .TP
 .B "\-p, \-\-pipe"
 Use pipes when talking to gdb.
diff --git a/doc/openocd.texi b/doc/openocd.texi
index ee5c723d0..38fa92f62 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -513,9 +513,10 @@ bash$ openocd --help
 --pipe       | -p       use pipes when talking to gdb
 @end verbatim
 
-By default OpenOCD reads the configuration file @file{openocd.cfg}.
-To specify a different (or multiple)
-configuration file, you can use the @option{-f} option. For example:
+If you don't give any @option{-f} or @option{-c} options,
+OpenOCD tries to read the configuration file @file{openocd.cfg}.
+To specify one or more different
+configuration files, use @option{-f} options. For example:
 
 @example
 openocd -f config1.cfg -f config2.cfg -f config3.cfg