Re: Extensions Documentation

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