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

On Mon, Feb 03, 2014 at 08:48:06PM -0500, Tom Lane wrote:
> Robert Haas <robertmhaas@gmail.com> writes:
> > On Mon, Feb 3, 2014 at 4:38 PM, Tom Lane <tgl@sss.pgh.pa.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