Re: Viability of text HISTORY/INSTALL/regression README files (was Re: [COMMITTERS] pgsql: Document a few more regression test hazards.)

Document a few more regression test hazards.

Michael Paquier, reviewed by Christian Kruse

Branch
------
master

Details
-------
http://git.postgresql.org/pg/commitdiff/65a193ebbb5e94b87773fbcbf8909ff8044734ab

Modified Files
--------------
doc/src/sgml/regress.sgml | 20 ++++++++++++++++++--
1 file changed, 18 insertions(+), 2 deletions(-)

Robert Haas <rhaas(at)postgresql(dot)org> writes:
> Document a few more regression test hazards.

guaibasaurus doesn't like this patch: you need to be more careful
about links, because the regression instructions are supposed to
compile as a standalone document.

Easy answer is to get rid of the link to RUNTIME-CONFIG-QUERY-ENABLE.
I think there's some hack you can use to make it sort-of-work standalone
too; look at the release notes for examples.

regards, tom lane

On Mon, Feb 3, 2014 at 4:38 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Robert Haas <rhaas(at)postgresql(dot)org> writes:
>> Document a few more regression test hazards.
>
> guaibasaurus doesn't like this patch: you need to be more careful
> about links, because the regression instructions are supposed to
> compile as a standalone document.
>
> Easy answer is to get rid of the link to RUNTIME-CONFIG-QUERY-ENABLE.
> I think there's some hack you can use to make it sort-of-work standalone
> too; look at the release notes for examples.

Fascinating. I knew that there was a HISTORY file that got built from
the release notes, but I didn't realize there was something similar
being built from regress.sgml. I'll rephase that passage to avoid the
link.

I wonder if these standalone things are really worthwhile. The whole
point of this, ten years ago, was that people who were trying to get
started with PostgreSQL might not have had neither the doc toolchain
nor convenient Internet access available. Plain text documentation
was essential for getting off the ground. This seems much less
relevant today; is the annoyance of not being able to use links
everywhere really buying us anything at this point?

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Robert Haas <robertmhaas(at)gmail(dot)com> writes:
> On Mon, Feb 3, 2014 at 4:38 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>> guaibasaurus doesn't like this patch: you need to be more careful
>> about links, because the regression instructions are supposed to
>> compile as a standalone document.

> I wonder if these standalone things are really worthwhile. The whole
> point of this, ten years ago, was that people who were trying to get
> started with PostgreSQL might not have had neither the doc toolchain
> nor convenient Internet access available. Plain text documentation
> was essential for getting off the ground. This seems much less
> relevant today; is the annoyance of not being able to use links
> everywhere really buying us anything at this point?

That's a very fair question. It's a reasonable bet that pretty much
nobody actually looks at the text versions of either HISTORY or
regress_README anymore. It's conceivable that somebody somewhere makes
use of the text version of INSTALL when trying to get PG going on some
bare-bones platform ... but really, can't they look it up on the net?
How'd they get the PG sources they're installing, anyway?

I'm prepared to believe that these things are just dinosaurs now.
However, at least in the case of the release notes, we'd have to kill them
in all active branches not only HEAD, if we don't want surprises.

Comments?

regards, tom lane

On Mon, Feb 03, 2014 at 08:48:06PM -0500, Tom Lane wrote:
> Robert Haas <robertmhaas(at)gmail(dot)com> writes:
> > On Mon, Feb 3, 2014 at 4:38 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> >> guaibasaurus doesn't like this patch: you need to be more careful
> >> about links, because the regression instructions are supposed to
> >> compile as a standalone document.
>
> > I wonder if these standalone things are really worthwhile. The whole
> > point of this, ten years ago, was that people who were trying to get
> > started with PostgreSQL might not have had neither the doc toolchain
> > nor convenient Internet access available. Plain text documentation
> > was essential for getting off the ground. This seems much less
> > relevant today; is the annoyance of not being able to use links
> > everywhere really buying us anything at this point?
>
> That's a very fair question. It's a reasonable bet that pretty much
> nobody actually looks at the text versions of either HISTORY or
> regress_README anymore. It's conceivable that somebody somewhere makes
> use of the text version of INSTALL when trying to get PG going on some
> bare-bones platform ... but really, can't they look it up on the net?
> How'd they get the PG sources they're installing, anyway?

