forked frompostgres/postgres
- Notifications
You must be signed in to change notification settings - Fork6
Commite894c61
committed
Doc: introduce new layout for tables of functions and operators.
We've long fought with the draconian space limitations of ourtraditional table layout for describing SQL functions and operators.This commit introduces a new approach, though so far I've only appliedit to a few of those tables. The new way makes use of DocBook's supportfor different layouts in different rows of a table, and allows thedescriptions and examples for a function or operator to run to severallines without as much ugliness and wasted space as before.The core layout concept is now Name Signature Description Example Example Resultso that a function or operator really has three table rows not one,but we group them to look like one row by having the name columnhave only one entry for all three rows. (Actually, there could befour or more rows if you wanted to have more than one example, whichis another thing that was painful before but works easily now.)This is handled by a "morerows" annotation on the name entry, whichisn't perfect (notably, the toolchain is not smart enough to avoidbreaking these row groups across PDF pages) but there seems no bettersolution in DocBook. The name column is normally fairly narrow,allowing plenty of space for the other column(s), and not wasting toomuch space when one of the other components runs to multiple lines.The varying row layout is managed by defining named "spans" and thentagging entries with a "spanname" of "name", "sig", "desc", "example",or "exresult". This provides a bit of semantic annotation to go withthe formatting improvement, which seems like a good thing. (It seemsthat we have to re-define these spans afresh for each table, which isannoying, but it's not any worse than the duplication involved inthe table headers. At least that gives us an opportunity to vary therelative column widths per-table, which is handy since function tablessometimes need much wider name columns than operator tables.)Signature entries should be written in the style <function>fname</function>(<type>typename</type> ...) <returnvalue>typename</returnvalue>The <returnvalue> tag produces a right arrow before the result typename. (I'll document that convention in a user-visible place later.)While this provides significantly more horizontal space than beforefor examples, it's still true that PDF output is a lot narrower thantypical webpage viewing windows, so some examples need to be brokenin places where there is no whitespace. I've added &zwsp; markers insuitable places to allow the tables to render warning-free in PDF.I've so far converted only the date/time operator, date/time function,and enum function tables in sections 9.9 and 9.10; these were chosento provide a reasonable sample of the formatting problems that needto be solved. Assuming that this looks good on the website and doesn'tprovoke howls of anguish, I'll work on the other similar tables in thenear future.There's a moderate amount of new editorial content in this patch alongwith the raw formatting changes; for instance I had to write textdescriptions for operators that lacked them. I failed to resist thetemptation to improve some other descriptions and examples, too.Patch by me, with thanks to Alexander Lakhin for assistance withfiguring out some formatting issues.Discussion:https://postgr.es/m/9326.1581457869@sss.pgh.pa.us1 parent88d934f commite894c61
File tree
3 files changed
+711
-330
lines changed- doc/src/sgml
3 files changed
+711
-330
lines changed0 commit comments
Comments
(0)