Robert Haas <robertmh...@gmail.com> writes: > The v12 version of the "Table 9.30. Date/Time Operators" is not that > wide, and is really quite clear.
Well, no it isn't. The main nit I would pick in that claim is that it's far from obvious that the three examples of float8 * interval are all talking about the same operator; in fact, a reader would be very likely to draw the false conclusion that there is an integer * interval operator. This is an aspect of the general problem that we don't have a nice way to deal with multiple examples in the tables. Somebody kluged their way around it here in this particular way, but I'd really like a clearer way, because we need more examples. I would also point out that this table is quite out of step with the rest of the docs in its practice of showing the results as though they were typed literals. Most places that show results just show what you'd expect to see in a psql output column, making it necessary to show the result data type somewhere else. > The new version takes 3 lines per > operator where the old one took one. That's because you've added (1) a > description of the fact that + does addition and - does subtraction, > repeated for each operator, and (2) explicit information about the > input and result types. I don't think either add much, in this case. As I already said, I agree about the text descriptions being of marginal value in this case. I disagree about the explicit datatypes, because the float8 * interval cases already show a hole in that argument, and surely we don't want to require every example to use explicitly-typed literals and nothing but. Besides, what will you do for operators that take anyarray or the like? > For more complicated cases, one thing we could do is ditch the table > and use a <variablelist> with a separate <varlistentry> for each > operator. So you could have something like: > ... > But I would only advocate for this style in cases where there is > substantial explaining to be done. I'd like to have more consistency, not less. I do not think it helps readers to have each page in Chapter 9 have its own idiosyncratic way of presenting operators/functions. The operator tables are actually almost that bad, right now --- compare section 9.1 (hasn't even bothered with a formal <table>) with tables 9.1, 9.4, 9.9, 9.12, 9.14, 9.30, 9.34, 9.37, 9.41, 9.44. The variation in level of detail and precision is striking, and not in a good way. regards, tom lane