begriffs open source - ai-pg/blob - full-docs/txt/docguide-build.txt

   1
   2 J.3. Building the Documentation with Make #
   3
   4    J.3.1. HTML
   5    J.3.2. Manpages
   6    J.3.3. PDF
   7    J.3.4. Syntax Check
   8
   9    Once you have everything set up, change to the directory doc/src/sgml
  10    and run one of the commands described in the following subsections to
  11    build the documentation. (Remember to use GNU make.)
  12
  13 J.3.1. HTML #
  14
  15    To build the HTML version of the documentation:
  16 doc/src/sgml$ make html
  17
  18    This is also the default target. The output appears in the subdirectory
  19    html.
  20
  21    To produce HTML documentation with the stylesheet used on
  22    postgresql.org instead of the default simple style use:
  23 doc/src/sgml$ make STYLE=website html
  24
  25    If the STYLE=website option is used, the generated HTML files include
  26    references to stylesheets hosted on postgresql.org and require network
  27    access to view.
  28
  29 J.3.2. Manpages #
  30
  31    We use the DocBook XSL stylesheets to convert DocBook refentry pages to
  32    *roff output suitable for man pages. To create the man pages, use the
  33    command:
  34 doc/src/sgml$ make man
  35
  36 J.3.3. PDF #
  37
  38    To produce a PDF rendition of the documentation using FOP, you can use
  39    one of the following commands, depending on the preferred paper format:
  40      * For A4 format:
  41 doc/src/sgml$ make postgres-A4.pdf
  42
  43      * For U.S. letter format:
  44 doc/src/sgml$ make postgres-US.pdf
  45
  46    Because the PostgreSQL documentation is fairly big, FOP will require a
  47    significant amount of memory. Because of that, on some systems, the
  48    build will fail with a memory-related error message. This can usually
  49    be fixed by configuring Java heap settings in the configuration file
  50    ~/.foprc, for example:
  51 # FOP binary distribution
  52 FOP_OPTS='-Xmx1500m'
  53 # Debian
  54 JAVA_ARGS='-Xmx1500m'
  55 # Red Hat
  56 ADDITIONAL_FLAGS='-Xmx1500m'
  57
  58    There is a minimum amount of memory that is required, and to some
  59    extent more memory appears to make things a bit faster. On systems with
  60    very little memory (less than 1 GB), the build will either be very slow
  61    due to swapping or will not work at all.
  62
  63    In its default configuration FOP will emit an INFO message for each
  64    page. The log level can be changed via ~/.foprc:
  65 LOGCHOICE=-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Simp
  66 leLog
  67 LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
  68
  69    Other XSL-FO processors can also be used manually, but the automated
  70    build process only supports FOP.
  71
  72 J.3.4. Syntax Check #
  73
  74    Building the documentation can take very long. But there is a method to
  75    just check the correct syntax of the documentation files, which only
  76    takes a few seconds:
  77 doc/src/sgml$ make check