Received: from malur.postgresql.org ([217.196.149.56])
 by arkaria.postgresql.org with esmtp (Exim 4.80) (envelope-from
 <pgsql-hackers-owner+M243887=pgsql-hackers-arkari@postgresql.org>)
 id 1WAYFC-00067e-9K
 for pgsql-hackers@arkaria.postgresql.org; Tue, 04 Feb 2014 05:08:22 +0000
Received: from localhost ([127.0.0.1] helo=postgresql.org)
 by malur.postgresql.org with smtp (Exim 4.80) (envelope-from
 <pgsql-hackers-owner+M243887=pgsql-hackers-arkari@postgresql.org>)
 id 1WAYFB-00041V-E4
 for pgsql-hackers@arkaria.postgresql.org; Tue, 04 Feb 2014 05:08:21 +0000
Received: from makus.postgresql.org ([2001:4800:7903:4::125])
 by malur.postgresql.org with esmtp (Exim 4.80)
 (envelope-from <noah@leadboat.com>) id 1WAYFA-00041F-5n
 for pgsql-hackers@postgresql.org; Tue, 04 Feb 2014 05:08:20 +0000
Received: from mail-qc0-f176.google.com ([209.85.216.176])
 by makus.postgresql.org with esmtp (Exim 4.80)
 (envelope-from <noah@leadboat.com>) id 1WAYF3-0007WM-ED
 for pgsql-hackers@postgresql.org; Tue, 04 Feb 2014 05:08:19 +0000
Received: by mail-qc0-f176.google.com with SMTP id e16so12657278qcx.21
 for <pgsql-hackers@postgresql.org>; Mon, 03 Feb 2014 21:08:12 -0800 (PST)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20130820;
 h=x-gm-message-state:date:from:to:cc:subject:message-id:references
 :mime-version:content-type:content-disposition:in-reply-to
 :user-agent;
 bh=BjsyvTswmPteqacmDAIjq0zZhrFzQFyPlaGc/2N6L2c=;
 b=NYB6eiobFvyR6q2OLN0Y8U1cJnmQN0SFFBfCM19pr+4lR9MiDBa+aOApfkl0tENdYd
 dCPa/D6gVQdKbz7F1nR8V/obem7Kg7fo0IefX7ZaB6tNychrDSG2XhvXLNve00ZkuZOA
 ojU/8dgOjKqHt76hXoeWv00bUIuchbyDaO5JMjsi0ODBgbe56shd70Bs5o3xrrWvfzVR
 NK5VBprYUzRC4qe/xtAzB1EKwOja32DLkZqA9Kd3BQYJZAa0fLoAY0NoXcPqJKUjg175
 6s9kRW5WA54KSNbYZEJPmFY9znWJv+2VslFIir32OshhJY/MszG4SmsgfmEnNKz8K3I7
 DC3w==
X-Gm-Message-State: 
 ALoCoQm3CU5rUV0ZL2gIBWtP4i1QGcxUo9gA1W2geFK102SYz1sLFxxYkT6PV212WJ/o/cjxDddt
X-Received: by 10.224.137.66 with SMTP id v2mr17236217qat.104.1391490492097;
 Mon, 03 Feb 2014 21:08:12 -0800 (PST)
Received: from tornado.leadboat.com (c-107-4-219-91.hsd1.va.comcast.net.
 [107.4.219.91])
 by mx.google.com with ESMTPSA id 30sm30708993qgt.4.2014.02.03.21.08.11
 for <multiple recipients>
 (version=TLSv1 cipher=RC4-SHA bits=128/128);
 Mon, 03 Feb 2014 21:08:11 -0800 (PST)
Date: Tue, 4 Feb 2014 00:08:09 -0500
From: Noah Misch <noah@leadboat.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Robert Haas <robertmhaas@gmail.com>, pgsql-hackers@postgreSQL.org,
 pgsql-docs@postgreSQL.org
Subject: Re: Viability of text HISTORY/INSTALL/regression README files (was
 Re: [COMMITTERS] pgsql: Document a few more regression test hazards.)
Message-ID: <20140204050809.GA2410543@tornado.leadboat.com>
References: <E1WALm6-0000nT-M0@gemulon.postgresql.org>
 <22438.1391463522@sss.pgh.pa.us>
 <CA+Tgmob0Jx_9v9KK95gojkjojeP2hTa38_P8JtOFXVDjjSkT=A@mail.gmail.com>
 <28834.1391478486@sss.pgh.pa.us>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <28834.1391478486@sss.pgh.pa.us>
User-Agent: Mutt/1.5.21 (2010-09-15)
X-Pg-Spam-Score: -2.6 (--)
List-Archive: <http://archives.postgresql.org/pgsql-hackers>
List-Help: <mailto:majordomo@postgresql.org?body=help>
List-ID: <pgsql-hackers.postgresql.org>
List-Owner: <mailto:pgsql-hackers-owner@postgresql.org>
List-Post: <mailto:pgsql-hackers@postgresql.org>
List-Subscribe: <mailto:majordomo@postgresql.org?body=sub%20pgsql-hackers>
List-Unsubscribe: <mailto:majordomo@postgresql.org?body=unsub%20pgsql-hackers>
X-Mailing-List: pgsql-hackers
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org

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


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers