Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 06ad580

Browse files
peterepetere
committed
Structure reference pages consistently. Document that structure.
Add information about environment variables.
1 parent b02c56f commit 06ad580

17 files changed

+2449
-1858
lines changed

‎doc/src/sgml/docguide.sgml

Lines changed: 191 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.41 2002/03/22 19:20:08 petere Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.42 2002/07/28 15:22:20 petere Exp $ -->
22

33
<appendix id="docguide">
44
<title>Documentation</title>
@@ -1254,6 +1254,196 @@ End:
12541254

12551255
</sect1>
12561256

1257+
1258+
<sect1 id="doc-style">
1259+
<title>Style Guide</title>
1260+
1261+
<sect2>
1262+
<title>Reference Pages</title>
1263+
1264+
<para>
1265+
Reference pages should follow a standard layout. This allows
1266+
users to find the desired information more quickly, and it also
1267+
encourages writers to document all relevant aspects of a command.
1268+
Consistency is not only desired among
1269+
<productname>PostgreSQL</productname> reference pages, but also
1270+
with reference pages provided by the operating system and other
1271+
packages. Hence the following guidelines have been developed.
1272+
They are for the most part consistent with similar guidelines
1273+
established by various operating systems.
1274+
</para>
1275+
1276+
<para>
1277+
Reference pages that describe executable commands should contain
1278+
the following sections, in this order. Sections that do not apply
1279+
may be omitted. Additional top-level sections should only be used
1280+
in special circumstances; often that information belongs in the
1281+
<quote>Usage</quote> section.
1282+
1283+
<variablelist>
1284+
<varlistentry>
1285+
<term>Name</term>
1286+
<listitem>
1287+
<para>
1288+
This section is generated automatically. It contains the
1289+
command name and a half-sentence summary of its functionality.
1290+
</para>
1291+
</listitem>
1292+
</varlistentry>
1293+
1294+
<varlistentry>
1295+
<term>Synopsis</term>
1296+
<listitem>
1297+
<para>
1298+
This section contains the syntax diagram of the command. The
1299+
synopsis should normally not list each command-line option;
1300+
that is done below. Instead, list the major components of the
1301+
command line, such as where input and output files go.
1302+
</para>
1303+
</listitem>
1304+
</varlistentry>
1305+
1306+
<varlistentry>
1307+
<term>Description</term>
1308+
<listitem>
1309+
<para>
1310+
Several paragraphs explaining what the command does.
1311+
</para>
1312+
</listitem>
1313+
</varlistentry>
1314+
1315+
<varlistentry>
1316+
<term>Options</term>
1317+
<listitem>
1318+
<para>
1319+
A list describing each command-line option. If there are a
1320+
lot of options, subsections may be used.
1321+
</para>
1322+
</listitem>
1323+
</varlistentry>
1324+
1325+
<varlistentry>
1326+
<term>Exit Status</term>
1327+
<listitem>
1328+
<para>
1329+
If the program uses 0 for success and non-zero for failure,
1330+
then you don't need to document it. If there is a meaning
1331+
behind the different non-zero exit codes, list them here.
1332+
</para>
1333+
</listitem>
1334+
</varlistentry>
1335+
1336+
<varlistentry>
1337+
<term>Usage</term>
1338+
<listitem>
1339+
<para>
1340+
Describe any sublanguage or run-time interface of the program.
1341+
If the program is not interactive, this section can usually be
1342+
omitted. Otherwise, this section is a catch-all for
1343+
describing run-time features. Use subsections if appropriate.
1344+
</para>
1345+
</listitem>
1346+
</varlistentry>
1347+
1348+
<varlistentry>
1349+
<term>Environment</term>
1350+
<listitem>
1351+
<para>
1352+
List all environment variables that the program might use.
1353+
Try to be complete; even seemingly trivial variables like
1354+
<envar>SHELL</envar> might be of interest to the user.
1355+
</para>
1356+
</listitem>
1357+
</varlistentry>
1358+
1359+
<varlistentry>
1360+
<term>Files</term>
1361+
<listitem>
1362+
<para>
1363+
List any files that the program might access implicitly. That
1364+
is, do not list input and output files that were specified on
1365+
the command line, but list configuration files, etc.
1366+
</para>
1367+
</listitem>
1368+
</varlistentry>
1369+
1370+
<varlistentry>
1371+
<term>Diagnostics</term>
1372+
<listitem>
1373+
<para>
1374+
Explain any unusual output that the program might create.
1375+
Refrain from listing every possible error message. This is a
1376+
lot of work and has little use in practice. But if, say, the
1377+
error messages have a standard format that the user can parse,
1378+
this would be the place to explain it.
1379+
</para>
1380+
</listitem>
1381+
</varlistentry>
1382+
1383+
<varlistentry>
1384+
<term>Notes</term>
1385+
<listitem>
1386+
<para>
1387+
Anything that doesn't fit elsewhere, but in particular bugs,
1388+
implementation flaws, security considerations, compatibility
1389+
issues.
1390+
</para>
1391+
</listitem>
1392+
</varlistentry>
1393+
1394+
<varlistentry>
1395+
<term>Examples</term>
1396+
<listitem>
1397+
<para>
1398+
Examples
1399+
</para>
1400+
</listitem>
1401+
</varlistentry>
1402+
1403+
<varlistentry>
1404+
<term>History</term>
1405+
<listitem>
1406+
<para>
1407+
If there were some major milestones in the history of the
1408+
program, they might be listed here. Usually, this section can
1409+
be omitted.
1410+
</para>
1411+
</listitem>
1412+
</varlistentry>
1413+
1414+
<varlistentry>
1415+
<term>See Also</term>
1416+
<listitem>
1417+
<para>
1418+
Cross-references, listed in the following order: other
1419+
<productname>PostgreSQL</productname> command reference pages,
1420+
<productname>PostgreSQL</productname> SQL command reference
1421+
pages, citation of <productname>PostgreSQL</productname>
1422+
manuals, other reference pages (e.g., operating system, other
1423+
packages), other documentation. Items in the same group are
1424+
listed alphabetically.
1425+
</para>
1426+
</listitem>
1427+
</varlistentry>
1428+
1429+
</variablelist>
1430+
</para>
1431+
1432+
<para>
1433+
Reference pages describing SQL commands should contain the
1434+
following sections: Name, Synopsis, Description, Parameters,
1435+
Usage, Diagnostics, Notes, Examples, Compatibility, History, See
1436+
Also. The Parameters section is like the Options section, but
1437+
there is more freedom about which clauses of the command can be
1438+
listed. The Compatibility section should explain to what extent
1439+
this command conforms to the SQL standard(s), or to which other
1440+
database system it is compatible. The See Also section of SQL
1441+
commands should list SQL commands before cross-references to
1442+
programs.
1443+
</para>
1444+
</sect2>
1445+
1446+
</sect1>
12571447
</appendix>
12581448

