3 ms·
I'd say I tend to ignore the standard docs because they rarely have examples and rely on the arcane procedure of trying to decipher the super command options wi
by cyanydeez 2y ago
I'd say I tend to ignore the standard docs because they rarely have examples and rely on the arcane procedure of trying to decipher the super command options with all it's "[OR THIS|THAT]".
I assume _someone_ can read this pseudo programming, but it's not me.
- Clubber 2y agoFWIW square brackets indicate an optional parameter and the pipe inside indicates all the parameters available; but I agree, I don't particularly care for that notation and prefer actual running SQL examples.
- hobs 2y agoRailroad-esque diagrams can be weird but they say a lot in a very short space, I would highly recommend spending a little extra time working on thinking through them, they are everywhere!
- Clubber 2y ago>Railroad-esque diagrams Now and forever I will think of railroads when I see these.
- hobs 2y agoWell, you should! But, I didn't invent anything there, that's what they are named :) Syntax diagrams (or railroad diagrams) are a way to represent a context-free grammar. They represent a graphical alternative to Backus–Naur form, EBNF, Augmented Backus–Naur form, and other text-based grammars as metalanguages... https://en.wikipedia.org/wiki/Syntax_diagram https://en.wikipedia.org/wiki/Syntax_diagram
- paulryanrogers 2y agoSometimes I find it annoying but mostly it works well for me. I've come to embrace the find feature and visually scanning over any parenthetical stuff. The alternative is they have to break it up into several quasi examples, each with their own optional modifiers.
- PhilippGille 2y agoI love the diagrams from the SQLite documentation: https://www.sqlite.org/syntaxdiagrams.html https://www.sqlite.org/syntaxdiagrams.html
- christophilus 2y agoSQLite diagrams plus examples are pretty much the way I wish all of my documentation worked.
- o11c 2y agoI've been bitten by those before because they are not generated from the actual syntax-parsing code, and thus are sometimes out of sync and wrong (or at least misleading).
- teddyh 2y agoThose are commonly called “railroad diagrams”: <https://en.wikipedia.org/w/index.php?title=Syntax_diagram&oldid=1193243767 https://en.wikipedia.org/w/index.php?title=Syntax_diagram&ol...>
- assbuttbuttass 2y agoI'm looking at the postgres docs now, and they certainly have the arcane formal syntax definitions, but they also have plenty of useful examples https://www.postgresql.org/docs/current/sql-altertable.html#id-1.9.3.35.8 https://www.postgresql.org/docs/current/sql-altertable.html#...
- smartbit 2y agoPostgreSQL Administration Cookbook series served me well https://www.oreilly.com/library/view/postgresql-16-administration/9781835460580/ https://www.oreilly.com/library/view/postgresql-16-administr...
- mustime 2y ago[dead]