Thread: pgAdmin Documentation
Hi, I've been thinking about trying to sort out the documentation included in pgAdmin. As you know, we currently bundle both the PostgreSQL and Slony docs with pgAdmin - what you may not know is that integrating these together at build time is a real pain, not to mention that those docs account for a major percentage of the number of files in our subversion repository, tarballs and Unix builds, and are also a fair percentage of the total size. There are at least a couple of options: 1) Leave things as they are, maybe attempt to script some of the build tasks. 2) Un-bundle the PostgreSQL and Slony docs. Allow the user to select a directory, CHM file, or website for each of these (we already allow a website to be selected for the PostgreSQL docs). This has the additional advantage that the user can use the docs for their server/slony version, rather than the ones we bundle. If we were to do the latter, in the Windows Installer for PostgreSQL (which we also need to consider, because it relies on our bundled docs), we would just build the CHM files for each of the three packages, without trying to merge them together. Thoughts? Regards, Dave
On Wed, May 16, 2007 at 12:15:06PM +0100, Dave Page wrote: > Hi, > > I've been thinking about trying to sort out the documentation included > in pgAdmin. As you know, we currently bundle both the PostgreSQL and > Slony docs with pgAdmin - what you may not know is that integrating > these together at build time is a real pain, not to mention that those > docs account for a major percentage of the number of files in our > subversion repository, tarballs and Unix builds, and are also a fair > percentage of the total size. > > There are at least a couple of options: > > 1) Leave things as they are, maybe attempt to script some of the build > tasks. > > 2) Un-bundle the PostgreSQL and Slony docs. Allow the user to select a > directory, CHM file, or website for each of these (we already allow a > website to be selected for the PostgreSQL docs). This has the additional > advantage that the user can use the docs for their server/slony version, > rather than the ones we bundle. > > If we were to do the latter, in the Windows Installer for PostgreSQL > (which we also need to consider, because it relies on our bundled docs), > we would just build the CHM files for each of the three packages, > without trying to merge them together. I think 2 is good, provided that the windows installer (or RPM packages or whatever is used on Mac) can be configured to pick up something by default. So that I don't have to figure out where my pg docs are if I just installed the bundle. We do get questions about pginstaller why we always include pgadmin docs, which would also be solved as a side-effect of this :-) Does this affect searching in help in a bad way? //Magnus
Magnus Hagander wrote:
> I think 2 is good, provided that the windows installer (or RPM packages
> or whatever is used on Mac) can be configured to pick up something by
> default. So that I don't have to figure out where my pg docs are if I just
> installed the bundle.
OK, here's what I'm thinking.
1) Add configuration options for pgAdmin, PostgreSQL, EnterpriseDB and
Slony helpfiles.
2) At startup, if any of those options are empty, search a set of local
directories for the helpfiles:
- On Windows only, look for CHM files first;
- $INSTDIR/Docs/$LANG/pgadmin3.chm (and postgresql.chm etc)
- $INSTDIR/Docs/en_US/pgadmin3.chm
- $INSTDIR/Docs/pgadmin3.chm
- $INSTDIR/pgadmin3.chm
In addition, we look for postgresql.chm & slony.chm in the
appropriate directory relative to the pg_dump directory, likewise the
equivalent for enterprisedb.chm.
- On other platforms (and Windows if we haven't got this far), we
look for postgresql.hhp in the appropriate directory relative to the
pg_dump directory, likewise the equivalent for enterprisedb.hhp.
- For those paths we still haven't satisfied, we look in the same
places as per the previous step for index.html files.
- Finally, we fall back to websites -
http://www.pgadmin.org/docs/current/,
http://www.postgresql.org/docs/current/static/ and so on.
3) When the user views a helpfile, if it's a Slony or pgAdmin page, just
use the appropriate path, if it's a DBMS page, use the PostgreSQL or
EnterpriseDB path as appropriate;
- if it's a CHM file, we launch MS HTML Help viewer using
wxCHMHelpController
- else if it's an hhp file, we launch the wx viewer using
wxHtmlHelpController
- else we launch the default web browser and pass it the html file,
or URL to open.
How does that sound?
> We do get questions about pginstaller why we always include pgadmin docs,
> which would also be solved as a side-effect of this :-)
Yeah.
> Does this affect searching in help in a bad way?
Shouldn't do. For CHM or HHP it'll be as it is now. For HTML there willl
be no search, for web, there's the search engine on the site used
(assuming there is one).
Regards, Dave.
Dave Page a écrit : > I've been thinking about trying to sort out the documentation included > in pgAdmin. As you know, we currently bundle both the PostgreSQL and > Slony docs with pgAdmin - what you may not know is that integrating > these together at build time is a real pain, not to mention that those > docs account for a major percentage of the number of files in our > subversion repository, tarballs and Unix builds, and are also a fair > percentage of the total size. > > There are at least a couple of options: > > 1) Leave things as they are, maybe attempt to script some of the build > tasks. > > 2) Un-bundle the PostgreSQL and Slony docs. Allow the user to select a > directory, CHM file, or website for each of these (we already allow a > website to be selected for the PostgreSQL docs). This has the additional > advantage that the user can use the docs for their server/slony version, > rather than the ones we bundle. > There's one more advantage to this method : we can use a translated manual. > If we were to do the latter, in the Windows Installer for PostgreSQL > (which we also need to consider, because it relies on our bundled docs), > we would just build the CHM files for each of the three packages, > without trying to merge them together. > > Thoughts? > I would definitly vote for option 2. -- Guillaume. <!-- http://abs.traduc.org/ http://lfs.traduc.org/ http://docs.postgresqlfr.org/ -->
From: "Guillaume Lelarge" >> If we were to do the latter, in the Windows Installer for PostgreSQL >> (which we also need to consider, because it relies on our bundled docs), >> we would just build the CHM files for each of the three packages, >> without trying to merge them together. >> >> Thoughts? >> > > I would definitly vote for option 2. I also think of with you.! There were some discussions about the content of a Japanese document before. It has already had a Japanese version of PostgreSQL and Slony. Then, It is very huge. Moreover, timing in which Fix was up to date done had the problem that release and synchronization were not able to be taken. I'm very huge the translation work, and think that an important mission of team work. There is a special team in Japan PostgreSQL Users Group.!! I hope to act in the specific place emphasized it as each country. P.S) leader of document translation team in Japan. honda@postgresql.jp Regards, Hiroshi Saito
Guillaume Lelarge wrote: > Dave Page a écrit : >> I've been thinking about trying to sort out the documentation included >> in pgAdmin. As you know, we currently bundle both the PostgreSQL and >> Slony docs with pgAdmin - what you may not know is that integrating >> these together at build time is a real pain, not to mention that those >> docs account for a major percentage of the number of files in our >> subversion repository, tarballs and Unix builds, and are also a fair >> percentage of the total size. >> >> There are at least a couple of options: >> >> 1) Leave things as they are, maybe attempt to script some of the build >> tasks. >> >> 2) Un-bundle the PostgreSQL and Slony docs. Allow the user to select a >> directory, CHM file, or website for each of these (we already allow a >> website to be selected for the PostgreSQL docs). This has the >> additional advantage that the user can use the docs for their >> server/slony version, rather than the ones we bundle. >> > > There's one more advantage to this method : we can use a translated manual. In fairness you could anyway, either by pointing the relevant option to an online copy, or by including a translation in docs/fr_FR, but as Hiroshi notes in his email, that would hugely bloat the distribution. >> If we were to do the latter, in the Windows Installer for PostgreSQL >> (which we also need to consider, because it relies on our bundled >> docs), we would just build the CHM files for each of the three >> packages, without trying to merge them together. >> >> Thoughts? >> > > I would definitly vote for option 2. OK, well thats four of us thinking that way. Purely by chance I'm halfway through coding option 2 anyway, so I'll finish it off and hopefully commit later today :-) Cheers, Dave