Обсуждение: docs: config chapter
This patch moves the documentation of the configuration parameters into a separate chapter; it was formerly a section in the "Server Run-time Environment" chapter. This is per earlier discussion. Because of the volume of SGML being moved, the patch is fairly large (~360KB uncompressed), but very boring. The patch is here: http://neilc.treehou.se/config_sgml_breakout-6.patch.gz Barring any objections, I'd like to apply this later tonight or tomorrow, before the tree drifts. -Neil
Neil Conway wrote: > Barring any objections, I'd like to apply this later tonight or > tomorrow, before the tree drifts. We are in beta; the time for major reorganizations has passed. Moreover, I don't agree with the premise. Could you point to the discussion? -- Peter Eisentraut http://developer.postgresql.org/~petere/
Peter Eisentraut wrote: > We are in beta; the time for major reorganizations has passed. This is not a major reorganization. In any case, the primary reason to avoid major reorganizations during beta is the risk of regressions, which does not really apply here. > Moreover, I don't agree with the premise. Could you point to the > discussion? http://archives.postgresql.org/pgsql-docs/2004-11/msg00029.php -Neil
Peter Eisentraut <peter_e@gmx.net> writes: > Neil Conway wrote: >> Barring any objections, I'd like to apply this later tonight or >> tomorrow, before the tree drifts. > We are in beta; the time for major reorganizations has passed. That would be a valid objection to a code reorganization, but I don't see that it applies to documentation. Indeed, personally I tend to do most of my major editorial work on the docs during beta, because all the rest of the time I'm too busy hacking code. I don't really want a policy that says "you can't work on the docs during beta". [ Of course this point is independent of the merits, if any, of this particular proposal. ] regards, tom lane
Neil Conway <neilc@samurai.com> writes: > Peter Eisentraut wrote: >> Moreover, I don't agree with the premise. Could you point to the >> discussion? > http://archives.postgresql.org/pgsql-docs/2004-11/msg00029.php As far as I could tell by eyeball, you are simply moving the section out to be a separate chapter and a separate file, without changing any text? This was agreed to in the above thread (or at least no one objected), but I thought we'd also agreed to provide some sort of alphabetical list of the config parameters, perhaps similar to the table at the front of the "System Catalogs" chapter. I don't agree with some of the more radical suggestions in that thread, such as one-page-per-config-variable, but the alpha index seemed to meet with everyone's approval. regards, tom lane
Tom Lane wrote: > As far as I could tell by eyeball, you are simply moving the section out > to be a separate chapter and a separate file, without changing any text? Sorry, I should have noted that explicitly in my original email. The vast majority of the patch is just moving the same text to a separate file and chapter, and then fixing the resulting fallout. I also tweaked a few areas in the text where appropriate ("This subsection" -> "This section" and similar). > This was agreed to in the above thread (or at least no one objected), > but I thought we'd also agreed to provide some sort of alphabetical list > of the config parameters, perhaps similar to the table at the front of > the "System Catalogs" chapter. Oh, there is definitely room for more improvement on this front -- Josh has some concrete ideas for changes he wants to make, I believe. I just submitted this to get it into the tree so that subsequent patches will be easier to review and less likely to drift. -Neil
Peter Eisentraut wrote: > Moreover, I don't agree with the premise. This patch is blocking other work. If you still object to it, can you elaborate why? Otherwise I'll apply it this evening (EST). -Neil
Neil Conway wrote: > This patch is blocking other work [...] > Otherwise I'll apply it this evening (EST). Applied. -Neil