Error building PostgreSQL documentation on macOS

Question

I'm encountering a persistent issue while attempting to build the PostgreSQL documentation on macOS. The error messages indicate problems with XML entities, external entities. I've followed the standard steps outlined in the PostgreSQL documentation, but I'm stuck with the following errors:

 ✘ spartacus@  ~/postgres/doc/src   master ±  make html
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C sgml html
/usr/bin/xmllint --nonet --path . --path . --output postgres-full.xml --noent --valid postgres.sgml
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
]>
  ^
postgres.sgml:23: element book: validity error : No declaration for attribute id of element book
<book id="postgres">
                   ^
postgres.sgml:24: element title: validity error : No declaration for element title
 <title>PostgreSQL &version; Documentation</title>
                                                  ^
postgres.sgml:27: element corpauthor: validity error : No declaration for element corpauthor
  <corpauthor>The PostgreSQL Global Development Group</corpauthor>
                                                                  ^
postgres.sgml:28: element productname: validity error : No declaration for element productname
  <productname>PostgreSQL</productname>
                                       ^
postgres.sgml:29: element productnumber: validity error : No declaration for element productnumber
  <productnumber>&version;</productnumber>
                                          ^
postgres.sgml:30: element date: validity error : No declaration for element date
  &legal;
         ^
legal.sgml:6: parser error : Entity 'ndash' not defined
 <year>1996&ndash;2023</year>
                  ^
legal.sgml:14: parser error : Entity 'copy' not defined
  <productname>PostgreSQL</productname> is Copyright &copy; 1996&ndash;2023
                                                           ^
legal.sgml:14: parser error : Entity 'ndash' not defined
  <productname>PostgreSQL</productname> is Copyright &copy; 1996&ndash;2023
                                                                       ^
legal.sgml:19: parser error : Entity 'copy' not defined
  <productname>Postgres95</productname> is Copyright &copy; 1994&ndash;5
                                                           ^
legal.sgml:19: parser error : Entity 'ndash' not defined
  <productname>Postgres95</productname> is Copyright &copy; 1994&ndash;5
                                                                       ^
legal.sgml:49: parser error : chunk is not well balanced

^
postgres.sgml:30: parser error : Entity 'legal' failed to parse
  &legal;
         ^
make[1]: *** [postgres-full.xml] Error 1
make: *** [html] Error 2

Additional Information:

• The system is configured without ICU support.
• ICU library is not found during the configuration process.
• Executed command without ICU: ./configure --without-icu

Solutions Attempted: I've tried the following solutions based on online research and PostgreSQL documentation:

• Checked the internet connection to ensure the system can access external resources.
• Confirmed that xmllint is installed and available in the system path.
• Verified the presence of required XML entities locally.
• Checked for any proxy configurations that might interfere with external entity loading.
• I also attempted to use a local *DOCTYPE declaration in the postgres.sgml file:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file:///Users/spartacus/postgres/doc/src/docbookx.dtd" [

Despite these efforts, the issue persists.

Answer 1

I followed the following steps to get rid of the error, help from this Github issue:

1. Uninstall existing packages:

   brew uninstall docbook docbook-xsl xmlto
   

   If there are dependency issues, you can force removal:

   brew uninstall --ignore-dependencies docbook docbook-xsl
   

2. Install required packages:

   brew install docbook docbook-xsl xmlto
   

3. Set up XML_CATALOG_FILES: Add the following to your ~/.bashrc or ~/.zshrc:

   export XML_CATALOG_FILES="/opt/homebrew/etc/xml/catalog"
   

4. Rebuild PostgreSQL documentation: Navigate to the PostgreSQL documentation directory and run:

   make html
   

5. Open HTML documentation:

   open path/to/postgres/doc/src/sgml/html/index.html
   

The issue was related to the inability to load the DocBook XML DTD from the specified URL. By uninstalling and reinstalling the required packages (docbook, docbook-xsl, xmlto), I ensured that the necessary XML entities and dependencies were correctly set up.

Configuring the XML_CATALOG_FILES environment variable pointed to the correct XML catalog file, providing the necessary references for DocBook entities. This, in turn, resolved the loading issues, allowing the PostgreSQL documentation build to proceed without errors, this is my view on this solution working

Any other insights on this are welcome.