Warnings while building Tesseract related to man pages generation

[stefanCCS]

Current Behavior

I have tried to compile Tesseract Release 5.5.1.
While doing make I could see these errors belows.

1st: I assume this is not important for running tesseract afterwards, as it looks like "only" to be relevant for documentation - correct?
2nd: Maybe something I can do to avoid this?
(if needed, I can provide more more details ...)

...
  CXXLD    libtesseract_sse.la
  CXXLD    libtesseract.la
  CXXLD    tesseract
asciidoc -b docbook -d manpage -o - doc/combine_lang_model.1.asc | \
xsltproc --nonet -o doc/combine_lang_model.1 http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl -
<unknown>:1: SyntaxWarning: invalid escape sequence '\S'
<unknown>:1: SyntaxWarning: invalid escape sequence '\S'
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
-:2: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
D DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
                                                                               ^
Note: Writing combine_lang_model.1
asciidoc -b docbook -d manpage -o - doc/combine_tessdata.1.asc | \
xsltproc --nonet -o doc/combine_tessdata.1 http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl -
<unknown>:1: SyntaxWarning: invalid escape sequence '\S'
<unknown>:1: SyntaxWarning: invalid escape sequence '\S'
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
-:2: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
D DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
                                                                               ^
Note: Writing combine_tessdata.1
asciidoc -b docbook -d manpage -o - doc/dawg2wordlist.1.asc | \
...

Expected Behavior

No response

Suggested Fix

No response

tesseract -v

No response

Operating System

Ubuntu 24.04 Noble

Other Operating System

No response

uname -a

No response

Compiler

No response

CPU

No response

Virtualization / Containers

ESXi-8

Other Information

No response

[stweil]

1. Yes, it is only relevant for the documentation (man pages).
2. It works for me on Debian. All messages are warnings, so you can simply ignore them.

asciidoc -b docbook -d manpage -o - doc/combine_lang_model.1.asc | xsltproc --nonet -o doc/combine_lang_model.1 http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl -
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
-:2: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
D DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
                                                                               ^
Note: Writing combine_lang_model.1

Which part of the pipeline throws the SyntaxWarning messages?

[stefanCCS]

Let me share some details:

• Here my complete logging from make, where this warning occurs:
  2025-08-20_09-47_make.log

This have been my commands:

git clone --branch 5.5.1 --depth 1 https://github.com/tesseract-ocr/tesseract.git tesseract-5.5.1
sudo apt update
sudo apt install automake ca-certificates g++ git libtool libleptonica-dev make pkg-config
sudo apt install --no-install-recommends asciidoc docbook-xsl xsltproc
sudo apt-get install libpango1.0-dev
cd tesseract-5.5.1
./autogen.sh
./configure
make
sudo make install
sudo ldconfig
make training
sudo make training-install

[stweil]

Try running asciidoc -b docbook -d manpage -o - doc/combine_lang_model.1.asc | xsltproc --nonet -o doc/combine_lang_model.1 http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl - from your Tesseract installation's root directory "tesseract-5.5.1". It should show the same messages.

Now run only asciidoc -b docbook -d manpage -o - doc/combine_lang_model.1.asc. Which messages does it produce?

[stefanCCS]

asciidoc -b docbook -d manpage -o - doc/combine_lang_model.1.asc | xsltproc --nonet -o doc/combine_lang_model.1 http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
<unknown>:1: SyntaxWarning: invalid escape sequence '\S'
<unknown>:1: SyntaxWarning: invalid escape sequence '\S'
Exception ignored in: <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>
BrokenPipeError: [Errno 32] Broken pipe

2. (sorry for proving an image - somehow the XML output contains something which formats this comment here...)

--> are you interested in full output?

[amitdo]

Maybe we should use asciidoctor instead of asciidoc(-py).

https://github.com/asciidoctor/asciidoctor

https://github.com/asciidoc-py/asciidoc-py

[denbrice]

This fixes it for me on Linux. Just move the "XML_CATALOG_FILES= " just underneath the $have_brew, so it only gets cleared on mac.

Workaround is to call make like this: "make XML_CATALOG_FILES=/etc/xml/catalog"

--- configure.ac.xml_catalog_files-broken       2026-03-08 23:58:00.921620446 +0100
+++ configure.ac        2026-03-08 23:55:45.134507032 +0100
@@ -450,8 +450,8 @@
   # XML_CATALOG_FILES for xsltproc.
   if $have_asciidoc && $have_xsltproc; then
     AM_CONDITIONAL([ASCIIDOC], true)
-    XML_CATALOG_FILES=
     if $have_brew; then
+      XML_CATALOG_FILES=
       catalog_file=$brew_prefix/etc/xml/catalog
       if test -f $catalog_file; then
         AM_CONDITIONAL([HAVE_XML_CATALOG_FILES], true)

[mvanhorn]

Implemented in #4530 - moves XML_CATALOG_FILES= inside the $have_brew block so Linux systems preserve their system catalog path.

[amitdo]

We moved from asciidoc to asciidoctor for manpage generation.

Unlike asciidoc, asciidoctor does not generate DocBook (XML) files, so this issue is not relevant anymore.