On Oct 25, 2012, at 5:07 PM, Peter Eisentraut <peter_e@gmx.net> wrote:
> I think the emerging standard is to have a README.md (or something
> similar). This gives enough structure and formatting options for most
> extensions.
For PGXN, I have used a README.md for a readme (briefly about the extension, how to build and install it), and a
doc/$extension.mdfile for documentation on the usage of the extension. Quite a few people put all of that into the
README,though.
> I don't think we need anything fancy to install and access the
> documentation. Most of the time it's on a server, in which case "less"
> would do a good job. To me, it's more important to have the
> documentation easily accessible over the internet for reference during
> development.
>
> That said, we do have a built-in documentation infrastructure, which is
> COMMENT. So an extension could have its documentation in its comment
> and the comments on its subordinate objects. This may or may not
> overlap with what a README would contain, but that depends on the
> situation, I think.
I think COMMENT is a bit lightweight for detailed documentation. I often write a lot of detail, including examples,
summarizations,tutorials, etc., not just brief explanations of what each object is.
Best,
David
