Thread: Shipping documentation untarred
So the next step to documentation bliss is to get rid of the man.tar.gz and postgres.tar.gz tarballs that are shipped inside the tarball. These are historical artifacts from the era when building the documentation for release required manual interference, and that era ended yesterday at the latest. Here is how I would like to set this up: * Man pages are built into doc/src/sgml/man1 and doc/src/sgml/man7. This is already happening. * HTML files are built into doc/src/sgml/html. On installation, we just copy that directory. * In doc/src/sgml/Makefile, put distprep: man html so that both documentation formats are built when the tarball is built. An added twist is that derived files that are shipped in the release tarball must be built in the source directory, not in the build directory (cf. gram.c etc.). This is not a problem with a few options on the respective tools (famous last words ...), but I just want to warn about it. If people would find this behavior too weird for their personal development workflow, we could add another target or other option to get the behavior you want. Let me know.
On Wed, Aug 5, 2009 at 09:24, Peter Eisentraut<peter_e@gmx.net> wrote: > So the next step to documentation bliss is to get rid of the man.tar.gz and > postgres.tar.gz tarballs that are shipped inside the tarball. These are > historical artifacts from the era when building the documentation for release > required manual interference, and that era ended yesterday at the latest. > > Here is how I would like to set this up: > > * Man pages are built into doc/src/sgml/man1 and doc/src/sgml/man7. This is > already happening. > > * HTML files are built into doc/src/sgml/html. On installation, we just copy > that directory. > > * In doc/src/sgml/Makefile, put > > distprep: man html > > so that both documentation formats are built when the tarball is built. Just to verify, there is not going to be any changes in the actual format of the generated files, right? Since we pre-parse those before we load them on the website, we'd have to change the loader in that case. -- Magnus HaganderMe: http://www.hagander.net/Work: http://www.redpill-linpro.com/
On Wednesday 05 August 2009 16:13:48 Magnus Hagander wrote: > Just to verify, there is not going to be any changes in the actual > format of the generated files, right? Correct.
Peter Eisentraut wrote: > So the next step to documentation bliss is to get rid of the man.tar.gz and > postgres.tar.gz tarballs that are shipped inside the tarball. These are > historical artifacts from the era when building the documentation for release > required manual interference, and that era ended yesterday at the latest. > > Here is how I would like to set this up: > > * Man pages are built into doc/src/sgml/man1 and doc/src/sgml/man7. This is > already happening. > > * HTML files are built into doc/src/sgml/html. On installation, we just copy > that directory. > > * In doc/src/sgml/Makefile, put Are you sure you don't want the results in doc/src/man1 and doc/src/html? Or even doc/man1 and doc/html? -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
On Monday 10 August 2009 18:43:26 Bruce Momjian wrote: > Are you sure you don't want the results in doc/src/man1 and > doc/src/html? Or even doc/man1 and doc/html? I am in fact not sure, but people are used to working on doc/src/sgml, so keeping the main action there seemed reasonable. If we ever change VCS, we can move this stuff around and cut out a few directory levels.
Peter Eisentraut wrote: > On Monday 10 August 2009 18:43:26 Bruce Momjian wrote: > > Are you sure you don't want the results in doc/src/man1 and > > doc/src/html? Or even doc/man1 and doc/html? > > I am in fact not sure, but people are used to working on doc/src/sgml, so > keeping the main action there seemed reasonable. If we ever change VCS, we > can move this stuff around and cut out a few directory levels. I understand that the placement of the generated docs in the sourcedir instead of the builddir is so that it is included in the tarball, correct? I admit I was surprised by that change. -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support
On Monday 10 August 2009 21:53:57 Alvaro Herrera wrote: > I understand that the placement of the generated docs in the sourcedir > instead of the builddir is so that it is included in the tarball, > correct? I admit I was surprised by that change. I did point that out upthread, with you in particular in mind. ;-) I've been thinking that we could actually get rid of that build-in-srcdir behavior, which also occasionally puzzles vpath users with respect to gram.c and so on. The new behavior would be to build targets in the local directory. The only requirement would be that distribution tarballs be built in-tree, so that the stuff that is distprep'ed actually ends up in the tarball, but I think that should not be a problem.
Peter Eisentraut <peter_e@gmx.net> writes:
> I've been thinking that we could actually get rid of that build-in-srcdir
> behavior, which also occasionally puzzles vpath users with respect to gram.c
> and so on. The new behavior would be to build targets in the local directory.
> The only requirement would be that distribution tarballs be built in-tree, so
> that the stuff that is distprep'ed actually ends up in the tarball, but I
> think that should not be a problem.
I think one of the arguments for the current behavior is that the
derived files are platform-independent, so this way saves work if you
are building several sets of binaries from the same source tree.
However, I don't know of anyone actively making use of that behavior
--- and if they did want to, they'd likely use a tarball not a CVS
pull anyway.
Having all the derived files in the build directory definitely seems
to me to reduce the complexity and surprise factor, so +1 for changing.
regards, tom lane
On Tuesday 11 August 2009 17:02:01 Tom Lane wrote: > Having all the derived files in the build directory definitely seems > to me to reduce the complexity and surprise factor, so +1 for changing. I've looked at that briefly, and it's a bit more complicated than it would appear. I will figure this out later, but it's not going to happen this week.
On tis, 2009-08-11 at 12:42 +0300, Peter Eisentraut wrote: > I've been thinking that we could actually get rid of that build-in-srcdir > behavior, which also occasionally puzzles vpath users with respect to gram.c > and so on. The new behavior would be to build targets in the local directory. > The only requirement would be that distribution tarballs be built in-tree, so > that the stuff that is distprep'ed actually ends up in the tarball, but I > think that should not be a problem. I have implemented this approach now.