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