Re: Extensions Documentation

On Oct 25, 2012, at 10:42 AM, Simon Riggs <simon(at)2ndQuadrant(dot)com> wrote:

>> Any plans to implement a documentation standard for extensions? I would love to see `make install` create the necessary man pages and perhaps even HTML (with a link added in the proper place). Anyone given this any thought? Dim?
>
> Isn't that distro-dependent?

No. PostgreSQL ships its own documentation as man pages and HTML (or build them, I guess). Distros put them where they want, I guess, but that’s just moving files around. I'm thinking thre could be some sort of support in core for generating docs and adding them to wherever the core docs are (or closely related, e.g., a subdirectory).

I'm thinking of Pod as the precedent here, but I think most of the popular programming language ecosystems offer something like this (JavaDoc, rdoc, etc.).

> Any proposal yourself?

I like MultiMarkdown. There is a decent C implementation. Not sure if the project would want to use such a thing.

https://github.com/fletcher/peg-multimarkdown

Probably too heavy-weight. Another option is to adopt something like libsoldout (née libupskirt, http://fossil.instinctive.eu/libsoldout/) or one of its forks, e.g., sundown (https://github.com/vmg/sundown).

But I am not so attached to any one solution (except SGML, pretty sure no one wants that to be part of the pg distribution, and is hateful to edit, anyway). I'd just like something, so I can tell users to just `man $extension` after installing.

Best,

David