Thread: Supplemental contrib docs (was: [GENERAL] DBlink documentation)
Tom Lane wrote:
> Joe Conway <mail@joeconway.com> writes:
>>Tom Lane wrote:
>>
>>>It's not only the downstream packagers that have missed these: the
>>>Makefiles don't install them either.
>>>
>>>It'd be a good idea to settle on what we want the installed file layout
>>>to be --- do we need to create subdirectories under {prefix}/doc to
>>>forestall name conflicts?
>
>>While I'm messing with dblink, did you want me to do anything WRT this?
>
> I don't think we settled on what we want to do yet. Any thoughts?
>
> I'm kind of leaning toward the subdirectory idea myself...
(I removed GENERAL, and added DOCS to the distribution of this thread)
Well I like {prefix}/doc given that's how dblink is already set up ;-)
Questions:
- Do we want a naming convention for the files in
{prefix}/doc?
- Do we pre-create {prefix}/doc for every contrib
directory in advance?
I think the answers are no, and yes, but I don't feel strongly about either.
Joe
On Tue, Jan 03, 2006 at 04:20:38PM -0800, Joe Conway wrote:
> Tom Lane wrote:
> >Joe Conway <mail@joeconway.com> writes:
> >>Tom Lane wrote:
> >>
> >>>It's not only the downstream packagers that have missed these: the
> >>>Makefiles don't install them either.
> >>>
> >>>It'd be a good idea to settle on what we want the installed file layout
> >>>to be --- do we need to create subdirectories under {prefix}/doc to
> >>>forestall name conflicts?
> >
> >>While I'm messing with dblink, did you want me to do anything WRT this?
> >
> >I don't think we settled on what we want to do yet. Any thoughts?
> >
> >I'm kind of leaning toward the subdirectory idea myself...
>
> (I removed GENERAL, and added DOCS to the distribution of this thread)
>
> Well I like {prefix}/doc given that's how dblink is already set up ;-)
>
> Questions:
> - Do we want a naming convention for the files in
> {prefix}/doc?
> - Do we pre-create {prefix}/doc for every contrib
> directory in advance?
>
> I think the answers are no, and yes, but I don't feel strongly about either.
By {prefix} do you mean where PostgreSQL is being installed? If so, that
would be highly non-standard. I think what you'd want is
{prefix}/share/doc/postgresql/contrib/.
--
Jim C. Nasby, Sr. Engineering Consultant jnasby@pervasive.com
Pervasive Software http://pervasive.com work: 512-231-6117
vcard: http://jim.nasby.net/pervasive.vcf cell: 512-569-9461
Jim C. Nasby wrote:
> On Tue, Jan 03, 2006 at 04:20:38PM -0800, Joe Conway wrote:
>>Well I like {prefix}/doc given that's how dblink is already set up ;-)
>>
> By {prefix} do you mean where PostgreSQL is being installed? If so, that
> would be highly non-standard. I think what you'd want is
> {prefix}/share/doc/postgresql/contrib/.
Well, I assumed Tom was referring to placement in the source tree, i.e.
{prefix} is contrib/dblink, etc.
But this raises a good question in terms of where these files should be
installed. The README.xxx files all go to {install-prefix}/doc/contrib.
I experimented with changing the Makefile line:
DOCS = README.dblink
to be:
DOCS = README.dblink doc/*
Unfortunately the files from contrib/dblink/doc still wound up being
installed to {install-prefix}/doc/contrib, which would become a naming
collision hazard. Maybe they should go to
{install-prefix}/doc/contrib/xxx (where xxx is the name of each contrib
dir)?
Joe
Joe Conway <mail@joeconway.com> writes:
> Well, I assumed Tom was referring to placement in the source tree, i.e.
> {prefix} is contrib/dblink, etc.
I'm concerned about both location in the source tree (dblink and
tsearch2 are inconsistent) and location in the installation tree.
The former seems easy to resolve: doc/ is the universal standard
directory name for documentation, not docs/. I am not sure that
we want to commit to creating a pile of subdirectories under the
installation doc/ directory, though. If they were mostly full,
fine, but a bunch of directories that are mostly empty would just
be clutter. Maybe create subdirectories only for modules that
have 'em in the source tree?
regards, tom lane