David Brownell <david-b@pacbell.net>:

Various updates, mostly small/formatting changes:

 * Small content tweaks:
    - Re-title:  "OpenOCD User's Guide".
    - For users, URLS for latest doc and SparkFun forum
    - Mention GIT-SVN
 * Fix some front-matter goofage, matching texinfo docs:
    - "paragraphintent" location matters
    - put release version/date description with the copyright
 * Fix some other stuff matching texinfo docs:
    - no tabs
    - tweak some refs and anchors
 * whitespace-at-end-o-line fixes


git-svn-id: svn://svn.berlios.de/openocd/trunk@1975 b42882b7-edfa-0310-969c-e2dbd0fdcd60

doc/openocd.texi

@@ -1,18 +1,23 @@
-\input texinfo	@c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-
 @c %**start of header
 @setfilename openocd.info
-@settitle Open On-Chip Debugger (OpenOCD)
+@settitle OpenOCD User's Guide
 @dircategory Development
 @direntry
-@paragraphindent 0
-* OpenOCD: (openocd).      Open On-Chip Debugger.
+* OpenOCD: (openocd).      OpenOCD User's Guide
 @end direntry
+@paragraphindent 0
 @c %**end of header
 
 @include version.texi
 
 @copying
 
+This User's Guide documents
+release @value{VERSION},
+dated @value{UPDATED},
+of the Open On-Chip Debugger (OpenOCD).
+
 @itemize @bullet
 @item Copyright @copyright{} 2008 The OpenOCD Project
 @item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
@@ -31,9 +36,12 @@ Free Documentation License''.
 @end copying
 
 @titlepage
-@title Open On-Chip Debugger (OpenOCD)
-@subtitle Edition @value{EDITION} for OpenOCD version @value{VERSION}
+@titlefont{@emph{Open On-Chip Debugger:}}
+@sp 1
+@title OpenOCD User's Guide
+@subtitle for release @value{VERSION}
 @subtitle @value{UPDATED}
+
 @page
 @vskip 0pt plus 1filll
 @insertcopying
@@ -42,13 +50,12 @@ Free Documentation License''.
 @summarycontents
 @contents
 
-@node Top, About, , (dir)
-@top OpenOCD
-
-This manual documents edition @value{EDITION} of the Open On-Chip Debugger
-(OpenOCD) version @value{VERSION}, @value{UPDATED}.
+@ifnottex
+@node Top
+@top OpenOCD User's Guide
 
 @insertcopying
+@end ifnottex
 
 @menu
 * About::                            About OpenOCD
@@ -77,6 +84,7 @@ This manual documents edition @value{EDITION} of the Open On-Chip Debugger
 * FAQ::                              Frequently Asked Questions
 * Tcl Crash Course::                 Tcl Crash Course
 * License::                          GNU Free Documentation License
+
 @comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
 @comment case issue with ``Index.html'' and ``index.html''
 @comment Occurs when creating ``--html --no-split'' output
