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