If you have installed the dependencies to build the PDF documentation, configure using cmake -DBUILD_PDF_DOCUMENTATION=ON … and build it. That produces man/SWI-Prolog-<version>.bbl in the build directory. That creates the correct .bbl, only containing the entries that are actually used. pl.bib contains a lot of stuff that is (no longer) used. Please leave it in, it may become of use later
Copy man/SWI-Prolog-<version>.bbl to ../man/gen/swipl.bbl (should result in a change according to git diff)
Important: in a build dir not setup for the PDF docs, make sure to deleteman/SWI-Prolog-<version>.bbl before building the HTML. Without this step this file is not copied.
Make sure to rebuild the HTML docs. One way is to delete man/pldoc2tex from the build dir as all generated LaTeX files depend on that. Then run ninja.
If all is fine, commit the change into git.
Note that all this breaks a golden rule of version management: generated files should not be in a repository. The alternative is to force the entire LaTeX suite as build dependency and always build the PDF. That is IMO an overkill, also because pl.bib and citations do not change often.
At first the system packages with “texlive-a4wide” and “epstopdf” were missing. For some reason, the build still proceeded without generating any errors. Maybe cmake doesn’t forward these? They would be generated by child processes of script man/runtex.
This quite a bit of time to get it working but in the end it worked out.
The LaTeX build is rather noisy about under and overfull boxes, etc. So yes, by default all reporting is ignored. Maybe there should be some setting to make it run verbosely. Now if the pdf is not created I run ninja -v to get the command line and then copy/paste it on the terminal, remove --quiet and run it. It is not needed often …
In case anyone ever hits this problem, I have just thrown together some very quick & dirty notes on editing the documentation. It might be helpful for anyone who is looking for such things.
Thanks. Most seems correct. Some are more general LaTeX things. Lots of available macros to deal with Prolog are also missing. All the dedicated macros for the docs are defined in man/pl.sty. Some with comments
Note that .doc files are translated into .tex using man/doc2tex.pl, which notably translates name/arity into links using \predref{name}{arity} and ensures that difficult to write atoms such as =\=, if they appear in {}, e.g., {=\=} is translated into some \urldef sequence. So, anywhere outside code blocks you write simply {=\=} and it will be rendered correctly. Typically you pass these atoms to one of the other macros. That is precisely why this exists as you cannot pass \verb$=\=$ to a macro in LaTeX.
Finally, there is a more elegant way to deal with pull requests described here