Re: [PATCH 2/3] xml: documentation

[Akim Demaille]

Le 24 oct. 2012 à 14:13, Theophile Ranquet a écrit :

> 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 (Xml): New 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

Please, fix the wrapping above.  Make this 76 cols, no more.

> +(@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

s/than/that/

> +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).

Forget about such details, imho: s/\(.*?\)//.

> +
> +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

Would @description make more sense?

> address@hidden bison.xsl, imported by the three following files.

I don't think you should mention it.

> 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'):

requires \code{xsltproc}

> address@hidden
> address@hidden
> +  $ bison -x input.y
> +  $ xsltproc data/xslt/xml2xhtml.xsl input.xml > input.html
> address@hidden group
> address@hidden example

This is incomplete: you must refer to --print-data-dir.  And please,
don't indent inside @example.  The @group is also, imho, useless.

> +
> @c ================================================= Tracing
> 
> @node Tracing
> -- 
> 1.7.11.4

You should mention in NEWS that the documentation features a
new section.