I sometimes read text-based INSTALL files when building other projects, but a
tiny file giving a URL is almost as good. (The other two generated files do
seem much less important.)

> I'm prepared to believe that these things are just dinosaurs now.
> However, at least in the case of the release notes, we'd have to kill them
> in all active branches not only HEAD, if we don't want surprises.

I wonder how difficult it would be to make sufficient link data available when
building the standalone files. There would be no linking per se; we would
just need the referent's text fragment emitted where the <xref> tag appears.
For example, have a stylesheet that produces a file bearing all link IDs and
titles appearing anywhere in the documentation. Let the standalone builds
include that file.

--
Noah Misch
EnterpriseDB http://www.enterprisedb.com

Noah Misch <noah(at)leadboat(dot)com> writes:
>> Robert Haas <robertmhaas(at)gmail(dot)com> writes:
>>> I wonder if these standalone things are really worthwhile.

> I wonder how difficult it would be to make sufficient link data available when
> building the standalone files. There would be no linking per se; we would
> just need the referent's text fragment emitted where the <xref> tag appears.

IIRC, that's basically what the "workaround" is, except it's not very
automated. Even if it were automated, though, there's still a problem:
such links aren't really *useful* in flat text format. I think that
forcing the author to actually think about what to put there in the
flat text version is a good thing, if we're going to retain the flat
text version at all.

regards, tom lane

On Tue, Feb 4, 2014 at 1:38 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Noah Misch <noah(at)leadboat(dot)com> writes:
>>> Robert Haas <robertmhaas(at)gmail(dot)com> writes:
>>>> I wonder if these standalone things are really worthwhile.
>
>> I wonder how difficult it would be to make sufficient link data available when
>> building the standalone files. There would be no linking per se; we would
>> just need the referent's text fragment emitted where the <xref> tag appears.
>
> IIRC, that's basically what the "workaround" is, except it's not very
> automated. Even if it were automated, though, there's still a problem:
> such links aren't really *useful* in flat text format. I think that
> forcing the author to actually think about what to put there in the
> flat text version is a good thing, if we're going to retain the flat
> text version at all.

Right. I mean, a lot of the links say things like "Section 26.2"
which obviously makes no sense in a standalone text file.

I agree with your comments upthread: INSTALL *might* still be useful
to somebody, but I would be pretty surprised if anyone uses HISTORY or
regress_README for anything any more.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On Tue, Feb 04, 2014 at 03:28:45PM -0500, Robert Haas wrote:
> On Tue, Feb 4, 2014 at 1:38 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> > Noah Misch <noah(at)leadboat(dot)com> writes:
> >>> Robert Haas <robertmhaas(at)gmail(dot)com> writes:
> >>>> I wonder if these standalone things are really worthwhile.
> >
> >> I wonder how difficult it would be to make sufficient link data available when
> >> building the standalone files. There would be no linking per se; we would
> >> just need the referent's text fragment emitted where the <xref> tag appears.
> >
> > IIRC, that's basically what the "workaround" is, except it's not very
> > automated. Even if it were automated, though, there's still a problem:
> > such links aren't really *useful* in flat text format. I think that
> > forcing the author to actually think about what to put there in the
> > flat text version is a good thing, if we're going to retain the flat
> > text version at all.
>
> Right. I mean, a lot of the links say things like "Section 26.2"
> which obviously makes no sense in a standalone text file.

For <xref>s normally displayed that way, text output could emit a URL, either
inline or in the form of a footnote. For link targets (e.g. SQL commands)
having a friendly text fragment for <xref> sites, use the normal fragment.

--
Noah Misch
EnterpriseDB http://www.enterprisedb.com

