Skip site navigation (1) Skip section navigation (2)

Re: [HACKERS] Linking the previously separated documentation

From: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
To: Michael Glaesemann <grzm(at)myrealbox(dot)com>
Cc: pgsql-docs(at)postgresql(dot)org, pgsql-hackers(at)postgresql(dot)org
Subject: Re: [HACKERS] Linking the previously separated documentation
Date: 2004-02-09 05:16:44
Message-ID: 9500.1076303804@sss.pgh.pa.us (view raw or flat)
Thread:
Lists: pgsql-docspgsql-hackers
Michael Glaesemann <grzm(at)myrealbox(dot)com> writes:
> I've been eyeing providing links between the previously separated 
> documentation books, ...
> Is anyone else working on something like this? Is it worthwhile?

There's been talk of this earlier, but I don't recall anyone specifically
saying they'd tackle it.  It's definitely worth doing.

> If so, I've got a question as to style. My first idea was not to change 
> the text at all, and just replace (in the above example) "pg_dump" with 
> <xref linkend="APP-PGDUMP">. Should I be rewriting these sections or is 
> what I'm doing agreeable?

There are (or at one time were) references along the line of "see the
pg_dump page in the <link>reference manual</>".  These obviously could
do with rephrasing now, if you find any left.  As far as style goes,
try to keep in mind that the link only helps for HTML-formatted output,
and we do still try to support printing the documentation on dead trees.
The reference should read well when the link infrastructure isn't there.
I think this means you want to have
	... see the <link>pg_dump</> reference page ...
and not just
	... see <link>pg_dump</> ...
except where the context is pretty obvious, such as a SEE ALSO section
of another reference page.

			regards, tom lane

In response to

Responses

pgsql-docs by date

Next:From: Michael GlaesemannDate: 2004-02-09 05:57:13
Subject: Re: [HACKERS] Linking the previously separated documentation
Previous:From: Michael GlaesemannDate: 2004-02-09 03:15:31
Subject: Linking the previously separated documentation

pgsql-hackers by date

Next:From: Gavin SherryDate: 2004-02-09 05:22:14
Subject: Re: Transaction aborts on syntax error.
Previous:From: Greg StarkDate: 2004-02-09 04:37:19
Subject: Re: Transaction aborts on syntax error.

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group