Bug 234120 - inconsistent documentation build description, bugs in .XML: can not build docs
Summary: inconsistent documentation build description, bugs in .XML: can not build docs
Status: Closed Overcome By Events
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: freebsd-doc (Nobody)
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2018-12-18 09:12 UTC by O. Hartmann
Modified: 2021-04-11 11:48 UTC (History)
2 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description O. Hartmann 2018-12-18 09:12:48 UTC
Since a couple of months for now I try to build the documentation of FreeBSD including PDF handbook and the web page. That is true for 12-CURRENT and now 13-CURRENT. Since then, I'm unable to build what is in /usr/doc!

Starting with what is explained to build the doc tree at

https://www.freebsd.org/doc/en/books/fdp-primer/doc-build-toolset.html

firt I do is to update /usr/doc, which targets to 

# svn info
Path: .
Working Copy Root Path: /usr/doc
URL: https://svn.freebsd.org/doc/head
Relative URL: ^/head
Repository Root: https://svn.freebsd.org/doc
Repository UUID: c2e8774f-c49f-e111-b436-862b2bbc8956
Revision: 52695
Node Kind: directory
Schedule: normal
Last Changed Author: rcyu
Last Changed Rev: 52695
Last Changed Date: 2018-12-17 16:08:35 +0100 (Mon, 17 Dec 2018)

The following requirements (ports) are installed and up to date:
textproc/iso8879
textproc/docbook-xml
textproc/xhtml

and as a (mutual) prerequisit

textproc/docbook
textproc/docproj

textproc/docproj has options DBLATEX and FOP set, if that information matters, too.

It doesn't matter whether I follow the instructions from here: 

https://www.freebsd.org/doc/en/books/fdp-primer/

Chapter 2.

In /etc/make I've setup the following:

DOC_LANG=en_US.ISO8859-1 de_DE.ISO8859-1 
FORMATS=html-split pdf   
WEB_LANG=de_DE.ISO8859-1 en_US.ISO8859-1

and prepared as shown above, staring

cd /usr/doc
make all

results all the time in a hard error as shown below.

It doesn't matter whether I start at /usr/doc and issue make all or try, following dumb and blunt the instructions in the primer mentioned above and try building only the en_US handbook as web pages, the error always pops up. 

I am wondering how people build the official website's documentation!

We need offsite and off-LAN/network documentation in a security environment and I'd like to build fresh docs from the repository for that purpose.


[...]
egrep: chapters.ent: No such file or directory
env XML_CATALOG_FILES="file:///usr/obj/usr/doc/en_US.ISO8859-1/books/handbook/catalog-cwd.xml  file:///usr/doc/en_US.ISO8859-1/share/xml/catalog.xml  file:///usr/doc/share/xml/catalog.xml  file:///usr/local/share/xml/catalog" /usr/local/bin/xmllint --nonet --noent --valid --dropdtd --xinclude /usr/doc/en_US.ISO8859-1/books/handbook/book.xml > book.parsed.xml.tmp
warning: failed to load external entity "/usr/doc/en_US.ISO8859-1/books/handbook/mirrors.xml.ftp.index.inc"
/usr/doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml:100: parser error : Failure to process entity chap.mirrors.ftp.index.inc
    &chap.mirrors.ftp.index.inc;
                                ^
/usr/doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml:100: parser error : Entity 'chap.mirrors.ftp.index.inc' not defined
    &chap.mirrors.ftp.index.inc;
                                ^
warning: failed to load external entity "/usr/doc/en_US.ISO8859-1/books/handbook/mirrors.lastmod.inc"
/usr/doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml:102: parser error : Failure to process entity chap.mirrors.lastmod.inc
    &chap.mirrors.lastmod.inc;
                              ^
/usr/doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml:102: parser error : Entity 'chap.mirrors.lastmod.inc' not defined
    &chap.mirrors.lastmod.inc;
                              ^
warning: failed to load external entity "/usr/doc/en_US.ISO8859-1/books/handbook/mirrors.xml.ftp.inc"
/usr/doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml:104: parser error : Failure to process entity chap.mirrors.ftp.inc
    &chap.mirrors.ftp.inc;
                          ^
/usr/doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml:104: parser error : Entity 'chap.mirrors.ftp.inc' not defined
    &chap.mirrors.ftp.inc;
                          ^
/usr/doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml:506: parser error : chunk is not well balanced

