1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Style Guide</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.1.15 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Documentation"
HREF="docguide.html"><LINK
REL="PREVIOUS"
TITLE="Documentation Authoring"
HREF="docguide-authoring.html"><LINK
REL="NEXT"
TITLE="Acronyms"
HREF="acronyms.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2015-02-02T21:03:01"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.1.15 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Documentation Authoring"
HREF="docguide-authoring.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Appendix I. Documentation</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Acronyms"
HREF="acronyms.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DOCGUIDE-STYLE"
>I.5. Style Guide</A
></H1
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN144458"
>I.5.1. Reference Pages</A
></H2
><P
> Reference pages should follow a standard layout. This allows
users to find the desired information more quickly, and it also
encourages writers to document all relevant aspects of a command.
Consistency is not only desired among
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> reference pages, but also
with reference pages provided by the operating system and other
packages. Hence the following guidelines have been developed.
They are for the most part consistent with similar guidelines
established by various operating systems.
</P
><P
> Reference pages that describe executable commands should contain
the following sections, in this order. Sections that do not apply
can be omitted. Additional top-level sections should only be used
in special circumstances; often that information belongs in the
<SPAN
CLASS="QUOTE"
>"Usage"</SPAN
> section.
<P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Name</DT
><DD
><P
> This section is generated automatically. It contains the
command name and a half-sentence summary of its functionality.
</P
></DD
><DT
>Synopsis</DT
><DD
><P
> This section contains the syntax diagram of the command. The
synopsis should normally not list each command-line option;
that is done below. Instead, list the major components of the
command line, such as where input and output files go.
</P
></DD
><DT
>Description</DT
><DD
><P
> Several paragraphs explaining what the command does.
</P
></DD
><DT
>Options</DT
><DD
><P
> A list describing each command-line option. If there are a
lot of options, subsections can be used.
</P
></DD
><DT
>Exit Status</DT
><DD
><P
> If the program uses 0 for success and non-zero for failure,
then you do not need to document it. If there is a meaning
behind the different non-zero exit codes, list them here.
</P
></DD
><DT
>Usage</DT
><DD
><P
> Describe any sublanguage or run-time interface of the program.
If the program is not interactive, this section can usually be
omitted. Otherwise, this section is a catch-all for
describing run-time features. Use subsections if appropriate.
</P
></DD
><DT
>Environment</DT
><DD
><P
> List all environment variables that the program might use.
Try to be complete; even seemingly trivial variables like
<TT
CLASS="ENVAR"
>SHELL</TT
> might be of interest to the user.
</P
></DD
><DT
>Files</DT
><DD
><P
> List any files that the program might access implicitly. That
is, do not list input and output files that were specified on
the command line, but list configuration files, etc.
</P
></DD
><DT
>Diagnostics</DT
><DD
><P
> Explain any unusual output that the program might create.
Refrain from listing every possible error message. This is a
lot of work and has little use in practice. But if, say, the
error messages have a standard format that the user can parse,
this would be the place to explain it.
</P
></DD
><DT
>Notes</DT
><DD
><P
> Anything that doesn't fit elsewhere, but in particular bugs,
implementation flaws, security considerations, compatibility
issues.
</P
></DD
><DT
>Examples</DT
><DD
><P
> Examples
</P
></DD
><DT
>History</DT
><DD
><P
> If there were some major milestones in the history of the
program, they might be listed here. Usually, this section can
be omitted.
</P
></DD
><DT
>See Also</DT
><DD
><P
> Cross-references, listed in the following order: other
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> command reference pages,
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> SQL command reference
pages, citation of <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>
manuals, other reference pages (e.g., operating system, other
packages), other documentation. Items in the same group are
listed alphabetically.
</P
></DD
></DL
></DIV
><P>
</P
><P
> Reference pages describing SQL commands should contain the
following sections: Name, Synopsis, Description, Parameters,
Outputs, Notes, Examples, Compatibility, History, See
Also. The Parameters section is like the Options section, but
there is more freedom about which clauses of the command can be
listed. The Outputs section is only needed if the command returns
something other than a default command-completion tag. The Compatibility
section should explain to what extent
this command conforms to the SQL standard(s), or to which other
database system it is compatible. The See Also section of SQL
commands should list SQL commands before cross-references to
programs.
</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide-authoring.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="acronyms.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Documentation Authoring</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="docguide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Acronyms</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
|
