On Fri, 2012-10-26 at 09:09 -0700, David E. Wheeler wrote: > On Oct 26, 2012, at 5:27 AM, Peter Eisentraut <pete...@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. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