12591449
<!-- Keep this comment at the end of the file

‎doc/src/sgml/ref/createdb.sgml

Lines changed: 74 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.26 2002/04/21 19:02:39 thomas Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.27 2002/07/28 15:22:20 petere Exp $
33
PostgreSQL documentation
44
-->
55

@@ -22,12 +22,42 @@ PostgreSQL documentation
2222
<arg><replaceable>dbname</replaceable></arg>
2323
<arg><replaceable>description</replaceable></arg>
2424
</cmdsynopsis>
25+
</refsynopsisdiv>
2526

26-
<refsect2 id="R2-APP-CREATEDB-1">
27-
<title>
28-
Inputs
29-
</title>
30-
<para>
27+
28+
<refsect1 id="R1-APP-CREATEDB-1">
29+
<title>
30+
Description
31+
</title>
32+
<para>
33+
<application>createdb</application> creates a new <productname>PostgreSQL</productname>
34+
database.
35+
</para>
36+
37+
<para>
38+
Normally, the database user who executes this command becomes the owner of
39+
the new database.
40+
However a different owner can be specified via the <option>-O</option>
41+
option, if the executing user has appropriate privileges.
42+
</para>
43+
44+
<para>
45+
<application>createdb</application> is a shell script wrapper around the
46+
<acronym>SQL</acronym> command
47+
<xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via
48+
the <productname>PostgreSQL</productname> interactive terminal
49+
<xref linkend="APP-PSQL">. Thus, there is nothing
50+
special about creating databases via this or other methods. This means
51+
that the <application>psql</application> program must be found by the script and that
52+
a database server must be running at the targeted port. Also, any default
53+
settings and environment variables available to <application>psql</application>
54+
and the <application>libpq</application> front-end library will apply.
55+
</para>
56+
</refsect1>
57+
58+
59+
<refsect1>
60+
<title>Options</title>
3161

