From 9c16d39944f2083dde29e364c1f61aebae6f2643 Mon Sep 17 00:00:00 2001 From: Theophile Ranquet Date: Mon, 22 Oct 2012 17:37:57 +0000 Subject: [PATCH] xml: documentation The XML output combined with the XSL Transformations provided in data/ are incredibly useful, they should be documented. * doc/bison.texi (Xml): New node. --- NEWS | 7 ++++++- doc/bison.texi | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+), 1 deletion(-) diff --git a/NEWS b/NEWS index bb016bb3..46d614cf 100644 --- a/NEWS +++ b/NEWS @@ -42,7 +42,7 @@ GNU Bison NEWS position_type are deprecated in favor of api.location.type and api.position.type. -** Graphviz improvements +** Graph improvements in DOT and XSLT The graphical presentation of the states is more readable: their shape is now rectangular, the state number is clearly displayed, and the items are @@ -51,6 +51,11 @@ GNU Bison NEWS The reductions are now explicitly represented as transitions to other diamond shaped nodes. + These changes are present in both --graph output and xml2dot.xsl XSLT + processing, with minor (documented) differences. + + Two nodes were added to the documentation: Xml and Graphviz. + * Noteworthy changes in release 2.6.5 (2012-11-07) [stable] We consider compiler warnings about Bison generated parsers to be bugs. diff --git a/doc/bison.texi b/doc/bison.texi index 7b900b27..023edd51 100644 --- 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 @@ -8618,6 +8623,55 @@ 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 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 DOT version of the automaton. This might not be exactly the +same as the one obtained through @option{--graph}. +@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 -- 2.45.2