Merge remote-tracking branch 'origin/maint'

[bison.git] / doc / bison.texi

diff --git a/doc/bison.texi b/doc/bison.texi
index 9b7b14fd2eac5c165a13d774a013e886f43c5fd0..6a35422b6d24ec32b67e237bf2362b3a8326b47a 100644 (file)
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -299,6 +299,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
@@ -8426,6 +8427,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
 
@@ -8842,6 +8844,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
@@ -8949,6 +8954,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