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

Re: Extensions Documentation

From: "David E(dot) Wheeler" <david(at)justatheory(dot)com>
To: Dimitri Fontaine <dimitri(at)2ndQuadrant(dot)fr>
Cc: Peter Eisentraut <peter_e(at)gmx(dot)net>, Simon Riggs <simon(at)2ndQuadrant(dot)com>, Pg Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: Extensions Documentation
Date: 2012-11-02 16:16:01
Message-ID: 42753C1E-F67A-47DF-AF2B-8256B6A2B2B3@justatheory.com (view raw or flat)
Thread:
Lists: pgsql-hackers
On Nov 2, 2012, at 7:56 AM, Dimitri Fontaine <dimitri(at)2ndQuadrant(dot)fr> wrote:

>> I'd also be in favor of adding hooks to generate man pages.
> 
> Who still use their local copy of the docs (without search ability)
> anyway? About man pages, I don't know how many DBA are looking there
> when they want to find some documentation.

I use man pages *all the time*.

> I think it all gets down to having a local text file installed and a
> proper web site to show off the extension's documentation, tutorial,
> quick start, etc. A good example of that would be the pgmp extension:
> 
>  http://pgmp.projects.pgfoundry.org/
>  https://github.com/dvarrazzo/pgmp/

Yes, and also http://pgxn.org/dist/pgmp/. But that doesn't help if you're offline or behind a moronic corporate firewall.

> Well I'm not really seeing how improving the local copy of any
> documentation is going to change the habit of people to just use some
> online reference with good integrated search facility, or even more
> often, $SEARCH_ENGINE.

Yes, that was one of my motivations for creating PGXN. But I still would love to be able to send someone instructions like this:

    pgxn install pgtap
    man pgtap

Rather than this:

    pgxn install pgtap
    less `pg_config --docdir `/extension/pgtap.mmd

The man page will be easier on the eyes, too.

When I *do* need the HTML docs, I use this when I need to access the full docs on a long flight:

    open `pg_config --docdir`/html/index.html

I would love to see an index of links to pages for each installed extension, too. We have that for contrib stuff, why not third-party extensions?

Best,

David



In response to

pgsql-hackers by date

Next:From: Jeff JanesDate: 2012-11-02 16:27:32
Subject: Re: Synchronous commit not... synchronous?
Previous:From: Dimitri FontaineDate: 2012-11-02 16:00:11
Subject: Re: Proposal for Allow postgresql.conf values to be changed via SQL

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