Date: Fri, 20 Jan 2023 06:26:00 -0600
From: "Karl O. Pinc" <kop@karlpinc.com>
To: Alvaro Herrera <alvherre@alvh.no-ip.org>
Cc: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Doc: Rework contrib appendix -- informative titles, tweaked
 sentences
Message-ID: <20230120062600.690e80ea@slate.karlpinc.com>
In-Reply-To: <20230120114231.ykq5s7w4konrx3i6@alvherre.pgsql>
References: <20230119120205.55766dd3@slate.karlpinc.com>
	<20230120114231.ykq5s7w4konrx3i6@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://www.postgresql.org/message-id/20230120062600.690e80ea%40slate.karlpinc.com>
Precedence: bulk

On Fri, 20 Jan 2023 12:42:31 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> On 2023-Jan-19, Karl O. Pinc wrote:
>=20
> > On Thu, 19 Jan 2023 11:03:53 -0600
> > "Karl O. Pinc" <kop@karlpinc.com> wrote:
> >  =20
> > > Attached are 2 patches, a regular and a delta from your v4 review:
> > >=20
> > > contrib_v5-delta.patch.txt
> > > contrib_v5.patch.txt =20
> >=20
> > I left your appendix title unchanged: "Additional Supplied=20
> > Extensions and Modules". =20
> >=20
> > I had put "Extensions" after
> > "Modules", because, apparently, things that come last in the
> > sentence are most remembered by the reader. My impression is that
> > more people are looking for extensions than modules. =20
>=20
> Hmm, I didn't know that.  I guess I can put it back.  My own instinct
> is to put the most important stuff first, not last, but if research
> says to do otherwise, fine, let's do that.

A quick google on the subject tells me that I can't figure out a good
quick google.  I believe it's from the book at bottom.  Memorability
goes "end", "beginning", "middle".  IIRC.

> I went over all the titles again.  There were a couple of mistakes
> and inconsistencies, which I've fixed to the best of my knowledge.
> I'm happy with 0001 now and will push shortly unless there are
> complaints.
>=20
> I'm still unsure of the [trusted]/[obsolete] marker, so I split that
> out to commit 0002.  I would like to see more support for that before
> pushing that one.
>=20
> I also put the page-split bits to another page, because it seems a bit
> too clumsy.=20

All the above sounds good to me.

> I hope somebody with more docbook-fu can comment: maybe
> there's a way to fix it more generally somehow?

What would the general solution be?  There could be a forced page
break at the beginning of _every_ sect1.  For PDFs.  That seems
a bit much, but maybe not.  The only other thing I can think of
that's "general" would be to force a page break for sect1-s
that are in an appendix.  Is any of this wanted?  (Or technically
"better"?)

Thanks for the help.

    ----

Writing for Readers
By George R. Bramer, Dorothy Sedley =C2=B7 1981

About this edition
ISBN:9780675080453, 0675080452
Page count:532
Published:1981
Format:Hardcover
Publisher:C.E. Merrill Publishing Company
Original from:Pennsylvania State University
Digitized:July 15, 2009
Language:English
Author:George R. Bramer, Dorothy Sedley

It's part of a wave of reaction against Strunk & White,
where they started basing writing on research into reading.
(If it's the right book.)

Regards,

Karl <kop@karlpinc.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein