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.
> 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
pagesand/or HTML output) will be whatever someone decides to implement and get committed. Because otherwise, there is
noconvention at all, aside from the current convention is a plain text file stuck in the docs folder, which isn't
reallydocumentation, IMHO.
Best,
David
