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

Reply via email to