Improve documentation for breakpoint builtin

darcs-hash:20070921151654-75c98-550df5aebaa11855c53585202ab7fafe7c5820ad.gz

builtin.c

@@ -3431,7 +3431,7 @@ const static builtin_data_t builtin_data[]=
 	}
 	,
 	{
-		L"breakpoint",  &builtin_breakpoint, N_( L"Temporarily halt execution and launch a new prompt" )  
+		L"breakpoint",  &builtin_breakpoint, N_( L"Temporarily halt execution of a script and launch an interactive debug prompt" )  
 	}
 	,
 

doc_src/breakpoint.txt

@@ -0,0 +1,10 @@
+\section breakpoint breakpoint - Launch debug mode
+
+\subsection breakpoint-synopsis Synopsis
+ <tt>breakpoint</tt>
+
+\subsection breakpoint-description Description
+
+The \c breakpoint builtin is used to halt a running script and launch
+an interactive debug prompt.
+

doc_src/index.hdr.in

@@ -1283,6 +1283,20 @@ For more information on how to define new event handlers, see the
 documentation for the <a href='commands.html#function'>function</a>
 command.
 
+\subsection debuging Debuging fish scripts
+
+Fish includes a built in debuger. The debuger allows you to stop
+execution of a script at an arbitrary point and launch a prompt. This
+prompt can then be used to check or change the value of any variables
+or perform any shellscript command. To resume normal execution of the
+script, simply exit the prompt.
+
+To start the debugger, simply call the builtin command
+'breakpoint'. The default action of the TRAP signal is to call this
+builtin, so a running script can be debuged by sending it the TRAP
+signal. Once in the debuger, it is easy to insert new breakpoints by
+using the funced function to edit the definition of a function.
+
 \section issues Common issues with fish
 
 If you install fish in your home directory, fish will not work