[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 2/3] xml: documentation
From: |
Theophile Ranquet |
Subject: |
[PATCH 2/3] xml: documentation |
Date: |
Wed, 24 Oct 2012 12:13:57 +0000 |
The XML output combined with the XSL Transformations provided in data/ are
incredibly useful, they should be documented.
* doc/bison.texi: Here, add an Xml:: node.
---
doc/bison.texi | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 49 insertions(+)
diff --git a/doc/bison.texi b/doc/bison.texi
index 8f98aa5..d143cdf 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,50 @@ 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}).
+
address@hidden ================================================= XML
+
address@hidden Xml
address@hidden Visualizing your parser in multiple formats
address@hidden xml
+
+Bison supports two major report formats: textual output (
address@hidden) when invoked with option @option{--verbose}, and DOT
+(@pxref{Graphviz}) when invoked with option @option{--graph}. However, an other
+alternative is to output an XML file than may then be, with xsltproc, rendered
+as either a raw text format very similar to the verbose file, or as an HTML
+version of the same file, with clickable transitions, or even as a DOT version
+(which is, as of 2.6.2, a less exciting version than the one obtained with
address@hidden, but this is subject to change in future releases).
+
+The textual file is generated when the options @option{-x} or
address@hidden 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. Therefore, if
+the grammar file is @file{foo.y}, then the parser implementation file is called
address@hidden by default. As a consequence, the XML output file is called
address@hidden
+
+Bison ships with a data/xslt directory, containing XSL Transformation files
+to apply to the XML file. Their names are non-ambiguous:
+
address@hidden @bullet
address@hidden bison.xsl, imported by the three following files.
address@hidden xml2dot.xsl, used to output a legacy DOT version of the
automaton.
address@hidden xml2text.xsl, used to output a copy of the .output file.
address@hidden xml2xhtml.xsl, used to output an xhtml enhancement of the
.output file.
address@hidden itemize
+
+Sample usage (requires 'xsltproc'):
address@hidden
address@hidden
+ $ bison -x input.y
+ $ xsltproc data/xslt/xml2xhtml.xsl input.xml > input.html
address@hidden group
address@hidden example
+
@c ================================================= Tracing
@node Tracing
--
1.7.11.4