Re: Documentation and explanatory diagrams

Rafael Martinez wrote:
> Sorry for the delay, I got finally some extra time to work on this.
>
> I am sending you a proposal with 13 diagrams to include in the manual so
> we can get an idea of how it will be. If it gets approved I will spend
> more time creating and including other diagrams and improving the build
> process for including figures into the manual.

Great!

> I have done this:
>
> - - Create/convert 13 images with/to DIA (v.0.96.1) and generate a PNG
> version of them.
> - - Patch the sgml files that will include the images under doc/src/sgml/.
> - - Patch the Makefile under doc/src/sgml/ so the images get move to
> doc/src/sgml/html/ under the generation of the html manual.

I have built an HTML version using your patch:

http://momjian.us/expire/pgsql-docs/

Here is a sample doc image:

http://momjian.us/expire/pgsql-docs/log-shipping-alternative.html

and all images appear here:

http://momjian.us/expire/pgsql-docs/img/

> I could test only the generation of the HTML version of the manual. I
> have had problems with the generation of the PDF version and I do not
> know at the moment if we have to ajust some of the images for the PDF
> version.

I think PDF will be fine. I can't generate PDF either but once it
committed to CVS I will have someone check and make adjustments.

> If this proposal gets accepted we should work with:
>
> - - Automatic generation of PNG files from DIA source under the build
> process of the manual.

I don't think we want to require dia to build the docs, so we are going
to keep the dia and png files in CVS.

> - - Testing of the PDF build process with images.
> - - Update the text some places to reference the figures.
> - - Automatic generation of a Table of Figures
> - - Create/convert more figures to include them in the manual.

Great.

> If you want to generate the html manual with these figures yourself, you
> have to do this in a 9.0beta2 source tree.:
>
> - - Untar the attached file pg_manual_figures.tar.gz under doc/src/sgml/.
> This will create an img/ directory with the DIA and PNG files versions
> of the figures.
>
> - - Patch the 9.0beta2 source tree with the attached file
> 9.0beta2_pg_manual_figures.patch (patch -p0 -i
> 9.0beta2_pg_manual_figures.patch)
>
> - - Delete the file doc/src/sgml/html-stamp and run make in doc/src/sgml/
>
> Well, I will await for your feedback before spending more time on this
> just in case I am in the wrong path.

I did adjust the file paths sightly and modified the makefile; new
patch attached.

I did remove the vacuum_full image because the 9.0 vacuum full rewrites
the table, rather than modifying it in place.

Also, there are two images that need to be updated for every major
release; is that something we want to commit to doing?

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ None of us is going to be here forever. +