Thread: 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