Re: [DOCS] Stats views and functions not in order?

On Thu, Jan 19, 2023 at 2:55 AM David G. Johnston
<david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>
> On Wed, Jan 18, 2023 at 8:38 AM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>>
>> "David G. Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com> writes:
>> > ... I was going for the html effect
>> > of having these views chunked into their own pages, any other changes being
>> > non-detrimental.
>>
>> But is that a result we want? It will for example break any bookmarks
>> that people might have for these documentation entries. It will also
>> pretty thoroughly break the cross-version navigation links in this
>> part of the docs.
>>
>>
>> Maybe the benefit is worth those costs, but I'm entirely not convinced
>> of that. I think we need to tread pretty lightly when rearranging
>> longstanding documentation-layout decisions.
>>
>

David already gave a good summary [1], but since I was the OP here is
the background of v10-0001 from my PoV.

~

The original $SUBJECT requirements evolved to also try to make each
view appear on a separate page after that was suggested by DavidJ [2].
I was unable to achieve per-page views "without radically changing the
document structure." [3], but DavidJ found a way [4] to do it using
refentry. I then wrote the patch v8-0003 using that strategy, which
after more rebasing became the v10-0001 you see today.

I did prefer the view-per-page results (although I also only use HTML
docs). But my worry is that there seem still to be a few unknowns
about how this might affect other (not the HTML) renderings of the
docs. If you think that risk is too great, or if you feel this patch
will cause unwarranted link/bookmark grief, then I am happy to just
drop it.

------
[1] DJ overview -
https://www.postgresql.org/message-id/CAKFQuwaVm%3D6d_sw9Wrp4cdSm5_k%3D8ZVx0--v2v4BH4KnJtqXqg%40mail.gmail.com
[2] DJ suggested view-per-page -
https://www.postgresql.org/message-id/CAKFQuwa9JtoCBVc6CJb7NC5FqMeEAy_A8X4H8t6kVaw7fz9LTw%40mail.gmail.com
[3] PS don't know how to do it -
https://www.postgresql.org/message-id/CAHut%2BPv5Efz1TLWOLSoFvoyC0mq%2Bs92yFSd534ctWSdjEFtKCw%40mail.gmail.com
[4] DJ how to do it using refentry -
https://www.postgresql.org/message-id/CAKFQuwYkM5UZT%2B6tG%2BNgZvDcd5VavS%2BxNHsGsWC8jS-KJsxh7w%40mail.gmail.com

Kind Regards,
Peter Smith.
Fujitsu Australia