CHM build issues

[AllenJB]

Attempted to build the CHM (non-enhanced) version of the manual and while the build itself appears to work, I ran into issues compiling the output into a chm file.

There's some CHM build instructions at https://github.com/php/phd/blob/master/phpdotnet/phd/Package/PHP/HOWTO.GENERATE_CHM but as you'll see from my notes below, they're not very helpful.

The first issue I encountered is that HTMLHelp Workshop (which contains the HTMLHelp Compiler) will not install on Windows 11 (installer errors saying a newer version is already installed).

Additionally I should note HTMLHelp Workshop no longer appears to be available for download from Microsoft (there's web documentation for it, but none of the download links leads anywhere. The closest I could find was this MS Answers post linking to an archive.org copy

I then tried the chmcmd compiler from freepascal on Linux (I was using fpc 3.2.2 on Gentoo). While this appeared to create a .chm file, this file failed to load on Windows 11. Additionally it output an Access Violation error.

chmcmd produced a number of warnings relating to content during the build. The most common 2 were:

• Warning: Found file res/language.types.value.html while scanning res/<filename>.html, but couldn't find it on disk - appears to be caused by specific instances of the <type> tag on true and false
• Warning: Found file res/ while scanning res/mongodb.persistence.html, but couldn't find it on disk - appears to be caused by anchors with no file attached. I think created by (for example) <footnoteref linkend="mongodb.pclass"/>

Does anyone have working instructions / tools to build the chm version of the manual?

The apparent lack of tools for building CHMs (I did have a search but there weren't many options, never mind free and maintained options) has me moving towards suggesting dropping support for CHM.

[alfsb]

There's some CHM build instructions at https://github.com/php/phd/blob/master/phpdotnet/phd/Package/PHP/HOWTO.GENERATE_CHM but as you'll see from my notes below, they're not very helpful.

These instructions appear to be missing an --with-chm on php configure.php step, otherwise the files on chmonly/ won't be included.

The first issue I encountered is that HTMLHelp Workshop (which contains the HTMLHelp Compiler) will not install on Windows 11 (installer errors saying a newer version is already installed).

These tools are old. A quarter of a century old (what a strange thing to write, btw...). They probably need an Windows 95/98/XP version/virtualization/emulation to install properly.

chmcmd produced a number of warnings relating to content during the build. The most common 2 were:

• Warning: Found file res/language.types.value.html while scanning res/<filename>.html, but couldn't find it on disk - appears to be caused by specific instances of the <type> tag on true and false
• Warning: Found file res/ while scanning res/mongodb.persistence.html, but couldn't find it on disk - appears to be caused by anchors with no file attached. I think created by (for example) <footnoteref linkend="mongodb.pclass"/>

These need further inspection, as they may be part of a broader problem. What are the exact commands issued on the PhD step?

The "Download documentation" is down at the moment, so I cannot assert what combination of arguments are (probably) used for generating the compiled files.

Does anyone have working instructions / tools to build the chm version of the manual?

I vaguely remember that is/was someone in @php/doc-ja-team that was building the CHM version of manual from time to time. @mumumu perhaps?

[AllenJB]

Yes, those instructions are obviously old.

Thanks for the tip about the configure option - I enabled it but it doesn't seem to make a difference to the results.

I followed the same instructions as for building the (chunked) xhtml, but replaced the render line (build.sh line in the linked instructions) with php phd/render.php -d doc-base/.manual.xml -P PHP -f chm, then cd to the php-chm ouput directory and ran chmcmd on the php_manual_en.hhp file.

FYI I filed php/web-php#1505 on the docs downloads issues. I've been told it's likely to be looked at in the next few weeks. archive.org for 1st Sept appears to have copies of the downloads.

[derickr]

These instructions appear to be missing an --with-chm

It's called --enable-chm:

$ php -n doc-base/configure.php --help
configure.php on PHP 8.4.12-dev, libxml 2.9.14
…
  --enable-chm                   Enable Windows HTML Help Edition pages [no]

But in any case, the chmcmd command for me (after install fp-utils) also failed with that access violation, and I got an empty CHM. Perhaps we should just discontinue them.

[alfsb]

The manual download page is back, but without any CHM links: https://www.php.net/download-docs.php . The page still mentions the CHM version (the note about unblocking).

If there is no plans to make the CHM version avaliable again, there a few places that may need a clean-up. That note on the download page, mentions of CHM in doc-base and here.

For information, the last know date that CHM was builts suscefully was 2025-08-14.