Debian Codegraph @

doc/src/sgml/docguide.sgml

raw
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>