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

On Sat, Nov 26, 2022 at 2:43 PM David G. Johnston
<david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>
> On Wed, Nov 23, 2022 at 1:36 AM Peter Smith <smithpb2250(at)gmail(dot)com> wrote:
>>
>> On Thu, Nov 17, 2022 at 8:46 AM David G. Johnston
>> <david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>>
>> > Also, make it so each view ends up being its own separate page.
>> >
>>
>> I did not do this. AFAIK those views of chapter 54 get rendered to
>> separate pages only because they are top-level <sect1>. So I do not
>> know how to put all these stats views onto different pages without
>> radically changing the document structure. Anyway – doing this would
>> be incompatible with my <sect3> changes of patch 0006 (see above).
>>
>
> I did some experimentation and reading on this today. Short answer - turn each view into a refentry under a dedicated sect2 where the table resides.
>
> David J.
>
> <chapter>
> [...]
> <sect1> <!--The Cumulative Statistics System -->
> [...]
> <sect2>
> <title>Statistics Views</title>
> <para>Table of Statistics Views...</para>
>
> <refentry id="monitoring-pg-stat-activity-view">
> <refnamediv><refname>pg_stat_activity</refname><refpurpose>Purpose</refpurpose></refnamediv>
> <refsect1>
> <title><structname>pg_stat_activity</structname></title>
>
> <indexterm>
> <primary>pg_stat_activity</primary>
> </indexterm>
>
> </refsect1></refentry>
>
> </sect2> <!-- Statistics Views -->
>
> </sect1>
> </chapter>
>
> I was doing quite a bit of experimentation and basically gutted the actual page to make that easier. The end result looked basically like below.
>
> Chapter 28. Monitoring Database Activity
>
> Table of Contents
>
> 28.1. Standard Unix Tools
> 28.2. The Cumulative Statistics System
>
> 28.2.1. Statistics Collection Configuration
> 28.2.2. Viewing Statistics
> 28.2.3. Statistics Views
>

PSA v8* patches.

Here, patches 0001 and 0002 are unchanged, but 0003 has many changes
per David's suggestion [1] to change all these views to <refentry>
blocks.

So, I've done pretty much the same as per the above advice, except:
- I just called the <refpurpose> text for all these views "View"
- I changed the <refsect1> <title> to be "Description". This renders
nicer (without the double text of the view name) and is also more in
keeping with the example I found here [2].

End result seems OK. YMMV.

~

Note that the refentry order within the monitoring.sgml is unchanged
from the previous <sect2> section order, so it's neither alphabetical
nor is it in the same order as within the tables. This is noticeable
only if you pay attention to the NEXT/PREV links at the bottom of the
browser page... so I'm not sure if it's worth shuffling these refentry
blocks into some better order or not?

------
[1] David's restructure suggestion
https://www.postgresql.org/message-id/CAKFQuwYkM5UZT%2B6tG%2BNgZvDcd5VavS%2BxNHsGsWC8jS-KJsxh7w%40mail.gmail.com
[2] Example of a refentry https://tdg.docbook.org/tdg/3.1/refentry.html

Kind Regards,
Peter Smith.
Fujitsu Australia