• Tom Lane's avatar
    Doc: introduce new layout for tables of functions and operators. · e894c618
    Tom Lane authored
    We've long fought with the draconian space limitations of our
    traditional table layout for describing SQL functions and operators.
    This commit introduces a new approach, though so far I've only applied
    it to a few of those tables.  The new way makes use of DocBook's support
    for different layouts in different rows of a table, and allows the
    descriptions and examples for a function or operator to run to several
    lines without as much ugliness and wasted space as before.
    
    The core layout concept is now
    
         Name              Signature
                          Description
                     Example     Example Result
    
    so 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 column
    have only one entry for all three rows.  (Actually, there could be
    four or more rows if you wanted to have more than one example, which
    is another thing that was painful before but works easily now.)
    This is handled by a "morerows" annotation on the name entry, which
    isn't perfect (notably, the toolchain is not smart enough to avoid
    breaking these row groups across PDF pages) but there seems no better
    solution in DocBook.  The name column is normally fairly narrow,
    allowing plenty of space for the other column(s), and not wasting too
    much space when one of the other components runs to multiple lines.
    
    The varying row layout is managed by defining named "spans" and then
    tagging entries with a "spanname" of "name", "sig", "desc", "example",
    or "exresult".  This provides a bit of semantic annotation to go with
    the formatting improvement, which seems like a good thing.  (It seems
    that we have to re-define these spans afresh for each table, which is
    annoying, but it's not any worse than the duplication involved in
    the table headers.  At least that gives us an opportunity to vary the
    relative column widths per-table, which is handy since function tables
    sometimes 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 type
    name.  (I'll document that convention in a user-visible place later.)
    
    While this provides significantly more horizontal space than before
    for examples, it's still true that PDF output is a lot narrower than
    typical webpage viewing windows, so some examples need to be broken
    in places where there is no whitespace.  I've added &zwsp; markers in
    suitable 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 chosen
    to provide a reasonable sample of the formatting problems that need
    to be solved.  Assuming that this looks good on the website and doesn't
    provoke howls of anguish, I'll work on the other similar tables in the
    near future.
    
    There's a moderate amount of new editorial content in this patch along
    with the raw formatting changes; for instance I had to write text
    descriptions for operators that lacked them.  I failed to resist the
    temptation to improve some other descriptions and examples, too.
    
    Patch by me, with thanks to Alexander Lakhin for assistance with
    figuring out some formatting issues.
    
    Discussion: https://postgr.es/m/9326.1581457869@sss.pgh.pa.us
    e894c618
stylesheet-fo.xsl 3.82 KB