Documentation improvement

[vitcpp]

There are some proposed tasks:

• Use postgresql style sheets and makefiles to generate the doc.
• Improve the formatting of sgm files in according to the postgresql approach.
• Remove empty sections with "tbw" (to be written).
• Remove release notes from the doc.
• Improve the structure of the doc.

[vitcpp]

Prepared PR #63 that replaces openjade/latex tools with fop.

The PR also introduces some more changes:

• The version propagation into the user manual.
• Fixed some greek alphabet's symbols in pdf.
• Removed some empty sections and release nodes from the user manual.

To compile the doc the same tools should be installed as for postgresql (https://www.postgresql.org/docs/current/docguide-toolsets.html).

@msdemlei, @esabol, @df7cb: Could you please be so kind to consider this PR?

Thank you in advance.

[vitcpp]

TODO from @msdemlei: Finally, I'm not sure if we want to smuggle such a change in here, but since I ran into it during review: sect. 2.2 says "You will need PostgreSQL 9.1 or above." almost certainly is wrong these days. Perhaps we can say "The minimal postgres version for any given pgsphere version can be found at xy" (where I'm not sure what "xy" would be at this point)? Or just drop the sentence entirely on grounds that it will probably always under-updated and no information is better than wrong information?

[esabol]

TODO: I think it would be a good to have a GitHub Action that generates the HTML documentation whenever there's a change merged/pushed to the master branch and then publishes the generated HTML to GitHub Pages. Something like this:

https://gist.github.com/MichaelCurrin/a698731096f78240f653faf9a9127cba

https://github.com/marketplace/actions/deploy-to-github-pages

https://github.com/marketplace/actions/github-pages

[esabol]

TODO: There are two (different) instances of the incorrect minimum supported PostgreSQL version in the documentation:

https://github.com/postgrespro/pgsphere/blob/fb93eb40c8c17f5bbfec66b7578cbbf79277d756/doc/appendixes.sgm#L39

https://github.com/postgrespro/pgsphere/blob/fb93eb40c8c17f5bbfec66b7578cbbf79277d756/doc/install.sgm#L22

These both need to be updated to reflect the current minimum (10.0?).

I suppose one could define a variable for this in Makefile.common.mk and populate the value in the documentation in the same fashion as PGSPHERE_VERSION.

The only other instance of this minimum supported PostrgeSQL version is in the README.pg_sphere file, I think.

[vitcpp]

@esabol I temporary removed appendixes.sgm from the doc. This file is skipped in doc generation now. I propose to remote release notes from the doc because they are already shown on the github page.

In my last PR I also removed minimal version from the install.sgm as @msdemlei suggested. I think it is a reasonable compromise. In my opinion, we should try to support all the versions if needed if it reasonable and doesn't complicate the development process significantly.

[vitcpp]

I also would like to reformat the sources the same way as in the postgresql (identation with 1 space). It allows to place more text on the line. I'm going to prepare a separate PR with only changes in the format, if no objections.

The example from postgres: https://github.com/postgres/postgres/blob/master/doc/src/sgml/advanced.sgml

[vitcpp]

One more suggestion is to put all doc rules into the top level makefile and to remove doc/Makefile and Makefile.common.mk. It allows to have the only Makefile and to utilize postgres doc installlation functionality (via DOCS variable). Now, there is README.pg_sphere and COPYRIGHT.pg_sphere are only installed when using make install. There are some difficulties to install pdf or html when doc rules are in a separate Makefile.

[esabol]

@vitcpp wrote:

In my last PR I also removed minimal version from the install.sgm as @msdemlei suggested. I think it is a reasonable compromise.

Oh, I didn't notice it had been removed in that PR. Well, never mind then.