Fixing/Adding a bibliogaphy in the SWI-Prolog manual

Help! Tools
#1

I have found that there is a reference to a now-nonexistent PDF at this page:

in a footnote at the very bottom, the link to Neng-Fa Zhou’s paper Declarative Loops and List Comprehensions for Prolog is broken. The correct link is

http://www.sci.brooklyn.cuny.edu/~zhou/papers/loops.pdf

Well, I wanted to move this to the bibliography.

So…

However, rebuilding does not resolve the new \cite entry, and to boot the pl.bbl file contains a lot of entries now that were not in there before.

Clearly my work process is lacking in correctness.

How do I do it correctly?

1 Like
#2

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 :slight_smile:

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 delete man/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.

1 Like
#3

Thanks jan, I will report back once I have tried this.

#4

Looks like I succeeded.

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.

2 Likes
#5

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 …

1 Like
#6

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.

1 Like
#7

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 :slight_smile:

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

1 Like