Re: New "function tables" in V13 documentation

On 11/13/20 11:20 AM, Kevin Brannen wrote:
>> From: David G. Johnston <david.g.johnston@gmail.com>
> 
>> On Mon, Nov 9, 2020 at 1:41 PM Tom Lane <mailto:tgl@sss.pgh.pa.us> wrote:
>> Alvaro Herrera <mailto:alvherre@alvh.no-ip.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.
> 
>>> 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
sincethere is considerable extra information in one's eyes during that process that needs to be skimmed over.
 
> 
> 
> I'm slow to the party, but I'm going to go with the new format is horrible. I agree with David that you can't quickly
scandown the new table to find things like the return type (for example) which is something I do frequently. Go to the
stringfuncs/ops page in v13, and try to quickly find the ones that return an "int" (because your goal is to find the
positionof something in a string so you know the return value will have to be an "int"). The new version makes that
hardwhile the old version is easy. In fact, I couldn't even find the return type at first when I looked because there
isno label (the power of tables with headers was removed).
 
> 
> The description and example also run together under the new format, which sort of comes across as a "wall of text".
IfI really zoom in, I can see they're different fonts, but at my normal zoom level they look pretty much the same at
firstglance.
 

+1

> 
> This makes me want to stay on v12.x for as long as possible -- really.

Second the motion.

> 
> If the maintainers are dead-set on maintaining the new format despite it drawbacks (and after reading all the other
commentsabout the positives I'm going to say I don't see any positives**), then it'd be extremely helpful to do some
CSSmagic to make them easier to read. Personally, I'd like to see there be a setting for if media is HTML that it show
theold table format, but if not, here's some ideas to make the new format more palatable:
 
> 
> * The return type needs to stand out a LOT more, bold would be a great start, adding color would help too.
> 
> * Make the description and example look much more different, again color or perhaps color banding (background a light
grayor something on the example).
 
> 
> * Make the example code and example results more different, the simple "->" between them gets lost easily to my eye
soit's harder to read as is.
 
> 
> * Can you add a few more classes to identify the parts betters in the tables? For example, I see the CSS class
"returnvalue"on the example result, but there is nothing on the example code itself identifying it as such. If you did
thisbetter labeling then perhaps those of us who are complaining could attempt to overcome some of our objections by
restylingthe tables with colors & fonts & such. Not a full solution as that would require manipulating the DOM, but
evensmall changes with color could bring large relief.
 
> 
> [** I think it was Bruce who pointed out the old table format was troublesome in the PDF format. I concede that and
anythingelse for when you're constrained to paper. But I suspect most users look at these docs on a computer monitor
withHTML so those size constraints aren't an issue there. Designing pages to the smallest media just frustrates those
userson larger media (cue the many examples on the web where the left/right margins are so wide half of your screen is
wastedinstead of letting the text flow and resize).]
 
> 
> Kevin
> This e-mail transmission, and any documents, files or previous e-mail messages attached to it, may contain
confidentialinformation. If you are not the intended recipient, or a person responsible for delivering it to the
intendedrecipient, you are hereby notified that any disclosure, distribution, review, copy or use of any of the
informationcontained in or attached to this message is STRICTLY PROHIBITED. If you have received this transmission in
error,please immediately notify us by reply e-mail, and destroy the original transmission and its attachments without
readingthem or saving them to disk. Thank you.
 
> 


-- 
Adrian Klaver
adrian.klaver@aklaver.com