@@ -125,6 +133,24 @@ The OpenOCD web site provides the latest public news from the community:
 
 @uref{http://openocd.berlios.de/web/}
 
+@section Latest User's Guide:
+
+The user's guide you are now reading may not be the latest one
+available.  A version for more recent code may be available.
+Its HTML form is published irregularly at:
+
+@uref{http://openocd.berlios.de/doc/}
+
+PDF form is likewise published at:
+
+@uref{http://openocd.berlios.de/doc/pdf/}
+
+@section OpenOCD User's Forum
+
+There is an OpenOCD forum (phpBB) hosted by SparkFun:
+
+@uref{http://forum.sparkfun.com/viewforum.php?f=18}
+
 
 @node Developers
 @chapter OpenOCD Developer Resources
@@ -167,12 +193,13 @@ listed in the Doxyfile configuration in the top of the repository trunk.
 The OpenOCD Developer Mailing List provides the primary means of
 communication between developers:
 
-	@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
+@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
 
 All drivers developers are enouraged to also subscribe to the list of
 SVN commits to keep pace with the ongoing changes:
 
-	@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
+@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
+
 
 @node Building OpenOCD
 @chapter Building OpenOCD
@@ -247,7 +274,14 @@ current directory):
  svn checkout svn://svn.berlios.de/openocd/trunk openocd
 @end example
 
-Building OpenOCD requires a recent version of the GNU autotools (autoconf >= 2.59 and automake >= 1.9).
+If you prefer GIT based tools, the @command{git-svn} package works too:
+
+@example
+ git svn clone -s svn://svn.berlios.de/openocd
+@end example
+
+Building OpenOCD from a repository requires a recent version of the
+GNU autotools (autoconf >= 2.59 and automake >= 1.9).
 For building on Windows,
 you have to use Cygwin. Make sure that your @env{PATH} environment variable contains no
 other locations with Unix utils (like UnxUtils) - these can't handle the Cygwin
@@ -1155,7 +1189,7 @@ can type a Tcl for() loop, set variables, etc.
 @* JIM-Tcl was introduced to OpenOCD in spring 2008.
 
 @item @b{Need a crash course in Tcl?}
-@* See: @xref{Tcl Crash Course}.
+@*@xref{Tcl Crash Course}.
 @end itemize
 
 @node Daemon Configuration
@@ -1232,8 +1266,8 @@ When not specified during the configuration stage,
 the port @var{number} defaults to 4444.
 @end deffn
 
-@section GDB Configuration
 @anchor{GDB Configuration}
+@section GDB Configuration
 @cindex GDB
 @cindex GDB configuration
 You can reconfigure some GDB behaviors if needed.
@@ -1241,8 +1275,8 @@ The ones listed here are static and global.
 @xref{Target Create}, about declaring individual targets.
 @xref{Target Events}, about configuring target-specific event handling.
 
-@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
 @anchor{gdb_breakpoint_override}
+@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
 Force breakpoint type for gdb @command{break} commands.
 The raison d'etre for this option is to support GDB GUI's which don't
 distinguish hard versus soft breakpoints, if the default OpenOCD and
@@ -1258,8 +1292,8 @@ Configures what OpenOCD will do when GDB detaches from the daemon.
 Default behaviour is @var{resume}.
 @end deffn
 
-@deffn {Config command} gdb_flash_program <enable|disable>
 @anchor{gdb_flash_program}
+@deffn {Config command} gdb_flash_program <enable|disable>
 Set to @var{enable} to cause OpenOCD to program the flash memory when a
 vFlash packet is received.
 The default behaviour is @var{enable}.
@@ -1508,8 +1542,8 @@ The OpenOCD default value is 2 and for some systems a value of 10 has proved use
 @cindex ep93xx options
 Currently, there are no options available for the ep93xx interface.
 
-@section JTAG Speed
 @anchor{JTAG Speed}
+@section JTAG Speed
 JTAG clock setup is part of system setup.
 It @emph{does not belong with interface setup} since any interface
 only knows a few of the constraints for the JTAG clock speed.
@@ -2120,9 +2154,9 @@ with odd reset situations and are not documented here.
 @* Invokes the specific event manually for the target
 @end itemize
 
+@anchor{Target Events}
 @section Target Events
 @cindex events
-@anchor{Target Events}
 At various times, certain things can happen, or you want them to happen.
 
 Examples:
@@ -2152,8 +2186,8 @@ creates and invokes small procedure. The second inlines the procedure.
    @}
    mychip.cpu configure -event gdb-attach my_attach_proc 
    mychip.cpu configure -event gdb-attach @{
-	   puts "Reset..."
-	   reset halt
+       puts "Reset..."
+       reset halt
    @}
 @end example
 
@@ -2243,8 +2277,8 @@ jtag configure DOTTED.NAME -event tap-disable @{
 @end example
 @end itemize
 
-@section Target Create
 @anchor{Target Create}
+@section Target Create
 @cindex target
 @cindex target creation
 
@@ -2455,8 +2489,7 @@ One feature distinguishing NOR flash from NAND or serial flash technologies
 is that for read access, it acts exactly like any other addressible memory.
 This means you can use normal memory read commands like @command{mdw} or
 @command{dump_image} with it, with no special @command{flash} subcommands.
-@xref{Memory access}.
-@xref{Image access}.
+@xref{Memory access}, and @ref{Image access}.
 
 Write access works differently.  Flash memory normally needs to be erased
 before it's written.  Erasing a sector turns all of its bits to ones, and
@@ -2570,8 +2603,8 @@ The @var{num} parameter is a value shown by @command{flash banks}.
 @comment @option{flash erase_sector} using the same syntax.
 @end deffn
 
-@section Flash Drivers, Options, and Commands
 @anchor{Flash Driver List}
+@section Flash Drivers, Options, and Commands
 As noted above, the @command{flash bank} command requires a driver name,
 and allows driver-specific options and behaviors.
 Some drivers also activate driver-specific commands.
@@ -3273,8 +3306,8 @@ bypassing hardware ECC logic.
 with the wrong ECC data can cause them to be marked as bad.
 @end deffn
 
-@section NAND Drivers, Options, and Commands
 @anchor{NAND Driver List}
+@section NAND Drivers, Options, and Commands
 As noted above, the @command{nand device} command allows
 driver-specific options and behaviors.
 Some controllers also activate controller-specific commands.
@@ -3376,9 +3409,9 @@ port is 5555.
 @cindex shutdown
 @*Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other). 
 
+@anchor{debug_level}
 @subsection debug_level [@var{n}]
 @cindex debug_level
-@anchor{debug_level}
 @*Display or adjust debug level to n<0-3> 
 
 @subsection fast [@var{enable|disable}]
@@ -3485,8 +3518,8 @@ the code that was executed may have left the hardware in an unknown
 state.
 
 
-@section Memory access commands
 @anchor{Memory access}
+@section Memory access commands
 @subsection meminfo
 display available RAM memory on OpenOCD host. Used in OpenOCD regression testing scripts. Mainly
 useful on embedded targets, PC type hosts have complimentary tools like Valgrind to address
@@ -3523,17 +3556,16 @@ SDRAM controller to enable SDRAM.
 @*write memory byte (8bit)
 @end itemize
 
-@section Image loading commands
 @anchor{Image access}
+@section Image loading commands
+@anchor{load_image}
 @subsection load_image
 @b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
 @cindex load_image
-@anchor{load_image}
 @*Load image <@var{file}> to target memory at <@var{address}> 
 @subsection fast_load_image
 @b{fast_load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
 @cindex fast_load_image
-@anchor{fast_load_image}
 @*Normally you should be using @b{load_image} or GDB load. However, for
 testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
 host), storing the image in memory and uploading the image to the target
@@ -3545,12 +3577,11 @@ separately.
 @subsection fast_load
 @b{fast_load}
 @cindex fast_image
-@anchor{fast_image}
 @*Loads an image stored in memory by @b{fast_load_image} to the current target. Must be preceeded by fast_load_image.
+@anchor{dump_image}
 @subsection dump_image
 @b{dump_image} <@var{file}> <@var{address}> <@var{size}>
 @cindex dump_image
-@anchor{dump_image}
 @*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
 (binary) <@var{file}>.
 @subsection verify_image
@@ -4299,9 +4330,9 @@ openocd -f interface/parport.cfg -f target/at91r40008.cfg \
 OpenOCD complies with the remote gdbserver protocol, and as such can be used
 to debug remote targets.
 
+@anchor{Connecting to GDB}
 @section Connecting to GDB
 @cindex Connecting to GDB
-@anchor{Connecting to GDB}
 Use GDB 6.7 or newer with OpenOCD if you run into trouble. For
 instance GDB 6.3 has a known bug that produces bogus memory access
 errors, which has since been fixed: look up 1836 in
@@ -4555,8 +4586,8 @@ halt
 @chapter FAQ
 @cindex faq
 @enumerate
-@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
 @anchor{FAQ RTCK}
+@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
 @cindex RTCK
 @cindex adaptive clocking
 @*