Re: Getting our tables to render better in PDF output

Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> On 2020-Feb-12, Tom Lane wrote:
>> I also attached a screenshot of a segment of Table 9-31, to show
>> what that layout proposal looks like.  It's a little busier, but
>> it does have the advantage that it's clearer how to apply that
>> format to operator tables.  The "returns <type>" notation isn't used
>> anywhere in SQL for operators, so I am not in love with the idea of
>> writing the operator tables that way.

> Yeah, that's a little less obvious.  I just noticed that the operators
> tables show the operator names but not the input datatypes except in the
> examples.  Perhaps we could use a layout with a cell labelled
> "signature" (namest=col2 nameend=col3) instead of input types + return
> types and separate them using → which would look like this:
>    date + integer → date

Oh, that's a thought.  We could do the same for functions:

    function name           type1, type2, type3 → rettype
                            description ...
                            example         example result

which'd relieve the column-width pressure for functions with several
arguments.  On the other hand, that would look a little funny
for functions with no arguments ... not but what they're going to
look funny no matter what.  I used "none" in my conversion of
table 9.31, but wasn't satisfied with that, because it relies
completely on font choice to be distinguishable from a data type
named "none".  With a separate argument-types cell it'd likely be
better to just leave the cell empty, but do we want to write
just "→ rettype" in a signature cell?

The other thing I was struggling with was how to distinguish
normal zero-argument functions (written with parens) from those
SQL abominations that are function calls with no parens.  I think
we need to show that somehow, so that it's clear that the examples
are correct and not typos.  It doesn't have to be *totally* obvious,
perhaps, if we have an example to back it up ... but the example
can't be the only thing.

Maybe don't take out the parens?  So it'd work like

    Function               Signature

    age                    (timestamp) → interval

    now                    () → timestamp with time zone

    current_timestamp      → timestamp with time zone

Also, I think we're both imagining that we'd use the operator name
in operator signatures:

    Operator               Signature

    +                      integer + integer → integer

    +                      + integer → integer

so being consistent with that might suggest including the function name
in function signatures:

    Function               Signature

    age                    age(timestamp) → interval

    now                    now() → timestamp with time zone

    current_timestamp      current_timestamp → timestamp with time zone

I'm a bit suspicious of how much horizontal space that would eat, but
if we're able to get rid of the separate cell for result type, it
might work out OK.

            regards, tom lane