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. > 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 -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
