Re: Extensions Documentation

On Oct 26, 2012, at 5:27 AM, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:

>
> The advantage that these programming language ecosystems have is that
> they can implement the processors for the documentation format in the
> language itself, so it's easy to recommend or enforce a particular
> system. I don't think we're going to implement any documentation
> processing in SQL, so we'd end up adding some kind of external
> dependency, and that's usually tricky.

True, which is why I was thinking of something relatively light-weight and self-contained like sundown.

> Also, there are wildly diverging paradigms in use. For example, in
> Perl, the convention is one man page per module. In Python, for most
> modules you don't get any locally installed documentation by default.
> Instead, you're encouraged to upload your stuff to readthedocs.org. All
> of these have their advantages, but I think it's too early to tell what
> the best convention for a PostgreSQL extension would be.

Well, only because nothing much exists yet. The convention for what gets turned into proper documentation (e.g., man pages and/or HTML output) will be whatever someone decides to implement and get committed. Because otherwise, there is no convention at all, aside from the current convention is a plain text file stuck in the docs folder, which isn't really documentation, IMHO.

Best,

David