Re: Getting our tables to render better in PDF output

[Corey Huinker]

On Mon, Apr 13, 2020 at 12:28 PM Tom Lane  wrote:

> Corey Huinker  writes:
> > I was thinking that there were references that included parameters, but
> I'm
> > not finding any with actual parameter values, so at most we'd lose the
> "()"
> > of a reference.
>
> We could possibly stick the parens into the indexterm text.  Arguably
> that's an improvement on its own merits, since it'd become clearer which
> index entries are function names.  If you don't want that, another idea is
> to put xreflabel options that include the parens into the indexterm tags.
> Or we can just standardize on not having parens, but personally I like
> them.  Without parens, for clarity you really have to write "function
> foo" which is redundant-looking in the XML and hence
> easy to get wrong.
>

That makes sense to me. There may be some hope for the font via the
xrefstyle attribute, but I'm not educated well enough on docbook to know
for sure.


> > Assuming we want to make the anchors visible, we need a way for people to
> > discover the anchors we've made, and my thought there is that we make the
> > first definition a non-xref link to the indexterm just above it. Any
> > thoughts on what the best way to do that is?
>
> I'm not really buying into that as a requirement.  For one thing, the
> anchor name will be 100% predictable.
>

The anchor name is deterministic (or I intend it to be) but
the existence of the link is not predictable. So while having no visible
link is fine for internal links which we create, I'm envisioning a
not-very-experienced reader wanting to help an even-less-experienced
person. If they find the date_part function, and they see that the word
"date_part" is itself clickable, they'll probably click it once, see that
it's a link, and send the less-experienced person the anchored link instead
of the broader page link. They're very unlikely to try to forge their own
anchor link in the hopes that it already exists.

One thing that I noticed while playing with this last night is that
> even though  or  links will take you right to the exact
> table entry, the index entries generated from the indexterms only
> point to the page.  That seems pretty sad, why isn't it better?
>

As you've described it it does seem very odd, but maybe I'm just
misunderstanding.

Re: Getting our tables to render better in PDF output

[Tom Lane]

Corey Huinker  writes:
> I was thinking that there were references that included parameters, but I'm
> not finding any with actual parameter values, so at most we'd lose the "()"
> of a reference.

We could possibly stick the parens into the indexterm text.  Arguably
that's an improvement on its own merits, since it'd become clearer which
index entries are function names.  If you don't want that, another idea is
to put xreflabel options that include the parens into the indexterm tags.
Or we can just standardize on not having parens, but personally I like
them.  Without parens, for clarity you really have to write "function
foo" which is redundant-looking in the XML and hence
easy to get wrong.

> Assuming we want to make the anchors visible, we need a way for people to
> discover the anchors we've made, and my thought there is that we make the
> first definition a non-xref link to the indexterm just above it. Any
> thoughts on what the best way to do that is?

I'm not really buying into that as a requirement.  For one thing, the
anchor name will be 100% predictable.

One thing that I noticed while playing with this last night is that
even though  or  links will take you right to the exact
table entry, the index entries generated from the indexterms only
point to the page.  That seems pretty sad, why isn't it better?

regards, tom lane

Re: Getting our tables to render better in PDF output

[Corey Huinker]

>
>
> I did a quick check by adding id tags to all 700-or-so s in
> func.sgml (don't get excited, it was a perl one-liner that just added
> random id strings).


I did, actually, get excited for a second.


> The runtime difference for building the HTML docs
> seems to be under 1%, and negligible for PDF output.  So it looks like
> we don't have to worry about scalability of tagging all the functions.
>

Ok, so that's the function anchors.

So some references to functions are just the name, and xrefs will work fine
for those.

I was thinking that there were references that included parameters, but I'm
not finding any with actual parameter values, so at most we'd lose the "()"
of a reference.

Assuming we want to make the anchors visible, we need a way for people to
discover the anchors we've made, and my thought there is that we make the
first definition a non-xref link to the indexterm just above it. Any
thoughts on what the best way to do that is?

Re: Improve This Sentence?

[Dave Cramer]

On Sun, 12 Apr 2020 at 20:57, Michael Paquier  wrote:

> On Fri, Apr 10, 2020 at 06:32:05PM +, PG Doc comments form wrote:
> > On Linux and POSIX platforms checkpoint_flush_after allows to force the
> OS
> > that pages written by the checkpoint should be flushed to disk after a
> > configurable number of bytes.
> >
> > I think I have an idea what it says, but saw some discussion to this very
> > issue.  Can it be re-written?
>
> How would you suggest to rewrite it?
>

This is interesting here is the entire paragraph in question from 29.4. WAL
Configuration

On Linux and POSIX platforms checkpoint_flush_after

allows
to force the OS that pages written by the checkpoint should be flushed to
disk after a configurable number of bytes. Otherwise, these pages may be
kept in the OS's page cache, inducing a stall when fsync is issued at the
end of a checkpoint. This setting will often help to reduce transaction
latency, but it also can have an adverse effect on performance;
particularly for workloads that are bigger than shared_buffers
,
but smaller than the OS's page cache.

and here is another paragraph which is much better from 19.5.2. Checkpoints

Whenever more than this amount of data has been written while performing a
checkpoint, attempt to force the OS to issue these writes to the underlying
storage. Doing so will limit the amount of dirty data in the kernel's page
cache, reducing the likelihood of stalls when an fsync is issued at the end
of the checkpoint, or when the OS writes data back in larger batches in the
background. Often that will result in greatly reduced transaction latency,
but there also are some cases, especially with workloads that are bigger
than shared_buffers
,
but smaller than the OS's page cache, where performance might degrade. This
setting may have no effect on some platforms. If this value is specified
without units, it is taken as blocks, that is BLCKSZ bytes, typically 8kB.
The valid range is between 0, which disables forced writeback, and 2MB. The
default is 256kB on Linux, 0 elsewhere. (If BLCKSZ is not 8kB, the default
and maximum values scale proportionally to it.) This parameter can only be
set in the postgresql.conf file or on the server command line.

Ironically the first one above is supposed to be providing more clarity if
you can believe:
For additional information on tuning these settings, see Section 29.4.

Clearly just copying the text from 19.5.2 to 29.4 is an improvement. I'd be
somewhat loathe to be that repetitive but honestly I don't have a better
suggestion

Dave

https://www.postgres.rocks

>
>