^
/usr/doc/en_US.ISO8859-1/books/handbook/book.xml:311: parser error : Failure to process entity chap.mirrors
    &chap.mirrors;
                  ^
/usr/doc/en_US.ISO8859-1/books/handbook/book.xml:311: parser error : Entity 'chap.mirrors' not defined
    &chap.mirrors;
                  ^
warning: failed to load external entity "/usr/doc/en_US.ISO8859-1/books/handbook/eresources.xml.www.index.inc"
/usr/doc/en_US.ISO8859-1/books/handbook/eresources/chapter.xml:2457: parser error : Failure to process entity chap.eresources.www.index.inc
    &chap.eresources.www.index.inc;
                                   ^
/usr/doc/en_US.ISO8859-1/books/handbook/eresources/chapter.xml:2457: parser error : Entity 'chap.eresources.www.index.inc' not defined
    &chap.eresources.www.index.inc;
                                   ^
warning: failed to load external entity "/usr/doc/en_US.ISO8859-1/books/handbook/mirrors.lastmod.inc"
/usr/doc/en_US.ISO8859-1/books/handbook/eresources/chapter.xml:2459: parser error : Failure to process entity chap.mirrors.lastmod.inc
    &chap.mirrors.lastmod.inc;
                              ^
/usr/doc/en_US.ISO8859-1/books/handbook/eresources/chapter.xml:2459: parser error : Entity 'chap.mirrors.lastmod.inc' not defined
    &chap.mirrors.lastmod.inc;
                              ^
warning: failed to load external entity "/usr/doc/en_US.ISO8859-1/books/handbook/eresources.xml.www.inc"
/usr/doc/en_US.ISO8859-1/books/handbook/eresources/chapter.xml:2461: parser error : Failure to process entity chap.eresources.www.inc
    &chap.eresources.www.inc;
                             ^
/usr/doc/en_US.ISO8859-1/books/handbook/eresources/chapter.xml:2461: parser error : Entity 'chap.eresources.www.inc' not defined
    &chap.eresources.www.inc;
                             ^
/usr/doc/en_US.ISO8859-1/books/handbook/eresources/chapter.xml:2464: parser error : chunk is not well balanced

^
/usr/doc/en_US.ISO8859-1/books/handbook/book.xml:313: parser error : Failure to process entity chap.eresources
    &chap.eresources;
                     ^
/usr/doc/en_US.ISO8859-1/books/handbook/book.xml:313: parser error : Entity 'chap.eresources' not defined
    &chap.eresources;
                     ^
*** Error code 1

Stop.
make[3]: stopped in /usr/doc/en_US.ISO8859-1/books/handbook
*** Error code 1

Stop.
Comment 1 Benjamin Kaduk freebsd_committer freebsd_triage 2018-12-20 23:01:03 UTC
The automated documentation build has not been running into an issue of this nature recently (though we did get some mail about failures that might be due to hardware issues or a full disk or similar, in the past couple days).

It is unfortunately the case that the documentation build is both susceptible to stray artifacts in the build tree (which is also the source tree, at least by default), and does not offer a reliable clean target.  But given the lack of other reports, my current best hypothesis is that there's a stray file in your local environment that is responsible for these issues.  It may be simplest to try to checkout a fresh tree and building that, at least before trying to track down exactly what stray file would be responsible for the build issues.
Comment 2 O. Hartmann 2018-12-21 12:22:50 UTC
Please be more specific in the terminus "... susceptible to stray artifacts in the build tree ...". Does this include the ports installation pathas as well or do you refer only to /usr/doc?

First thing I did, a long time ago and just now, delete the whole /usr/doc folder and check it out again; then check via "svn status" whether there is something strange. It is all clean.
Comment 3 Benjamin Kaduk freebsd_committer freebsd_triage 2018-12-24 04:20:12 UTC
The only ones I remember running into involve files in /usr/doc .

It might be helpful to post (whether here or on a pastebin-alike) a bit more of the end of your build log.  My local build was successful, though it used a somewhat different invocation than yours.  (I can't build html-split, for one, since I don't currently have fop installed.)  But the builds that I can do, finish successfully.
Comment 4 Sergio Carlavilla Delgado freebsd_committer freebsd_triage 2021-04-11 11:48:55 UTC
Since we moved to Hugo/AsciiDoc we can close this.
Please try with the new documentation system.
To get more information please check https://docs.freebsd.org/en/books/fdp-primer/overview/