pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedLinking the previously separated documentation
5+ messages / 3 participants
[nested] [flat]
* Linking the previously separated documentation
@ 2004-02-09 03:15 Michael Glaesemann <grzm@myrealbox.com>
2004-02-09 05:16 ` Re: [HACKERS] Linking the previously separated documentation Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 5+ messages in thread
From: Michael Glaesemann @ 2004-02-09 03:15 UTC (permalink / raw)
To: pgsql-docs; +Cc: pgsql-hackers@postgresql.org
Hello all!
I've been eyeing providing links between the previously separated
documentation books, e.g., linking this sentence "Please familiarize
yourself with the pg_dump reference page." in the backup and restore
section <http://www.postgresql.org/docs/current/static/backup.html; to
the applicable reference page. I haven't gone through all of the docs
yet (there are a lot of them!) and right now I'm just looking for
obvious linking possibilities of the "see foo" variety. Is anyone else
working on something like this? Is it worthwhile?
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? (Might not be a bad idea to work up a style
book for the documentation to guide writing, but that's a project in
and of itself.)
If everything seems fine, I'll see if I can't figure out how to submit
a patch.
Michael Glaesemann
grzm myrealbox com
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: [HACKERS] Linking the previously separated documentation
2004-02-09 03:15 Linking the previously separated documentation Michael Glaesemann <grzm@myrealbox.com>
@ 2004-02-09 05:16 ` Tom Lane <tgl@sss.pgh.pa.us>
2004-02-09 05:57 ` Re: [HACKERS] Linking the previously separated documentation Michael Glaesemann <grzm@myrealbox.com>
0 siblings, 1 reply; 5+ messages in thread
From: Tom Lane @ 2004-02-09 05:16 UTC (permalink / raw)
To: Michael Glaesemann <grzm@myrealbox.com>; +Cc: pgsql-docs; pgsql-hackers@postgresql.org
Michael Glaesemann <grzm@myrealbox.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
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: [HACKERS] Linking the previously separated documentation
2004-02-09 03:15 Linking the previously separated documentation Michael Glaesemann <grzm@myrealbox.com>
2004-02-09 05:16 ` Re: [HACKERS] Linking the previously separated documentation Tom Lane <tgl@sss.pgh.pa.us>
@ 2004-02-09 05:57 ` Michael Glaesemann <grzm@myrealbox.com>
2004-02-09 09:23 ` Re: [HACKERS] Linking the previously separated documentation Peter Eisentraut <peter_e@gmx.net>
0 siblings, 1 reply; 5+ messages in thread
From: Michael Glaesemann @ 2004-02-09 05:57 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs; pgsql-hackers@postgresql.org
On Feb 9, 2004, at 2:16 PM, Tom Lane wrote:
> Michael Glaesemann <grzm@myrealbox.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.
Okay. I'll keep working.
>> 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.
If I'm understanding you correctly, that's what I'm doing. Here's an
example of the change:
Original:
Please familiarize yourself with the
<citerefentry><refentrytitle>pg_dump</> reference page.
Revised:
Please familiarize yourself with the
<citerefentry><refentrytitle><xref linkend="APP-PGDUMP"></></>
reference page.
Doing it this way makes for quicker changes and few disruptions of any
output flow, I believe. And it gets things linked. Rewriting could be
worried about later.
Michael Glaesemann
grzm myrealbox com
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: [HACKERS] Linking the previously separated documentation
2004-02-09 03:15 Linking the previously separated documentation Michael Glaesemann <grzm@myrealbox.com>
2004-02-09 05:16 ` Re: [HACKERS] Linking the previously separated documentation Tom Lane <tgl@sss.pgh.pa.us>
2004-02-09 05:57 ` Re: [HACKERS] Linking the previously separated documentation Michael Glaesemann <grzm@myrealbox.com>
@ 2004-02-09 09:23 ` Peter Eisentraut <peter_e@gmx.net>
2004-02-09 10:50 ` Re: [HACKERS] Linking the previously separated documentation Michael Glaesemann <grzm@myrealbox.com>
0 siblings, 1 reply; 5+ messages in thread
From: Peter Eisentraut @ 2004-02-09 09:23 UTC (permalink / raw)
To: Michael Glaesemann <grzm@myrealbox.com>; Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs; pgsql-hackers@postgresql.org
Michael Glaesemann wrote:
> If I'm understanding you correctly, that's what I'm doing. Here's an
> example of the change:
>
> Original:
> Please familiarize yourself with the
> <citerefentry><refentrytitle>pg_dump</> reference page.
>
> Revised:
> Please familiarize yourself with the
> <citerefentry><refentrytitle><xref linkend="APP-PGDUMP"></></>
> reference page.
If you write xref then you already say that this is a cross-reference,
so you don't need the citerefentry element. (citerefentry is typically
used to automatically link all occurences to the location of the
manpage. For instance, FreeBSD uses it to link all refentry
"citations" to their online manpage gateway.)
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: [HACKERS] Linking the previously separated documentation
2004-02-09 03:15 Linking the previously separated documentation Michael Glaesemann <grzm@myrealbox.com>
2004-02-09 05:16 ` Re: [HACKERS] Linking the previously separated documentation Tom Lane <tgl@sss.pgh.pa.us>
2004-02-09 05:57 ` Re: [HACKERS] Linking the previously separated documentation Michael Glaesemann <grzm@myrealbox.com>
2004-02-09 09:23 ` Re: [HACKERS] Linking the previously separated documentation Peter Eisentraut <peter_e@gmx.net>
@ 2004-02-09 10:50 ` Michael Glaesemann <grzm@myrealbox.com>
0 siblings, 0 replies; 5+ messages in thread
From: Michael Glaesemann @ 2004-02-09 10:50 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-docs; pgsql-hackers@postgresql.org
On Feb 9, 2004, at 6:23 PM, Peter Eisentraut wrote:
> Michael Glaesemann wrote:
>> If I'm understanding you correctly, that's what I'm doing. Here's an
>> example of the change:
>>
>> Original:
>> Please familiarize yourself with the
>> <citerefentry><refentrytitle>pg_dump</> reference page.
>>
>> Revised:
>> Please familiarize yourself with the
>> <citerefentry><refentrytitle><xref linkend="APP-PGDUMP"></></>
>> reference page.
>
> If you write xref then you already say that this is a cross-reference,
> so you don't need the citerefentry element. (citerefentry is typically
> used to automatically link all occurences to the location of the
> manpage. For instance, FreeBSD uses it to link all refentry
> "citations" to their online manpage gateway.)
Thanks, Peter! Good to know.
Michael Glaesemann
grzm myrealbox com
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2004-02-09 10:50 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2004-02-09 03:15 Linking the previously separated documentation Michael Glaesemann <grzm@myrealbox.com>
2004-02-09 05:16 ` Tom Lane <tgl@sss.pgh.pa.us>
2004-02-09 05:57 ` Michael Glaesemann <grzm@myrealbox.com>
2004-02-09 09:23 ` Peter Eisentraut <peter_e@gmx.net>
2004-02-09 10:50 ` Michael Glaesemann <grzm@myrealbox.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox