Re: Syntax diagrams in user documentation

On 03/28/19 17:56, Peter Geoghegan wrote:
> SQLite has a bubble generator tool that they use to generate syntax
> diagrams for their documentation:
>
> https://www.sqlite.org/docsrc/doc/tip/art/syntax/bubble-generator.tcl?mimetype=text/plain
>
> I think that the results are rather good. See, for example, the INSERT
> documentation:
>
> https://www.sqlite.org/lang_insert.html
>
> Now that we have infrastructure that can add images to our
> documentation, we may want to consider something like this. Note that
> Bison has an option that outputs a grammar as a Graphviz dot file:
>
> https://www.gnu.org/software/bison/manual/html_node/Graphviz.html
>
> It's probably not possible to create a useful visualization/syntax
> diagram with Bison's --graph option, but it might at least be an
> interesting starting point.

I did a thing at $work where a query from pg_authid and pg_auth_members
produces an XML file with elements for roles and elements for grant arcs,
an XSL transform from that into Graphviz language, transformed into SVG
by Viz.js (which is graphviz turned into javascript by Emscripten,
running right in the browser and making SVG).

SVG itself, being XML, is amenable to further XSL transforms too, so
there are several places it should be possible to intervene and filter/
tweak the output.

A quick glance at the bison --graph option makes me think it creates
a giant impractical dot file of the whole grammar at once. I'm thinking
it would be more practical to use the --xml option to get the output
instead in a form that XSLT can pull individual productions from in
isolation and produce dot (or svg) from those.

I'm guessing the biggest automation challenges will be about where to
break and wrap things.

-Chap