| 1 |
<!-- doc/src/sgml/docguide.sgml --> |
| 2 |
|
| 3 |
<appendix id="docguide"> |
| 4 |
<title>Documentation</title> |
| 5 |
|
| 6 |
<para> |
| 7 |
<productname>PostgreSQL</productname> has four primary documentation |
| 8 |
formats: |
| 9 |
|
| 10 |
<itemizedlist> |
| 11 |
<listitem> |
| 12 |
<para> |
| 13 |
Plain text, for pre-installation information |
| 14 |
</para> |
| 15 |
</listitem> |
| 16 |
<listitem> |
| 17 |
<para> |
| 18 |
<acronym>HTML</acronym>, for on-line browsing and reference |
| 19 |
</para> |
| 20 |
</listitem> |
| 21 |
<listitem> |
| 22 |
<para> |
| 23 |
PDF, for printing |
| 24 |
</para> |
| 25 |
</listitem> |
| 26 |
<listitem> |
| 27 |
<para> |
| 28 |
man pages, for quick reference. |
| 29 |
</para> |
| 30 |
</listitem> |
| 31 |
</itemizedlist> |
| 32 |
|
| 33 |
Additionally, a number of plain-text <filename>README</filename> files can |
| 34 |
be found throughout the <productname>PostgreSQL</productname> source tree, |
| 35 |
documenting various implementation issues. |
| 36 |
</para> |
| 37 |
|
| 38 |
<para> |
| 39 |
<acronym>HTML</acronym> documentation and man pages are part of a |
| 40 |
standard distribution and are installed by default. PDF |
| 41 |
format documentation is available separately for |
| 42 |
download. |
| 43 |
</para> |
| 44 |
|
| 45 |
<sect1 id="docguide-docbook"> |
| 46 |
<title>DocBook</title> |
| 47 |
<para> |
| 48 |
The documentation sources are written in |
| 49 |
<firstterm>DocBook</firstterm>, which is a markup language |
| 50 |
defined in <acronym>XML</acronym>. In what |
| 51 |
follows, the terms DocBook and <acronym>XML</acronym> are both |
| 52 |
used, but technically they are not interchangeable. |
| 53 |
</para> |
| 54 |
|
| 55 |
<para> |
| 56 |
<productname>DocBook</productname> allows an author to specify the |
| 57 |
structure and content of a technical document without worrying |
| 58 |
about presentation details. A document style defines how that |
| 59 |
content is rendered into one of several final forms. DocBook is |
| 60 |
maintained by the <ulink url="https://www.oasis-open.org"> |
| 61 |
OASIS group</ulink>. The <ulink url="https://www.oasis-open.org/docbook/"> |
| 62 |
official DocBook site</ulink> has good introductory and reference documentation and |
| 63 |
a complete O'Reilly book for your online reading pleasure. |
| 64 |
The <ulink url="https://www.freebsd.org/docproj/"> |
| 65 |
FreeBSD Documentation Project</ulink> also uses DocBook and has some good |
| 66 |
information, including a number of style guidelines that might be |
| 67 |
worth considering. |
| 68 |
</para> |
| 69 |
</sect1> |
| 70 |
|
| 71 |
|
| 72 |
<sect1 id="docguide-toolsets"> |
| 73 |
<title>Tool Sets</title> |
| 74 |
|
| 75 |
<para> |
| 76 |
The following tools are used to process the documentation. Some |
| 77 |
might be optional, as noted. |
| 78 |
|
| 79 |
<variablelist> |
| 80 |
<varlistentry id="docguide-toolsets-docbook-dtd"> |
| 81 |
<term><ulink url="https://www.oasis-open.org/docbook/">DocBook DTD</ulink></term> |
| 82 |
<listitem> |
| 83 |
<para> |
| 84 |
This is the definition of DocBook itself. We currently use version |
| 85 |
4.5; you cannot use later or earlier versions. You need |
| 86 |
the <acronym>XML</acronym> variant of the DocBook DTD, not |
| 87 |
the <acronym>SGML</acronym> variant. |
| 88 |
</para> |
| 89 |
</listitem> |
| 90 |
</varlistentry> |
| 91 |
|
| 92 |
<varlistentry id="docguide-toolsets-docbook-xsl"> |
| 93 |
<term><ulink url="https://github.com/docbook/wiki/wiki/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term> |
| 94 |
<listitem> |
| 95 |
<para> |
| 96 |
These contain the processing instructions for converting the |
| 97 |
DocBook sources to other formats, such as |
| 98 |
<acronym>HTML</acronym>. |
| 99 |
</para> |
| 100 |
|
| 101 |
<para> |
| 102 |
The minimum required version is currently 1.77.0, but it is recommended |
| 103 |
to use the latest available version for best results. |
| 104 |
</para> |
| 105 |
</listitem> |
| 106 |
</varlistentry> |
| 107 |
|
| 108 |
<varlistentry id="docguide-toolsets-libxml2"> |
| 109 |
<term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term> |
| 110 |
<listitem> |
| 111 |
<para> |
| 112 |
This library and the <command>xmllint</command> tool it contains are |
| 113 |
used for processing XML. Many developers will already |
| 114 |
have <application>Libxml2</application> installed, because it is also |
| 115 |
used when building the PostgreSQL code. Note, however, |
| 116 |
that <command>xmllint</command> might need to be installed from a |
| 117 |
separate subpackage. |
| 118 |
</para> |
| 119 |
</listitem> |
| 120 |
</varlistentry> |
| 121 |
|
| 122 |
<varlistentry id="docguide-toolsets-libxslt"> |
| 123 |
<term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term> |
| 124 |
<listitem> |
| 125 |
<para> |
| 126 |
<command>xsltproc</command> is an XSLT processor, that is, a program to |
| 127 |
convert XML to other formats using XSLT stylesheets. |
| 128 |
</para> |
| 129 |
</listitem> |
| 130 |
</varlistentry> |
| 131 |
|
| 132 |
<varlistentry id="docguide-toolsets-fop"> |
| 133 |
<term><ulink url="https://xmlgraphics.apache.org/fop/">FOP</ulink></term> |
| 134 |
<listitem> |
| 135 |
<para> |
| 136 |
This is a program for converting, among other things, XML to PDF. |
| 137 |
It is needed only if you want to build the documentation in PDF format. |
| 138 |
</para> |
| 139 |
</listitem> |
| 140 |
</varlistentry> |
| 141 |
</variablelist> |
| 142 |
</para> |
| 143 |
|
| 144 |
<para> |
| 145 |
We have documented experience with several installation methods for |
| 146 |
the various tools that are needed to process the documentation. |
| 147 |
These will be described below. There might be some other packaged |
| 148 |
distributions for these tools. Please report package status to the |
| 149 |
documentation mailing list, and we will include that information |
| 150 |
here. |
| 151 |
</para> |
| 152 |
|
| 153 |
<sect2 id="docguide-toolsets-inst-fedora-et-al"> |
| 154 |
<title>Installation on Fedora, RHEL, and Derivatives</title> |
| 155 |
|
| 156 |
<para> |
| 157 |
To install the required packages, use: |
| 158 |
<programlisting> |
| 159 |
yum install docbook-dtds docbook-style-xsl libxslt fop |
| 160 |
</programlisting> |
| 161 |
</para> |
| 162 |
</sect2> |
| 163 |
|
| 164 |
<sect2 id="docguide-toolsets-inst-freebsd"> |
| 165 |
<title>Installation on FreeBSD</title> |
| 166 |
|
| 167 |
<para> |
| 168 |
To install the required packages with <command>pkg</command>, use: |
| 169 |
<programlisting> |
| 170 |
pkg install docbook-xml docbook-xsl libxslt fop |
| 171 |
</programlisting> |
| 172 |
</para> |
| 173 |
|
| 174 |
<para> |
| 175 |
When building the documentation from the <filename>doc</filename> |
| 176 |
directory you'll need to use <command>gmake</command>, because the |
| 177 |
makefile provided is not suitable for FreeBSD's <command>make</command>. |
| 178 |
</para> |
| 179 |
</sect2> |
| 180 |
|
| 181 |
<sect2 id="docguide-toolsets-inst-debian"> |
| 182 |
<title>Debian Packages</title> |
| 183 |
|
| 184 |
<para> |
| 185 |
There is a full set of packages of the documentation tools |
| 186 |
available for <productname>Debian GNU/Linux</productname>. |
| 187 |
To install, simply use: |
| 188 |
<programlisting> |
| 189 |
apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop |
| 190 |
</programlisting> |
| 191 |
</para> |
| 192 |
</sect2> |
| 193 |
|
| 194 |
<sect2 id="docguide-toolsets-inst-macos"> |
| 195 |
<title>macOS</title> |
| 196 |
|
| 197 |
<para> |
| 198 |
If you use MacPorts, the following will get you set up: |
| 199 |
<programlisting> |
| 200 |
sudo port install docbook-xml docbook-xsl-nons libxslt fop |
| 201 |
</programlisting> |
| 202 |
If you use Homebrew, use this: |
| 203 |
<programlisting> |
| 204 |
brew install docbook docbook-xsl libxslt fop |
| 205 |
</programlisting> |
| 206 |
</para> |
| 207 |
|
| 208 |
<para> |
| 209 |
The Homebrew-supplied programs require the following environment variable |
| 210 |
to be set. For Intel based machines, use this: |
| 211 |
<programlisting> |
| 212 |
export XML_CATALOG_FILES=/usr/local/etc/xml/catalog |
| 213 |
</programlisting> |
| 214 |
On Apple Silicon based machines, use this: |
| 215 |
<programlisting> |
| 216 |
export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog |
| 217 |
</programlisting> |
| 218 |
Without it, <command>xsltproc</command> will throw errors like this: |
| 219 |
<programlisting> |
| 220 |
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd |
| 221 |
postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" |
| 222 |
... |
| 223 |
</programlisting> |
| 224 |
</para> |
| 225 |
|
| 226 |
<para> |
| 227 |
While it is possible to use the Apple-provided versions |
| 228 |
of <command>xmllint</command> and <command>xsltproc</command> |
| 229 |
instead of those from MacPorts or Homebrew, you'll still need |
| 230 |
to install the DocBook DTD and stylesheets, and set up a catalog |
| 231 |
file that points to them. |
| 232 |
</para> |
| 233 |
</sect2> |
| 234 |
|
| 235 |
<sect2 id="docguide-toolsets-configure"> |
| 236 |
<title>Detection by <command>configure</command></title> |
| 237 |
|
| 238 |
<para> |
| 239 |
Before you can build the documentation you need to run the |
| 240 |
<filename>configure</filename> script, as you would when building |
| 241 |
the <productname>PostgreSQL</productname> programs themselves. |
| 242 |
Check the output near the end of the run; it should look something |
| 243 |
like this: |
| 244 |
<screen> |
| 245 |
checking for xmllint... xmllint |
| 246 |
checking for xsltproc... xsltproc |
| 247 |
checking for fop... fop |
| 248 |
checking for dbtoepub... dbtoepub |
| 249 |
</screen> |
| 250 |
If <filename>xmllint</filename> or <filename>xsltproc</filename> is not |
| 251 |
found, you will not be able to build any of the documentation. |
| 252 |
<filename>fop</filename> is only needed to build the documentation in |
| 253 |
PDF format. |
| 254 |
<filename>dbtoepub</filename> is only needed to build the documentation |
| 255 |
in EPUB format. |
| 256 |
</para> |
| 257 |
|
| 258 |
<para> |
| 259 |
If necessary, you can tell <filename>configure</filename> where to find |
| 260 |
these programs, for example |
| 261 |
<screen> |
| 262 |
./configure ... XMLLINT=/opt/local/bin/xmllint ... |
| 263 |
</screen> |
| 264 |
</para> |
| 265 |
|
| 266 |
<para> |
| 267 |
If you prefer to build <productname>PostgreSQL</productname> using |
| 268 |
Meson, instead run <command>meson setup</command> as described in |
| 269 |
<xref linkend="install-meson"/>, and then see |
| 270 |
<xref linkend="docguide-build-meson"/>. |
| 271 |
</para> |
| 272 |
</sect2> |
| 273 |
</sect1> |
| 274 |
|
| 275 |
<sect1 id="docguide-build"> |
| 276 |
<title>Building the Documentation with Make</title> |
| 277 |
|
| 278 |
<para> |
| 279 |
Once you have everything set up, change to the directory |
| 280 |
<filename>doc/src/sgml</filename> and run one of the commands |
| 281 |
described in the following subsections to build the |
| 282 |
documentation. (Remember to use GNU make.) |
| 283 |
</para> |
| 284 |
|
| 285 |
<sect2 id="docguide-build-html"> |
| 286 |
<title>HTML</title> |
| 287 |
|
| 288 |
<para> |
| 289 |
To build the <acronym>HTML</acronym> version of the documentation: |
| 290 |
<screen> |
| 291 |
<prompt>doc/src/sgml$ </prompt><userinput>make html</userinput> |
| 292 |
</screen> |
| 293 |
This is also the default target. The output appears in the |
| 294 |
subdirectory <filename>html</filename>. |
| 295 |
</para> |
| 296 |
|
| 297 |
<para> |
| 298 |
To produce HTML documentation with the stylesheet used on <ulink |
| 299 |
url="https://www.postgresql.org/docs/current/">postgresql.org</ulink> instead of the |
| 300 |
default simple style use: |
| 301 |
<screen> |
| 302 |
<prompt>doc/src/sgml$ </prompt><userinput>make STYLE=website html</userinput> |
| 303 |
</screen> |
| 304 |
</para> |
| 305 |
|
| 306 |
<para> |
| 307 |
If the <literal>STYLE=website</literal> option is used, the generated HTML |
| 308 |
files include references to stylesheets hosted on <ulink |
| 309 |
url="https://www.postgresql.org/docs/current/">postgresql.org</ulink> and |
| 310 |
require network access to view. |
| 311 |
</para> |
| 312 |
</sect2> |
| 313 |
|
| 314 |
<sect2 id="docguide-build-manpages"> |
| 315 |
<title>Manpages</title> |
| 316 |
|
| 317 |
<para> |
| 318 |
We use the DocBook XSL stylesheets to |
| 319 |
convert <productname>DocBook</productname> |
| 320 |
<sgmltag>refentry</sgmltag> pages to *roff output suitable for man |
| 321 |
pages. To create the man pages, use the command: |
| 322 |
<screen> |
| 323 |
<prompt>doc/src/sgml$ </prompt><userinput>make man</userinput> |
| 324 |
</screen> |
| 325 |
</para> |
| 326 |
</sect2> |
| 327 |
|
| 328 |
<sect2 id="docguide-build-pdf"> |
| 329 |
<title>PDF</title> |
| 330 |
|
| 331 |
<para> |
| 332 |
To produce a PDF rendition of the documentation |
| 333 |
using <productname>FOP</productname>, you can use one of the following |
| 334 |
commands, depending on the preferred paper format: |
| 335 |
|
| 336 |
<itemizedlist> |
| 337 |
<listitem> |
| 338 |
<para> |
| 339 |
For A4 format: |
| 340 |
<screen> |
| 341 |
<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.pdf</userinput> |
| 342 |
</screen> |
| 343 |
</para> |
| 344 |
</listitem> |
| 345 |
|
| 346 |
<listitem> |
| 347 |
<para> |
| 348 |
For U.S. letter format: |
| 349 |
<screen> |
| 350 |
<prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.pdf</userinput> |
| 351 |
</screen> |
| 352 |
</para> |
| 353 |
</listitem> |
| 354 |
</itemizedlist> |
| 355 |
</para> |
| 356 |
|
| 357 |
<para> |
| 358 |
Because the PostgreSQL documentation is fairly |
| 359 |
big, <productname>FOP</productname> will require a significant amount of |
| 360 |
memory. Because of that, on some systems, the build will fail with a |
| 361 |
memory-related error message. This can usually be fixed by configuring |
| 362 |
Java heap settings in the configuration |
| 363 |
file <filename>~/.foprc</filename>, for example: |
| 364 |
<programlisting> |
| 365 |
# FOP binary distribution |
| 366 |
FOP_OPTS='-Xmx1500m' |
| 367 |
# Debian |
| 368 |
JAVA_ARGS='-Xmx1500m' |
| 369 |
# Red Hat |
| 370 |
ADDITIONAL_FLAGS='-Xmx1500m' |
| 371 |
</programlisting> |
| 372 |
There is a minimum amount of memory that is required, and to some extent |
| 373 |
more memory appears to make things a bit faster. On systems with very |
| 374 |
little memory (less than 1 GB), the build will either be very slow due to |
| 375 |
swapping or will not work at all. |
| 376 |
</para> |
| 377 |
|
| 378 |
<para> |
| 379 |
In its default configuration <productname>FOP</productname> will emit an |
| 380 |
<literal>INFO</literal> message for each page. The log level can be |
| 381 |
changed via <filename>~/.foprc</filename>: |
| 382 |
<programlisting> |
| 383 |
LOGCHOICE=-Dorg.apache.commons.logging.Log=&zwsp;org.apache.commons.logging.impl.SimpleLog |
| 384 |
LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN |
| 385 |
</programlisting> |
| 386 |
</para> |
| 387 |
|
| 388 |
<para> |
| 389 |
Other XSL-FO processors can also be used manually, but the automated build |
| 390 |
process only supports FOP. |
| 391 |
</para> |
| 392 |
</sect2> |
| 393 |
|
| 394 |
<sect2 id="docguide-build-syntax-check"> |
| 395 |
<title>Syntax Check</title> |
| 396 |
|
| 397 |
<para> |
| 398 |
Building the documentation can take very long. But there is a |
| 399 |
method to just check the correct syntax of the documentation |
| 400 |
files, which only takes a few seconds: |
| 401 |
<screen> |
| 402 |
<prompt>doc/src/sgml$ </prompt><userinput>make check</userinput> |
| 403 |
</screen> |
| 404 |
</para> |
| 405 |
</sect2> |
| 406 |
</sect1> |
| 407 |
|
| 408 |
|
| 409 |
<sect1 id="docguide-build-meson"> |
| 410 |
<title>Building the Documentation with Meson</title> |
| 411 |
|
| 412 |
<para> |
| 413 |
To build the documentation using Meson, change to the |
| 414 |
<filename>build</filename> directory before running one of these commands, |
| 415 |
or add <option>-C build</option> to the command. |
| 416 |
</para> |
| 417 |
|
| 418 |
<para> |
| 419 |
To build just the <acronym>HTML</acronym> version of the documentation: |
| 420 |
<screen> |
| 421 |
<prompt>build$ </prompt><userinput>ninja html</userinput> |
| 422 |
</screen> |
| 423 |
For a list of other documentation targets see |
| 424 |
<xref linkend="targets-meson-documentation"/>. |
| 425 |
|
| 426 |
The output appears in the |
| 427 |
subdirectory <filename>build/doc/src/sgml</filename>. |
| 428 |
</para> |
| 429 |
</sect1> |
| 430 |
|
| 431 |
|
| 432 |
<sect1 id="docguide-authoring"> |
| 433 |
<title>Documentation Authoring</title> |
| 434 |
|
| 435 |
<para> |
| 436 |
The documentation sources are most conveniently modified with an editor |
| 437 |
that has a mode for editing XML, and even more so if it has some awareness |
| 438 |
of XML schema languages so that it can know about |
| 439 |
<productname>DocBook</productname> syntax specifically. |
| 440 |
</para> |
| 441 |
|
| 442 |
<para> |
| 443 |
Note that for historical reasons the documentation source files are named |
| 444 |
with an extension <filename>.sgml</filename> even though they are now XML |
| 445 |
files. So you might need to adjust your editor configuration to set the |
| 446 |
correct mode. |
| 447 |
</para> |
| 448 |
|
| 449 |
<sect2 id="docguide-authoring-emacs"> |
| 450 |
<title>Emacs</title> |
| 451 |
|
| 452 |
<para> |
| 453 |
<productname>nXML Mode</productname>, which ships with |
| 454 |
<productname>Emacs</productname>, is the most common mode for editing |
| 455 |
<acronym>XML</acronym> documents with <productname>Emacs</productname>. |
| 456 |
It will allow you to use <application>Emacs</application> to insert tags |
| 457 |
and check markup consistency, and it supports |
| 458 |
<productname>DocBook</productname> out of the box. Check the <ulink |
| 459 |
url="https://www.gnu.org/software/emacs/manual/html_mono/nxml-mode.html"> |
| 460 |
nXML manual</ulink> for detailed documentation. |
| 461 |
</para> |
| 462 |
|
| 463 |
<para> |
| 464 |
<filename>src/tools/editors/emacs.samples</filename> contains |
| 465 |
recommended settings for this mode. |
| 466 |
</para> |
| 467 |
</sect2> |
| 468 |
|
| 469 |
</sect1> |
| 470 |
|
| 471 |
|
| 472 |
<sect1 id="docguide-style"> |
| 473 |
<title>Style Guide</title> |
| 474 |
|
| 475 |
<sect2 id="docguide-style-ref-pages"> |
| 476 |
<title>Reference Pages</title> |
| 477 |
|
| 478 |
<para> |
| 479 |
Reference pages should follow a standard layout. This allows |
| 480 |
users to find the desired information more quickly, and it also |
| 481 |
encourages writers to document all relevant aspects of a command. |
| 482 |
Consistency is not only desired among |
| 483 |
<productname>PostgreSQL</productname> reference pages, but also |
| 484 |
with reference pages provided by the operating system and other |
| 485 |
packages. Hence the following guidelines have been developed. |
| 486 |
They are for the most part consistent with similar guidelines |
| 487 |
established by various operating systems. |
| 488 |
</para> |
| 489 |
|
| 490 |
<para> |
| 491 |
Reference pages that describe executable commands should contain |
| 492 |
the following sections, in this order. Sections that do not apply |
| 493 |
can be omitted. Additional top-level sections should only be used |
| 494 |
in special circumstances; often that information belongs in the |
| 495 |
<quote>Usage</quote> section. |
| 496 |
|
| 497 |
<variablelist> |
| 498 |
<varlistentry id="docguide-style-ref-pages-name"> |
| 499 |
<term>Name</term> |
| 500 |
<listitem> |
| 501 |
<para> |
| 502 |
This section is generated automatically. It contains the |
| 503 |
command name and a half-sentence summary of its functionality. |
| 504 |
</para> |
| 505 |
</listitem> |
| 506 |
</varlistentry> |
| 507 |
|
| 508 |
<varlistentry id="docguide-style-ref-pages-synopsis"> |
| 509 |
<term>Synopsis</term> |
| 510 |
<listitem> |
| 511 |
<para> |
| 512 |
This section contains the syntax diagram of the command. The |
| 513 |
synopsis should normally not list each command-line option; |
| 514 |
that is done below. Instead, list the major components of the |
| 515 |
command line, such as where input and output files go. |
| 516 |
</para> |
| 517 |
</listitem> |
| 518 |
</varlistentry> |
| 519 |
|
| 520 |
<varlistentry id="docguide-style-ref-pages-description"> |
| 521 |
<term>Description</term> |
| 522 |
<listitem> |
| 523 |
<para> |
| 524 |
Several paragraphs explaining what the command does. |
| 525 |
</para> |
| 526 |
</listitem> |
| 527 |
</varlistentry> |
| 528 |
|
| 529 |
<varlistentry id="docguide-style-ref-pages-options"> |
| 530 |
<term>Options</term> |
| 531 |
<listitem> |
| 532 |
<para> |
| 533 |
A list describing each command-line option. If there are a |
| 534 |
lot of options, subsections can be used. |
| 535 |
</para> |
| 536 |
</listitem> |
| 537 |
</varlistentry> |
| 538 |
|
| 539 |
<varlistentry id="docguide-style-ref-pages-exit-status"> |
| 540 |
<term>Exit Status</term> |
| 541 |
<listitem> |
| 542 |
<para> |
| 543 |
If the program uses 0 for success and non-zero for failure, |
| 544 |
then you do not need to document it. If there is a meaning |
| 545 |
behind the different non-zero exit codes, list them here. |
| 546 |
</para> |
| 547 |
</listitem> |
| 548 |
</varlistentry> |
| 549 |
|
| 550 |
<varlistentry id="docguide-style-ref-pages-usage"> |
| 551 |
<term>Usage</term> |
| 552 |
<listitem> |
| 553 |
<para> |
| 554 |
Describe any sublanguage or run-time interface of the program. |
| 555 |
If the program is not interactive, this section can usually be |
| 556 |
omitted. Otherwise, this section is a catch-all for |
| 557 |
describing run-time features. Use subsections if appropriate. |
| 558 |
</para> |
| 559 |
</listitem> |
| 560 |
</varlistentry> |
| 561 |
|
| 562 |
<varlistentry id="docguide-style-ref-pages-environment"> |
| 563 |
<term>Environment</term> |
| 564 |
<listitem> |
| 565 |
<para> |
| 566 |
List all environment variables that the program might use. |
| 567 |
Try to be complete; even seemingly trivial variables like |
| 568 |
<envar>SHELL</envar> might be of interest to the user. |
| 569 |
</para> |
| 570 |
</listitem> |
| 571 |
</varlistentry> |
| 572 |
|
| 573 |
<varlistentry id="docguide-style-ref-pages-files"> |
| 574 |
<term>Files</term> |
| 575 |
<listitem> |
| 576 |
<para> |
| 577 |
List any files that the program might access implicitly. That |
| 578 |
is, do not list input and output files that were specified on |
| 579 |
the command line, but list configuration files, etc. |
| 580 |
</para> |
| 581 |
</listitem> |
| 582 |
</varlistentry> |
| 583 |
|
| 584 |
<varlistentry id="docguide-style-ref-pages-diagnostics"> |
| 585 |
<term>Diagnostics</term> |
| 586 |
<listitem> |
| 587 |
<para> |
| 588 |
Explain any unusual output that the program might create. |
| 589 |
Refrain from listing every possible error message. This is a |
| 590 |
lot of work and has little use in practice. But if, say, the |
| 591 |
error messages have a standard format that the user can parse, |
| 592 |
this would be the place to explain it. |
| 593 |
</para> |
| 594 |
</listitem> |
| 595 |
</varlistentry> |
| 596 |
|
| 597 |
<varlistentry id="docguide-style-ref-pages-notes"> |
| 598 |
<term>Notes</term> |
| 599 |
<listitem> |
| 600 |
<para> |
| 601 |
Anything that doesn't fit elsewhere, but in particular bugs, |
| 602 |
implementation flaws, security considerations, compatibility |
| 603 |
issues. |
| 604 |
</para> |
| 605 |
</listitem> |
| 606 |
</varlistentry> |
| 607 |
|
| 608 |
<varlistentry id="docguide-style-ref-pages-examples"> |
| 609 |
<term>Examples</term> |
| 610 |
<listitem> |
| 611 |
<para> |
| 612 |
Examples |
| 613 |
</para> |
| 614 |
</listitem> |
| 615 |
</varlistentry> |
| 616 |
|
| 617 |
<varlistentry id="docguide-style-ref-pages-history"> |
| 618 |
<term>History</term> |
| 619 |
<listitem> |
| 620 |
<para> |
| 621 |
If there were some major milestones in the history of the |
| 622 |
program, they might be listed here. Usually, this section can |
| 623 |
be omitted. |
| 624 |
</para> |
| 625 |
</listitem> |
| 626 |
</varlistentry> |
| 627 |
|
| 628 |
<varlistentry id="docguide-style-ref-pages-author"> |
| 629 |
<term>Author</term> |
| 630 |
<listitem> |
| 631 |
<para> |
| 632 |
Author (only used in the contrib section) |
| 633 |
</para> |
| 634 |
</listitem> |
| 635 |
</varlistentry> |
| 636 |
|
| 637 |
<varlistentry id="docguide-style-ref-pages-see-also"> |
| 638 |
<term>See Also</term> |
| 639 |
<listitem> |
| 640 |
<para> |
| 641 |
Cross-references, listed in the following order: other |
| 642 |
<productname>PostgreSQL</productname> command reference pages, |
| 643 |
<productname>PostgreSQL</productname> SQL command reference |
| 644 |
pages, citation of <productname>PostgreSQL</productname> |
| 645 |
manuals, other reference pages (e.g., operating system, other |
| 646 |
packages), other documentation. Items in the same group are |
| 647 |
listed alphabetically. |
| 648 |
</para> |
| 649 |
</listitem> |
| 650 |
</varlistentry> |
| 651 |
|
| 652 |
</variablelist> |
| 653 |
</para> |
| 654 |
|
| 655 |
<para> |
| 656 |
Reference pages describing SQL commands should contain the |
| 657 |
following sections: Name, Synopsis, Description, Parameters, |
| 658 |
Outputs, Notes, Examples, Compatibility, History, See |
| 659 |
Also. The Parameters section is like the Options section, but |
| 660 |
there is more freedom about which clauses of the command can be |
| 661 |
listed. The Outputs section is only needed if the command returns |
| 662 |
something other than a default command-completion tag. The Compatibility |
| 663 |
section should explain to what extent |
| 664 |
this command conforms to the SQL standard(s), or to which other |
| 665 |
database system it is compatible. The See Also section of SQL |
| 666 |
commands should list SQL commands before cross-references to |
| 667 |
programs. |
| 668 |
</para> |
| 669 |
</sect2> |
| 670 |
|
| 671 |
</sect1> |
| 672 |
</appendix> |