Folks,
Attached is a patch for runtime.sgml. It provides a long-needed (in my view)
list of which runtime settings are most important to a first-time PG setup.
I'm starting to go through the settings documentation to make them clearer to
the novice. Here's an example of what I plan to do to each entry:
<varlistentry id="guc-effective-cache-size"
xreflabel="effective_cache_size">
<term><varname>effective_cache_size</varname> (<type>floating
point</type>)</term>
<listitem>
<para>Default: 1000</para>
<para>Set At: runtime (per connection)</para>
<para>Unit: disk pages (typically 8192 bytes)</para>
<para>Description: Sets the planner's assumption about the effective
size of the
disk cache (that is, the portion of the kernel's disk cache
that will be used for <productname>PostgreSQL</productname>
data files).
</para>
<para>Recommendations: Set this to 3/4 of the available RAM on your
server (RAM not dedicated to other applications)</para>
</listitem>
</varlistentry>
While most of this data is already available in the text, I feel that breaking
each dictionary entry out into 5 sections (Default, Set At, Unit/Options,
Description, and Recommendations) greatly improves the readability of the
file.
Are there any objections to this before I spend a lot of time on it? Are the
better tags I could use than a simple <para>? One person suggested a
segmentedlist, but I'm a bit reluctant to nest a segmentedlist inside a
varlist.
--
--Josh
Josh Berkus
Aglio Database Solutions
San Francisco
