On Oct 25, 2012, at 10:42 AM, Simon Riggs <simon@2ndQuadrant.com> wrote:
>> Any plans to implement a documentation standard for extensions? I would love to see `make install` create the
necessaryman 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
generatingdocs 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
somethinglike 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`
afterinstalling.
Best,
David