On Tue, Feb 4, 2014 at 11:43 PM, Noah Misch <noah(at)leadboat(dot)com> wrote:
>> Right. I mean, a lot of the links say things like "Section 26.2"
>> which obviously makes no sense in a standalone text file.
>
> For <xref>s normally displayed that way, text output could emit a URL, either
> inline or in the form of a footnote. For link targets (e.g. SQL commands)
> having a friendly text fragment for <xref> sites, use the normal fragment.

True. If we're going to keep these things around, something like that
would avoid some annoyances for documentation authors. But I still
think we ought to just nuke them, because who cares?

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On 02/05/2014 07:27 PM, Robert Haas wrote:
> On Tue, Feb 4, 2014 at 11:43 PM, Noah Misch <noah(at)leadboat(dot)com> wrote:
>>> Right. I mean, a lot of the links say things like "Section 26.2"
>>> which obviously makes no sense in a standalone text file.
>>
>> For <xref>s normally displayed that way, text output could emit a URL, either
>> inline or in the form of a footnote. For link targets (e.g. SQL commands)
>> having a friendly text fragment for <xref> sites, use the normal fragment.
>
> True. If we're going to keep these things around, something like that
> would avoid some annoyances for documentation authors. But I still
> think we ought to just nuke them, because who cares?

I dont care about HISTORY and even less so about regress_README but I
would prefer to keep INSTALL because I know that people do look at that
one...

Stefan

On 2/3/14, 8:48 PM, Tom Lane wrote:
> That's a very fair question. It's a reasonable bet that pretty much
> nobody actually looks at the text versions of either HISTORY or
> regress_README anymore. It's conceivable that somebody somewhere makes
> use of the text version of INSTALL when trying to get PG going on some
> bare-bones platform ... but really, can't they look it up on the net?
> How'd they get the PG sources they're installing, anyway?

I think having an INSTALL file is good form, and it costs us little to
maintain it.

The other files could be removed, IMO.

On 2/4/14, 3:28 PM, Robert Haas wrote:
> Right. I mean, a lot of the links say things like "Section 26.2"
> which obviously makes no sense in a standalone text file.

The man pages have the same issue. For example from man postgres:

Other possible file layouts are discussed in Section 18.2, "File
Locations", in the documentation.

The same could (probably) be done with the INSTALL file.

Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
> On 2/3/14, 8:48 PM, Tom Lane wrote:
>> That's a very fair question. It's a reasonable bet that pretty much
>> nobody actually looks at the text versions of either HISTORY or
>> regress_README anymore. It's conceivable that somebody somewhere makes
>> use of the text version of INSTALL when trying to get PG going on some
>> bare-bones platform ... but really, can't they look it up on the net?
>> How'd they get the PG sources they're installing, anyway?

> I think having an INSTALL file is good form, and it costs us little to
> maintain it.

> The other files could be removed, IMO.

That seems like a reasonable compromise to me. The HISTORY file is
certainly the worst pain-in-the-rear among these, since it's generated
from files that we change constantly, and so we're always tripping over
the link restrictions.

regards, tom lane

On 08/02/14 19:05, Tom Lane wrote:
> Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
>> On 2/3/14, 8:48 PM, Tom Lane wrote:
>>> That's a very fair question. It's a reasonable bet that pretty much
>>> nobody actually looks at the text versions of either HISTORY or
>>> regress_README anymore. It's conceivable that somebody somewhere makes
>>> use of the text version of INSTALL when trying to get PG going on some
>>> bare-bones platform ... but really, can't they look it up on the net?
>>> How'd they get the PG sources they're installing, anyway?
>> I think having an INSTALL file is good form, and it costs us little to
>> maintain it.
>> The other files could be removed, IMO.
> That seems like a reasonable compromise to me. The HISTORY file is
> certainly the worst pain-in-the-rear among these, since it's generated
> from files that we change constantly, and so we're always tripping over
> the link restrictions.
>
> regards, tom lane
>
>
How about adding URL's for the online versions of HISTORY & README's (or
their rough equivalents - perhaps the online version of the latest
'Appendix E. Release Notes' would be sufficient?) to the INSTALL file?

