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

On Wed, Jan 18, 2023 at 3:36 AM Peter Eisentraut <
peter(dot)eisentraut(at)enterprisedb(dot)com> wrote:

> On 11.01.23 07:11, Peter Smith wrote:
> > v9-0003 --> v10-0001
> >
> >> I'm not sure if anything is pending for v9-0003, if there is something
> >> pending, please post an updated patch for the same.
> >
> > Thanks for the reminder. PSA v10.
>
> So this patch changes some sections describing system views to
> refentry's. What is the reason for that? refentry's are basically man
> pages; do we want man pages for each system view?
>

I didn't really consider the effect this might have on man pages. I knew
it would produce the desired effect in the HTML and assumed it would
produce an acceptable effect in the PDF. I was going for the html effect
of having these views chunked into their own pages, any other changes being
non-detrimental. And inspecting the DocBook configurations learned that
sect1 and refentry had this effect. Using sect1 is not possible in this
part of the documentation.

>
> Maybe (*), but then we should also do the same to all the other system
> views, all the system catalogs, everything else. Just changing a few in
> a single place seems odd.
>
> (*) -- but also maybe not?
>
>
I could see those who use man pages being pleased with having access to
these core building blocks of the system at ready access. I am not one of
those people, using the website exclusively. If there is a champion of man
pages here that wants to ensure that changes in this area work well there
this patch would be better for it.

I really want a one-page-per-view output on the website in this section.
This is the only way I could see getting to that point (as noted upthread,
system catalogs don't have this problem because they are able to be
marked up as sect1) . The existing side-effect is, for me, an acceptable
trade-off situation. If you want to provide a statement for why these are
special, it's because they are in the System Monitoring chapter instead of
System Internals and the man pages don't cover system internals...

I'm not opposed to alternative markup that gets the pagination job done,
though it likely involves tool-chain configuration/modifications. There is
a nearby thread where this is being done presently so maybe if refentry is
a commit-blocker there is still hope, but it is presently outside my
capability. I'm after the pagination and have no current preference as to
how it is technically accomplished.

David J.