Re: New "function tables" in V13 documentation

On 11/9/20 2:47 PM, David G. Johnston wrote:
> On Mon, Nov 9, 2020 at 1:41 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us
> <mailto:tgl(at)sss(dot)pgh(dot)pa(dot)us>> wrote:
>
> Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org
> <mailto:alvherre(at)alvh(dot)no-ip(dot)org>> writes:
> > On 2020-Nov-08, Adrian Klaver wrote:
> >> Yeah, I would agree with the mobile first design comments. Then
> again that
> >> plague is hitting most sites these days. My 2 cents is it is a step
> >> backwards. You can cover more ground quickly and digest it faster
> in the old
> >> format.
>
> > The person who made that comment retracted later.
>
> > If you have suggestion on how to improve the new format, I'm sure we can
> > discuss that.  It seems pretty clear to me that we're not going back to
> > the old format.
>
> I think there's no question that the new format is better in any case
> where a function needs more than a couple words of documentation.
> I could see the argument for adopting a more compact format for tables
> that contain no such functions.  I think you might find that the set of
> such tables is nigh empty, though; even section 9.3 (mathematical
> functions) has a lot of functions that need a sentence or two.  We used
> to either omit important details for such functions or stick them in
> footnotes, and neither of those options is very nice.
>
>
> My observation is that the new format reduces one's ability to quickly
> skim the table to find out what is present since there is considerable
> extra information in one's eyes during that process that needs to be
> skimmed over.
>
> My suggestion is to add a "table of contents" at the top of non-trivial
> sections that simply lists available functions by name (generally ignoring
> argument variations) and a quick one line description of purpose.  Once a
> person finds the name of the function that suits their needs they can then
> reference the main table for details, warnings, and examples.

This is what TOCs are for, no?

--
Angular momentum makes the world go 'round.