Re: Documentation and explanatory diagrams

Bruce Momjian <bruce@momjian.us> writes:

Rafael Martinez wrote:

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!

Where are the DIA sources for these? It's impossible to evaluate how
maintainable these will be without seeing the source code.

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.

Yeah, probably, at least for the first go-round.

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

-1 on that. The timeline thing is *certainly* not worth the maintenance
effort, if indeed it even belongs in the docs at all (it looks more like
marketing material). I think the lines-of-code diagram is not worth its
keep either.

One minor comment is that the page_layout diagram should say BLCKSZ not
8K, and the different-colored arrows in it don't really convey much ---
they need on-image labeling I think.

regards, tom lane

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

Rafael Martinez wrote:

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!

Where are the DIA sources for these? It's impossible to evaluate how
maintainable these will be without seeing the source code.

OK, I put the dia sources online:

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

They are XML files.

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

-1 on that. The timeline thing is *certainly* not worth the maintenance
effort, if indeed it even belongs in the docs at all (it looks more like
marketing material). I think the lines-of-code diagram is not worth its
keep either.

Sure, I can remove them, unless someone else wants to argue for their
inclusion.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Bruce Momjian wrote:

Rafael Martinez wrote:

[........]

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.

You use cp $(srcdir)/img/png/*.png html/img/ in the Makefile but in the
<imagedata fileref=""> tags the images are under html/. Am I missing
anything?

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

Good, I found this out after I sent you all the images.

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

Ok, I agree with you and Tom. They are not difficult to maintain but
they are more marketing material than technical.

If we go ahead with having explanatory diagrams, how do you want me to
send you new/updated diagrams (src&png)? Last time I try to send a large
attachment to the list, the e-mail was not deliver to the list. Maybe I
can make them available via an URL.

- --
Rafael Martinez, <r.m.guerrero@usit.uio.no>
Center for Information Technology Services
University of Oslo, Norway

PGP Public Key: http://folk.uio.no/rafael/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkws6GIACgkQBhuKQurGihTzVACfa3VUeZJtJ9WXotGG8cTNWnDd
30IAnRwyOZVNthzi+DkbvvGbMaNVk4KQ
=0gQ8
-----END PGP SIGNATURE-----

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Tom Lane wrote:

One minor comment is that the page_layout diagram should say BLCKSZ not
8K, and the different-colored arrows in it don't really convey much ---
they need on-image labeling I think.

ack. I will update this image with these changes.

- --
Rafael Martinez, <r.m.guerrero@usit.uio.no>
Center for Information Technology Services
University of Oslo, Norway

PGP Public Key: http://folk.uio.no/rafael/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkws6HEACgkQBhuKQurGihRGOwCgjdwP2VbDsMR/knX1eHLNMw+y
PNcAnRhhFaXjGVAS1nkJcOuaVUFHW9QE
=GutE
-----END PGP SIGNATURE-----

Excerpts from Rafael Martinez's message of jue jul 01 15:11:31 -0400 2010:

If we go ahead with having explanatory diagrams, how do you want me to
send you new/updated diagrams (src&png)? Last time I try to send a large
attachment to the list, the e-mail was not deliver to the list. Maybe I
can make them available via an URL.

I think we should have a Makefile rule to build the PNGs from the source
dia files; this seems absent from this patch. (This means you shouldn't
send PNG files around.)

I'm not sure if this means that we don't want to have the PNG files in
our SCM though, because it'd make the doc unbuildable for those without
access to dia.

Rafael Martinez wrote:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Bruce Momjian wrote:

Rafael Martinez wrote:

[........]

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.

You use cp $(srcdir)/img/png/*.png html/img/ in the Makefile but in the
<imagedata fileref=""> tags the images are under html/. Am I missing
anything?

I will need to adjust that before I apply the patch. I had not decided
on a directory structure yet. I am thinking of using simply /dia and
/png directories so we don't have to create an img/png directory in the
HTML, which would look odd.

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

Ok, I agree with you and Tom. They are not difficult to maintain but
they are more marketing material than technical.

If we go ahead with having explanatory diagrams, how do you want me to
send you new/updated diagrams (src&png)? Last time I try to send a large
attachment to the list, the e-mail was not deliver to the list. Maybe I
can make them available via an URL.

Sure, or just email it to me and I will handle it.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

Alvaro Herrera wrote:

Excerpts from Rafael Martinez's message of jue jul 01 15:11:31 -0400 2010:

If we go ahead with having explanatory diagrams, how do you want me to
send you new/updated diagrams (src&png)? Last time I try to send a large
attachment to the list, the e-mail was not deliver to the list. Maybe I
can make them available via an URL.

I think we should have a Makefile rule to build the PNGs from the source
dia files; this seems absent from this patch. (This means you shouldn't
send PNG files around.)

I'm not sure if this means that we don't want to have the PNG files in
our SCM though, because it'd make the doc unbuildable for those without
access to dia.

Yeah, it would be nice to have a rule, but we also should have the PNG
files in our CVS.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

On tor, 2010-07-01 at 19:10 -0400, Alvaro Herrera wrote:

I'm not sure if this means that we don't want to have the PNG files in
our SCM though, because it'd make the doc unbuildable for those
without access to dia.

Is there something that makes installing dia more challenging than the
other documentation build tools?

Peter Eisentraut wrote:

On tor, 2010-07-01 at 19:10 -0400, Alvaro Herrera wrote:

I'm not sure if this means that we don't want to have the PNG files in
our SCM though, because it'd make the doc unbuildable for those
without access to dia.

Is there something that makes installing dia more challenging than the
other documentation build tools?

No, but it is an additional requirement for diagrams that will rarely
change.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

On tor, 2010-07-01 at 22:08 -0400, Bruce Momjian wrote:

Peter Eisentraut wrote:

On tor, 2010-07-01 at 19:10 -0400, Alvaro Herrera wrote:

I'm not sure if this means that we don't want to have the PNG files in
our SCM though, because it'd make the doc unbuildable for those
without access to dia.

Is there something that makes installing dia more challenging than the
other documentation build tools?

No, but it is an additional requirement for diagrams that will rarely
change.

I dispute that the diagrams will/should rarely change, and also that
changing rarely is an acceptable criterion for breaking the build
system.

Excerpts from Peter Eisentraut's message of jue jul 01 21:52:00 -0400 2010:

On tor, 2010-07-01 at 19:10 -0400, Alvaro Herrera wrote:

I'm not sure if this means that we don't want to have the PNG files in
our SCM though, because it'd make the doc unbuildable for those
without access to dia.

Is there something that makes installing dia more challenging than the
other documentation build tools?

Err, I dunno -- it's just an apt-get away for me, but what will Tom say
when it doesn't work on his ancient HP-UX 10.20 system?

Alvaro Herrera <alvherre@commandprompt.com> writes:

Excerpts from Peter Eisentraut's message of jue jul 01 21:52:00 -0400 2010:

Is there something that makes installing dia more challenging than the
other documentation build tools?

Err, I dunno -- it's just an apt-get away for me, but what will Tom say
when it doesn't work on his ancient HP-UX 10.20 system?

I don't try to build the docs on that box anyway --- it does have
openjade but such an old version that they don't build. In practice
building the docs already takes much more modern infrastructure than
compiling the source code; and besides there are many fewer people
who care about doing it.

A more interesting question is whether Marc can install a working
version of dia on whatever he uses to wrap the tarballs.

regards, tom lane

On Fri, 2 Jul 2010, Tom Lane wrote:

Alvaro Herrera <alvherre@commandprompt.com> writes:

Excerpts from Peter Eisentraut's message of jue jul 01 21:52:00 -0400 2010:

Is there something that makes installing dia more challenging than the
other documentation build tools?

Err, I dunno -- it's just an apt-get away for me, but what will Tom say
when it doesn't work on his ancient HP-UX 10.20 system?

I don't try to build the docs on that box anyway --- it does have
openjade but such an old version that they don't build. In practice
building the docs already takes much more modern infrastructure than
compiling the source code; and besides there are many fewer people
who care about doing it.

A more interesting question is whether Marc can install a working
version of dia on whatever he uses to wrap the tarballs.

that shouldn't be an issue ... Peter runs an update every 3 hours on that
machine right now as it is ...

Marc G. Fournier Hub.Org Hosting Solutions S.A.
scrappy@hub.org http://www.hub.org

Yahoo:yscrappy Skype: hub.org ICQ:7615664 MSN:scrappy@hub.org

tgl@sss.pgh.pa.us (Tom Lane) writes:

Alvaro Herrera <alvherre@commandprompt.com> writes:

Excerpts from Peter Eisentraut's message of jue jul 01 21:52:00 -0400 2010:

Is there something that makes installing dia more challenging than the
other documentation build tools?

Err, I dunno -- it's just an apt-get away for me, but what will Tom say
when it doesn't work on his ancient HP-UX 10.20 system?

I don't try to build the docs on that box anyway --- it does have
openjade but such an old version that they don't build. In practice
building the docs already takes much more modern infrastructure than
compiling the source code; and besides there are many fewer people
who care about doing it.

A more interesting question is whether Marc can install a working
version of dia on whatever he uses to wrap the tarballs.

Good news... It's not terribly difficult to use command line usage to
get dia to export .png files.

{wrox} dia --export=transport.png Transports.dia
Transports.dia --> transport.png
{wrox} file Transports.dia transport.png
Transports.dia: gzip compressed data, from Unix
transport.png: PNG image data, 753 x 774, 8-bit/color RGBA, non-interlaced

So the makefile rule is pretty much:
%.png : %.dia; dia --export=$@ $<

I'll observe that while dia claims to be able to export in JPEG form,
it doesn't necessarily work:

{wrox} dia --export=transport.jpg Transports.dia

** (dia:946): CRITICAL **: dia error: do not know how to export into transport.jpg

If we have a preference for JPEG, then that's presumably an
ImageMagick run away...
--
output = ("cbbrowne" "@" "gmail.com")
http://linuxdatabases.info/info/languages.html
HEADLINE: Suicidal twin kills sister by mistake!

Tom Lane wrote:

Alvaro Herrera <alvherre@commandprompt.com> writes:

Excerpts from Peter Eisentraut's message of jue jul 01 21:52:00 -0400 2010:

Is there something that makes installing dia more challenging than the
other documentation build tools?

Err, I dunno -- it's just an apt-get away for me, but what will Tom say
when it doesn't work on his ancient HP-UX 10.20 system?

I don't try to build the docs on that box anyway --- it does have
openjade but such an old version that they don't build. In practice
building the docs already takes much more modern infrastructure than
compiling the source code; and besides there are many fewer people
who care about doing it.

A more interesting question is whether Marc can install a working
version of dia on whatever he uses to wrap the tarballs.

One more issue is that the dia and png files are going to impact our
download sizes:

526k ./dia
483k ./png

If we generate the png from the dia files, we are looking at increasing
the source download by 526k and the binary downloads by 483k for all
existing images and, of course, as we add images, these sizes will
increase.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

On Fri, 2 Jul 2010, Bruce Momjian wrote:

Tom Lane wrote:

Alvaro Herrera <alvherre@commandprompt.com> writes:

Excerpts from Peter Eisentraut's message of jue jul 01 21:52:00 -0400 2010:

Is there something that makes installing dia more challenging than the
other documentation build tools?

Err, I dunno -- it's just an apt-get away for me, but what will Tom say
when it doesn't work on his ancient HP-UX 10.20 system?

I don't try to build the docs on that box anyway --- it does have
openjade but such an old version that they don't build. In practice
building the docs already takes much more modern infrastructure than
compiling the source code; and besides there are many fewer people
who care about doing it.

A more interesting question is whether Marc can install a working
version of dia on whatever he uses to wrap the tarballs.

One more issue is that the dia and png files are going to impact our
download sizes:

526k ./dia
483k ./png

If we generate the png from the dia files, we are looking at increasing
the source download by 526k and the binary downloads by 483k for all
existing images and, of course, as we add images, these sizes will
increase.

Which brings me to a point I brought up before ... do we want to start
looking at a dist file split similar to what Devrim does for packages?
lib vs client vs server vs docs vs ... ? where each could be invididually
built, or requires a prev set (ie. client would require lib first) sort of
thing ...

----
Marc G. Fournier Hub.Org Hosting Solutions S.A.
scrappy@hub.org http://www.hub.org

Yahoo:yscrappy Skype: hub.org ICQ:7615664 MSN:scrappy@hub.org

Marc G. Fournier wrote:

On Fri, 2 Jul 2010, Tom Lane wrote:

Alvaro Herrera <alvherre@commandprompt.com> writes:

Excerpts from Peter Eisentraut's message of jue jul 01 21:52:00 -0400 2010:

Is there something that makes installing dia more challenging than the
other documentation build tools?

Err, I dunno -- it's just an apt-get away for me, but what will Tom say
when it doesn't work on his ancient HP-UX 10.20 system?

I don't try to build the docs on that box anyway --- it does have
openjade but such an old version that they don't build. In practice
building the docs already takes much more modern infrastructure than
compiling the source code; and besides there are many fewer people
who care about doing it.

A more interesting question is whether Marc can install a working
version of dia on whatever he uses to wrap the tarballs.

that shouldn't be an issue ... Peter runs an update every 3 hours on that
machine right now as it is ...

OK, everyone seems to like requiring dia. I wasn't sure how popular dia
was. One hack solution to allow builds without dia would be to create a
Makefile rule that creates empty PNG files to match the dia files.

Can someone provide the command-line to build the PNG files from the DIA
files?

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

On Fri, Jul 2, 2010 at 5:28 PM, Bruce Momjian <bruce@momjian.us> wrote:

OK, everyone seems to like requiring dia.

I don't like it a bit. It's hard enough for people to build the docs as it is.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company

On Fri, 2 Jul 2010, Robert Haas wrote:

On Fri, Jul 2, 2010 at 5:28 PM, Bruce Momjian <bruce@momjian.us> wrote:

OK, everyone seems to like requiring dia.

I don't like it a bit. It's hard enough for people to build the docs as
it is.

Why should anyone build the docs? Its part of the tarball process, so the
only ppl that should be doing it are those coming from CVS, no ... ?

----
Marc G. Fournier Hub.Org Hosting Solutions S.A.
scrappy@hub.org http://www.hub.org

Yahoo:yscrappy Skype: hub.org ICQ:7615664 MSN:scrappy@hub.org