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@gmx.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.