From 92b8381c725911cd016e6b87ca5b2f309ceb1865 Mon Sep 17 00:00:00 2001
From: thurston <thurston@052ea7fc-9027-0410-9066-f65837a77df0>
Date: Sun, 22 Mar 2009 15:50:51 +0000
Subject: [PATCH] Documented: 	write start; 	write first_final; 	and
 write error;

git-svn-id: http://svn.complang.org/ragel/trunk@754 052ea7fc-9027-0410-9066-f65837a77df0
---
 doc/ragel-guide.tex | 38 +++++++++++++++++++++++++++++++++-----
 1 file changed, 33 insertions(+), 5 deletions(-)

diff --git a/doc/ragel-guide.tex b/doc/ragel-guide.tex
index 5816eb5..4cca738 100644
--- a/doc/ragel-guide.tex
+++ b/doc/ragel-guide.tex
@@ -2745,11 +2745,10 @@ write <component> [options];
 \end{verbatim}
 \verbspace
 
-
 The write statement is used to generate parts of the machine. 
-There are four
-components that can be generated by a write statement. These components are the
-state machine's data, initialization code, execution code, and exports.
+There are seven
+components that can be generated by a write statement. These components make up the
+state machine's data, initialization code, execution code, and export definitions.
 A write statement may appear before a machine is fully defined.
 This allows one to write out the data first then later define the machine where
 it is used. An example of this is shown in Figure \ref{fbreak-example}.
@@ -2826,6 +2825,35 @@ processing a string.}
 \label{fbreak-example}
 \end{figure}
 
+\subsection{Write Start, First Final and Error}
+
+\begin{verbatim}
+write start;
+write first_final;
+write error;
+\end{verbatim}
+\verbspace
+
+These three write statements provide an alternative means of accessing the
+\verb|start|, \verb|first_final| and \verb|error| states. If there are many
+different machine specifications in one file it is easy to get the prefix for
+these wrong. This is especially true if the state machine boilerplate is
+frequently made by a copy-paste-edit process. These write statements allow the
+problem to be avoided. They can be used as follows:
+
+\verbspace
+
+{
+\small
+\begin{verbatim}
+/* Did parsing succeed? */
+if ( cs < %%{ write first_final; }%% ) {
+    result = ERR_PARSE_ERROR;
+    goto fail;
+}
+\end{verbatim}
+}
+  
 
 \subsection{Write Init}
 \begin{verbatim}
@@ -2894,7 +2922,7 @@ When the write exports statement is used these machines are
 written out in the generated code. Defines are used for C and constant integers
 are used for D, Java and Ruby. See Section \ref{import} for a description of the
 import statement.
-  
+
 \section{Maintaining Pointers to Input Data}
 
 In the creation of any parser it is not uncommon to require the collection of
-- 
2.7.4