3262
<variablelist>
3363
<varlistentry>
@@ -149,6 +179,7 @@ PostgreSQL documentation
149179

150180
</variablelist>
151181

182+
<para>
152183
The options <option>-h</option>, <option>-p</option>, <option>-U</option>,
153184
<option>-W</option>, and <option>-e</option> are passed on literally to
154185
<xref linkend="app-psql">.
@@ -160,13 +191,12 @@ PostgreSQL documentation
160191
endterm="SQL-CREATEDATABASE-title">; see there for more information
161192
about them.
162193
</para>
163-
</refsect2>
194+
</refsect1>
195+
196+
197+
<refsect1>
198+
<title>Diagnostics</title>
164199

165-
<refsect2 id="R2-APP-CREATEDB-2">
166-
<title>
167-
Outputs
168-
</title>
169-
<para>
170200
<variablelist>
171201
<varlistentry>
172202
<term><computeroutput>CREATE DATABASE</computeroutput></term>
@@ -195,45 +225,37 @@ PostgreSQL documentation
195225
</varlistentry>
196226
</variablelist>
197227

228+
<para>
198229
If there is an error condition, the backend error message will be displayed.
199230
See <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-TITLE">
200231
and <xref linkend="APP-PSQL"> for possibilities.
201232
</para>
202-
</refsect2>
203-
</refsynopsisdiv>
233+
</refsect1>
204234

205-
<refsect1 id="R1-APP-CREATEDB-1">
206-
<title>
207-
Description
208-
</title>
209-
<para>
210-
<application>createdb</application> creates a new <productname>PostgreSQL</productname>
211-
database.
212-
</para>
213235

214-
<para>
215-
Normally, the database user who executes this command becomes the owner of
216-
the new database.
217-
However a different owner can be specified via the <option>-O</option>
218-
option, if the executing user has appropriate privileges.
219-
</para>
236+
<refsect1>
237+
<title>Environment</title>
220238

221-
<para>
222-
<application>createdb</application> is a shell script wrapper around the
223-
<acronym>SQL</acronym> command
224-
<xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via
225-
the <productname>PostgreSQL</productname> interactive terminal
226-
<xref linkend="APP-PSQL">. Thus, there is nothing
227-
special about creating databases via this or other methods. This means
228-
that the <application>psql</application> program must be found by the script and that
229-
a database server must be running at the targeted port. Also, any default
230-
settings and environment variables available to <application>psql</application>
231-
and the <application>libpq</application> front-end library will apply.
232-
</para>
239+
<variablelist>
240+
<varlistentry>
241+
<term><envar>PGHOST</envar></term>
242+
<term><envar>PGPORT</envar></term>
243+
<term><envar>PGUSER</envar></term>
244+
245+
<listitem>
246+
<para>
247+
Default connection parameters. <envar>PGUSER</envar> also
248+
determines the name of the database to create, if it is not
249+
specified in the command line.
250+
</para>
251+
</listitem>
252+
</varlistentry>
253+
</variablelist>
233254
</refsect1>
234255

256+
235257
<refsect1 id="R1-APP-CREATEDB-2">
236-
<title>Usage</title>
258+
<title>Examples</title>
237259

238260
<informalexample>
239261
<para>
@@ -262,6 +284,17 @@ PostgreSQL documentation
262284
</para>
263285
</informalexample>
264286
</refsect1>
287+
288+
289+
<refsect1>
290+
<title>See Also</title>
291+
292+
<simplelist type="inline">
293+
<member><xref linkend="app-dropdb"></member>
294+
<member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member>
295+
</simplelist>
296+
</refsect1>
297+
265298
</refentry>
266299

267300
<!-- Keep this comment at the end of the file

0 commit comments

Comments
 (0)