1# SWI-Prolog manual sources 2 3 4This directory contains the sources to the SWI-Prolog manual. From this 5source we create PDF, HTML and the plain text online manual available 6through the help/1 and apropos/1 commands. 7 8The *.doc files form the input. The program doc2tex converts these into 9plain LaTeX files. It is responsible for handling characters that are 10difficult to handle in LaTeX, such as \ and to make references for such 11constructs like member/2. 12 13The style file pl.sty ensures _ (underscore) can be used without special 14precautions outside math mode. Do NOT write expand\_file/2, but simply 15expand_file/2. 16 17 18## Handling LaTeX special characters 19 20Predicate names that cannot be handled by TeX because they contain 21TeX-special characters are translated by doc2tex if they appear as plain 22LaTeX argument. We use the URL quoting mechanism for this, producing 23sequences that can be use in any TeX environment (unlike \verb). The 24sequences are named \S<name>. If you add such a sequence you must: 25 26 * Add it to doc2tex 27 * Add it to pl.sty 28 * Add it to ../packages/ltx2htm/pl.cmd 29 * Run "make install" in ../packages/ltx2htm 30 31## Summaries 32 33For each described predicate there MUST be an entry in the file 34summary.doc. Note that the content of this file is ordered 35alphabetically. 36 37## Documenting libraries 38 39Libraries are documented in their own file in the lib subdirectory. The 40library file has to be added to the input statements of lib/library.doc 41and the LIBFILES macro of the Makefile. To modify the Makefile, edit 42Makefile.in and run ./config.status from the build-directory of the base 43system (normally 'src'). The summary of libraries is in the file 44lib/summary.doc. Please update this with summary information for your 45library. 46 47Many of the libraries are nowadays documented in the source and the TeX 48is created through PlDoc. To add a library 49 50 - Edit Makefile.in: 51 - $LIBFILES 52 - Add a rule to the section "PlDoc generated manual files" 53 - Add an \input to lib/library.doc and lib/summary.doc. 54 55Note that the LaTeX filename should not contain underscores (see e.g., 56pure_input for an example). 57 58 59## Generating the documentation 60 61You need a recent latex installation with many optional packages. You 62find the documentation dependencies for Debian based Linux systems at 63http://www.swi-prolog.org/build/Debian.txt 64 65You also need to install the fixed-width font libraries available in the 66txt subdirectory. The README there explains how this must be installed. 67 68For the HTML version, you need to install the Prolog based latex2html. 69This is available in ../packages/ltx2htm. This is _not a default 70package_. If you install SWI-Prolog from the GIT sources, perform these 71steps to add it: 72 73 - run `git submodule update --init packages/ltx2htm` 74 - Add `ltx2htm` to the variable `EXTRA_PKGS` in the `build` script. 75 76After installing SWI-Prolog and with `swipl` in your `PATH`, run `make 77install` in `packages/ltx2htm` install `latex2html` in your `$HOME/bin` 78 79Targets: 80 81 make pdf - Generate SWI-Prolog-<version>.pdf 82 make html - Generate the HTML version in Manual/ 83 make clean - Remove generated intermediate files 84