xml: match DOT output and xml2dot.xsl processing

[bison.git] / doc / bison.texi

diff --git a/doc/bison.texi b/doc/bison.texi
index 8f98aa5e421744eb0f9089a148a2200a5f6120b3..7bb41460f8f44bcad7807a7fa287139cd2e13ebc 100644 (file)
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -295,6 +295,7 @@ Debugging Your Parser
 
 * Understanding::     Understanding the structure of your parser.
 * Graphviz::          Getting a visual representation of the parser.
+* Xml::               Getting a markup representation of the parser.
 * Tracing::           Tracing the execution of your parser.
 
 Tracing Your Parser
@@ -8095,6 +8096,7 @@ automaton, and how to enable and understand the parser run-time traces.
 @menu
 * Understanding::     Understanding the structure of your parser.
 * Graphviz::          Getting a visual representation of the parser.
+* Xml::               Getting a markup representation of the parser.
 * Tracing::           Tracing the execution of your parser.
 @end menu
 
@@ -8511,6 +8513,9 @@ precedence of @samp{/} with respect to @samp{+}, @samp{-}, and
 @samp{*}, but also because the
 associativity of @samp{/} is not specified.
 
+Note that Bison may also produce an HTML version of this output, via an XML
+file and XSLT processing (@pxref{Xml}).
+
 @c ================================================= Graphical Representation
 
 @node Graphviz
@@ -8525,8 +8530,8 @@ a PDF or PNG file from it will take very long, and more often than not it will
 fail due to memory exhaustion). This option was rather designed for beginners,
 to help them understand LR parsers.
 
-This file is generated when the @option{--graph} option is specified (see
-@pxref{Invocation, , Invoking Bison}).  Its name is made by removing
+This file is generated when the @option{--graph} option is specified
+(@pxref{Invocation, , Invoking Bison}).  Its name is made by removing
 @samp{.tab.c} or @samp{.c} from the parser implementation file name, and
 adding @samp{.dot} instead.  If the grammar file is @file{foo.y}, the
 Graphviz output file is called @file{foo.dot}.
@@ -8618,6 +8623,54 @@ is shown as a blue diamond, labelled "Acc".
 The @samp{go to} jump transitions are represented as dotted lines bearing
 the name of the rule being jumped to.
 
+Note that a DOT file may also be produced via an XML file and XSLT
+processing (@pxref{Xml}).
+
+@c ================================================= XML
+
+@node Xml
+@section Visualizing your parser in multiple formats
+@cindex xml
+
+Bison supports two major report formats: textual output
+(@pxref{Understanding}) when invoked with option @option{--verbose}, and DOT
+(@pxref{Graphviz}) when invoked with option @option{--graph}. However,
+another alternative is to output an XML file that may then be, with
+@command{xsltproc}, rendered as either a raw text format equivalent to the
+verbose file, or as an HTML version of the same file, with clickable
+transitions, or even as a DOT. The @file{.output} and DOT files obtained via
+XSLT have no difference whatsoever with those obtained by invoking
+@command{bison} with options @option{--verbose} or @option{--graph}.
+
+The textual file is generated when the options @option{-x} or
+@option{--xml[=FILE]} are specified, see @ref{Invocation,,Invoking Bison}.
+If not specified, its name is made by removing @samp{.tab.c} or @samp{.c}
+from the parser implementation file name, and adding @samp{.xml} instead.
+For instance, if the grammar file is @file{foo.y}, the default XML output
+file is @file{foo.xml}.
+
+Bison ships with a @file{data/xslt} directory, containing XSL Transformation
+files to apply to the XML file. Their names are non-ambiguous:
+
+@table @file
+@item xml2dot.xsl
+Used to output a copy of the DOT visualization of the automaton.
+@item xml2text.xsl
+Used to output a copy of the .output file.
+@item xml2xhtml.xsl
+Used to output an xhtml enhancement of the .output file.
+@end table
+
+Sample usage (requires @code{xsltproc}):
+@example
+$ bison -x input.y
+@group
+$ bison --print-datadir
+/usr/local/share/bison
+@end group
+$ xsltproc /usr/local/share/bison/xslt/xml2xhtml.xsl input.xml > input.html
+@end example
+
 @c ================================================= Tracing
 
 @node Tracing