Re: Can extension build own SGML document?

On 9/14/15 6:06 PM, Michael Paquier wrote:
> On Tue, Sep 15, 2015 at 6:01 AM, Alvaro Herrera wrote:
>> I think the only way upstream Postgres could offer this is as a way to
>> build a separate "book", i.e. not a chapter/section within the main
>> book. I think it would require huge complications in doc/src/sgml's
>> Makefile. Not sure it's worthwhile.

I'm not sure SGML is the way to go anymore anyways. Asciidoc offers a
lot of what our SGML does in a much easier to support toolchain. It's
also natively supported by github, which makes it nice for others to
view the output (see [1] as an exmaple). If asciidoc isn't powerful
enough for what you need you can switch to asciidoctor which is even
more powerful[2].

> I am not sure either, and as each project/developer have always
> different requirements I am convinced that this is going to be
> finished with enforced rules in Makefile rules for sure, so it is
> really unclear what would be the potential benefit to have a
> centralized facility. Take for example man pages, those should not be
> installed in share/doc/extension/ which is the default path, but in
> $(DESTDIR)$(mandir)/man1...

I do wish there was better infrastructure for creating extensions, but I
agree that the main project is not the way to handle that. There needs
to be more than just a Makefile you can include too. In particular, the
test framework is pretty ugly to deal with (unless you really like
wading through regress.c diff output...) Bumping extension versions,
creating distfiles and uploading to PGXN are also ripe for automation.

pgxn-utils makes an attempt at this by creating an extension template
for you to build from, but that's ultimately problematic because there's
no way to pull in improvements to the overall infrastructure (such as
how to create manpages). I think something you can pull in via a git
subtree might work better, at least for a makefile framework. I've been
meaning to create that but haven't found the time yet.

[1]
https://github.com/decibel/trunklet-format/blob/master/doc/trunklet-format.asc
[2] http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/
--
Jim Nasby, Data Architect, Blue Treble Consulting, Austin TX
Experts in Analytics, Data Architecture and PostgreSQL
Data in Trouble? Get it in Treble! http://BlueTreble.com