Thread: Syntax diagrams in user documentation
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 don't think that it's necessary to discuss this now. This can be a placeholder thread that we may come back to when we're all less busy. -- Peter Geoghegan
On 2019-Mar-28, 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 Interesting. SQLite itself is in the public domain, so it's not totally unreasonable to borrow this code ... -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Thu, 28 Mar 2019 at 17:56, Peter Geoghegan <pg@bowt.ie> 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
neato!
(And no coincidence that GraphViz has a command by that name... https://www.graphviz.org/pdf/neatoguide.pdf)
An especially cool idea if we could automatically dig input directly from src/backend/parser/gram.y
When confronted by a difficult problem, solve it by reducing it to the
question, "How would the Lone Ranger handle this?"
question, "How would the Lone Ranger handle this?"
On 3/28/19 14:56, Peter Geoghegan wrote: > SQLite has a bubble generator tool that they use to generate syntax > diagrams for their documentation: > > ... > > I don't think that it's necessary to discuss this now. This can be a > placeholder thread that we may come back to when we're all less busy. We're just gearing up for the Google Season of Docs and I think this would be a great task for a doc writer to help with. Any reason to expect serious objections to syntax diagram graphics in the docs? (Peter E, I did notice that you just added the idea of more images to the GSoD wiki.) -Jeremy -- Jeremy Schneider Database Engineer Amazon Web Services
On Thu, Mar 28, 2019 at 3:46 PM Jeremy Schneider <schnjere@amazon.com> wrote: > We're just gearing up for the Google Season of Docs and I think this > would be a great task for a doc writer to help with. Any reason to > expect serious objections to syntax diagram graphics in the docs? It might be hard to come to a consensus, because it's one of those things that everybody can be expected to have an opinion on. It probably won't be hard to get something committed that's clearly more informative than what we have right now, though. There is a question about how we maintain consistency between the syntax diagrams in psql if we go this way, though. Not sure what to do about that. -- Peter Geoghegan
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
On Thu, Mar 28, 2019 at 6:49 PM Peter Geoghegan <pg@bowt.ie> wrote:
On Thu, Mar 28, 2019 at 3:46 PM Jeremy Schneider <schnjere@amazon.com> wrote:
> We're just gearing up for the Google Season of Docs and I think this
> would be a great task for a doc writer to help with. Any reason to
> expect serious objections to syntax diagram graphics in the docs?
It might be hard to come to a consensus, because it's one of those
things that everybody can be expected to have an opinion on. It
probably won't be hard to get something committed that's clearly more
informative than what we have right now, though.
There is a question about how we maintain consistency between the
syntax diagrams in psql if we go this way, though. Not sure what to do
about that.
This discussion is highly relevant to an upcoming talk I have called "In Aid Of RTFM", and the work I hope would follow from it.
While I personally like these bubble charts because they remind me of my misspent youth at IBM, they have some drawbacks:
1. They look like something out of an IBM manual
2. Images conceal information from visually impaired people
3. They aren't copy paste-able text
4. They aren't easily comparable
5. They bake in the language of the comments
The merits of #1 can be argued forever, and it's possible that a more modern bubble chart theme is possible.
#2 is problematic, because things like ADA compliance and the EU Accessibility Requirements frown upon conveying text inside images. The way around this might be to have the alt-text of the image be the original syntax as we have it now.
#3 is important when attempting to relay the relevant excerpt of a very large documentation page via email or slack. Yes, I could right click and copy the URL of the image (in this case https://www.sqlite.org/images/syntax/insert-stmt.gif and others), but that's more work that copy-paste. We could add an HTML anchor to each image (my talk discusses our current lack of reference anchors) and that would mitigate it somewhat. Making the original text available via mouse-over or a "copy text" link might work too.
#3b As long as I live, I will never properly memorize the syntax for RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW. I will google this and copy-paste it. I suspect I'm not alone. If it's available only in an image, then I can't copy paste, and I will mistype some part of that at least twice.
#4 isn't such an immediate issue, but one of my points in the talk is that right now there is no way to easily distinguish text on a page that is new in the most recent version of pgsql (i.e. a red-line markup). We could of course flag that an image changed from version X-1 to X, but it would be tougher to convey which parts of the image changed.
#5 it not such a big issue because most of what is in the diagram is pure syntax, but comments will leak in, and those snippets of English will be buried very deep in bubble-markup.
Christopher Browne <cbbrowne@gmail.com> writes:
> An especially cool idea if we could automatically dig input directly from
> src/backend/parser/gram.y
FWIW, I think the odds of getting desirable diagrams that way are nil.
There are *way* too many things about our Bison grammar that can
be described charitably as implementation details, or uncharitably
as ugly hacks.
It may or may not be useful to present the grammar as railroad
diagrams or the like; but I think we need to expect that that'd be
an abstraction of the syntax, not something that can be automatically
reverse-engineered from the implementation.
It might be more useful to try to generate pretty pictures from
the SGML^H^H^H^HXML docs' <synopsis> sections.
regards, tom lane
On 2019-03-29 03:53, Corey Huinker wrote: > #3b As long as I live, I will never properly memorize the syntax for > RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW. I will google this > and copy-paste it. I suspect I'm not alone. If it's available only in an > image, then I can't copy paste, and I /will/ mistype some part of that > at least twice. I doubt that we would remove the current textual synopses. The graphics would just be an addition. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On 2019-03-28 23:45, Jeremy Schneider wrote: > We're just gearing up for the Google Season of Docs and I think this > would be a great task for a doc writer to help with. Any reason to > expect serious objections to syntax diagram graphics in the docs? It's worth a thought, but I tend to think that this would not be a good task for a "technical writer". It's either an automation task or busywork transcribing the syntax to whatever new intermediate format. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services