Обсуждение: 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