Cheers,
Gavin

Gavin Flower <GavinFlower(at)archidevsys(dot)co(dot)nz> writes:
> How about adding URL's for the online versions of HISTORY & README's (or
> their rough equivalents - perhaps the online version of the latest
> 'Appendix E. Release Notes' would be sufficient?) to the INSTALL file?

Actually, what I had in mind was to replace the dynamically-generated
HISTORY and README files with small text files that contain those
URL references. If we remove those files from the distribution
tarballs altogether, it'd likely break some packagers' recipes
(I know for sure it'd break the Red Hat RPM specs, for instance).
But packaging should still work if they're there but smaller.

regards, tom lane

I wrote:
> Gavin Flower <GavinFlower(at)archidevsys(dot)co(dot)nz> writes:
>> How about adding URL's for the online versions of HISTORY & README's (or
>> their rough equivalents - perhaps the online version of the latest
>> 'Appendix E. Release Notes' would be sufficient?) to the INSTALL file?

> Actually, what I had in mind was to replace the dynamically-generated
> HISTORY and README files with small text files that contain those
> URL references.

Here's a proposed patch against HEAD for this. It also gets rid of some
rather quaint instructions for using Netscape to construct these files ;-)

Barring objection, I'd like to update all the live branches this way
before the upcoming releases. I'm tired of having to worry about
whether the release notes will build as plain text; but that worry
won't go away unless we nuke the text output in all the branches.

regards, tom lane

On Sat, Feb 8, 2014 at 4:41 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> I wrote:
>> Gavin Flower <GavinFlower(at)archidevsys(dot)co(dot)nz> writes:
>>> How about adding URL's for the online versions of HISTORY & README's (or
>>> their rough equivalents - perhaps the online version of the latest
>>> 'Appendix E. Release Notes' would be sufficient?) to the INSTALL file?
>
>> Actually, what I had in mind was to replace the dynamically-generated
>> HISTORY and README files with small text files that contain those
>> URL references.
>
> Here's a proposed patch against HEAD for this. It also gets rid of some
> rather quaint instructions for using Netscape to construct these files ;-)
>
> Barring objection, I'd like to update all the live branches this way
> before the upcoming releases. I'm tired of having to worry about
> whether the release notes will build as plain text; but that worry
> won't go away unless we nuke the text output in all the branches.

Sounds OK to me. If there's as many as two people using those files,
I'll be surprised. (Of course, I've been surprised before.)

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On 2/8/14, 4:41 PM, Tom Lane wrote:
> diff --git a/HISTORY b/HISTORY
> index ...360c7f6 .
> *** a/HISTORY
> --- b/HISTORY
> ***************
> *** 0 ****
> --- 1,6 ----
> + Release notes for all versions of PostgreSQL can be found on-line at
> + http://www.postgresql.org/docs/devel/static/release.html

Should be "current" instead of "devel"?

> +
> + In a distribution file set, release notes for the current version can be
> + found prebuilt under doc/src/sgml/html/. Visit the index.html file with
> + an HTML browser, then consult the "Release Notes" appendix.

You can point them straight at doc/src/sgml/html/release.html.

Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
> On 2/8/14, 4:41 PM, Tom Lane wrote:
>> + Release notes for all versions of PostgreSQL can be found on-line at
>> + http://www.postgresql.org/docs/devel/static/release.html

> Should be "current" instead of "devel"?

>> +
>> + In a distribution file set, release notes for the current version can be
>> + found prebuilt under doc/src/sgml/html/. Visit the index.html file with
>> + an HTML browser, then consult the "Release Notes" appendix.

> You can point them straight at doc/src/sgml/html/release.html.

Done and done. I also noticed that these instructions were wrong anyway
for 8.4, which still has the embedded-tarball HTML docs, so I adjusted
the text for that version.

regards, tom lane