From: | Peter Eisentraut <peter_e(at)gmx(dot)net> |
---|---|
To: | "David E(dot) Wheeler" <david(at)justatheory(dot)com> |
Cc: | Simon Riggs <simon(at)2ndQuadrant(dot)com>, Pg Hackers <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Extensions Documentation |
Date: | 2012-10-30 21:08:44 |
Message-ID: | 1351631324.9232.6.camel@vanquo.pezone.net |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-hackers |
On Fri, 2012-10-26 at 09:09 -0700, David E. Wheeler wrote:
> 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.
That's a markdown library, which transforms markdown to HTML, right? So
what would we do with the HTML?
> > 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.
I don't agree with this approach. There is no need to be prescriptive.
Enforcing a documentation format won't make better, or any,
documentation anyway.
That said, if there are things we could put in, e.g., pgxs, to make
building documentation simpler, we can discuss that.
From | Date | Subject | |
---|---|---|---|
Next Message | Peter Eisentraut | 2012-10-30 21:11:14 | Re: [COMMITTERS] pgsql: Preserve intermediate .c files in coverage mode |
Previous Message | Oskari Saarenmaa | 2012-10-30 21:06:56 | [PATCH] PL/Python: Add spidata to all spiexceptions |