[PATCH 2/6] xml: documentation

[Theophile Ranquet]

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 | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/NEWS b/NEWS
index bb016bb..46d614c 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 7b900b2..f7892cd 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,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}).
+
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 that 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.
+
+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 @file{foo.tab.c} by default.  As a
+consequence, the XML output file is called @file{foo.xml}.
+
+Bison ships with a data/xslt directory, containing XSL Transformation files
+to apply to the XML file. Their names are non-ambiguous:
+
address@hidden @file
address@hidden 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}.
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 table
+
+Sample usage (requires @code{xsltproc}):
address@hidden
+$ bison -x input.y
address@hidden
+$ bison --print-datadir
+/usr/local/share/bison
address@hidden group
+$ xsltproc /usr/local/share/bison/xslt/xml2xhtml.xsl input.xml > input.html
address@hidden example
+
 @c ================================================= Tracing
 
 @node Tracing
-- 
1.7.11.4