Skip to Content
DocsGetting the Documentation

How To Get (More) PPL Documentation@ $Date:

Do you have all the documentation you need? If you don’t or if you are unsure, the following is for you.

The Parma Polyhedra Library’s documentation is partitioned in two subsets:

  • the `user’ manuals, containing all and only the information needed by people willing to use the library;
  • the `devref’ (developer reference) manuals, also containing details about the library implementation.

Each of the two subsets above contains:

  • the `core’ library manual, devoted to the description of the C++ language interface but also including a (programming language independent) specification of the semantic domains and their operators;
  • a `configuration-independent’ manual for each of the supported non-templatic (i.e., non-C++) language interfaces; typically, these manuals will only provide language specific information, restricted to a subset of the available semantic domains, while referring to the core manual for a high-level description of the domain themselves and the corresponding operators;
  • a `configuration-dependent’ manual for each of the supported non-templatic (i.e., non-C++) language interfaces; these manuals differ from the ones above in that they will list all the datatypes and functions (resp., methods, predicates) that are available for the specific set of domain instances chosen at configuration time.

Each manual in either of the two subsets above can be obtained in several formats:

  • a PDF file suitable for printing or browsing on the screen;
  • a (gzipped) PostScript file suitable for printing;
  • a (tarred and gzipped) collection of HTML pages suitable for browsing.

[]{#find}

The Documentation You May Already Have

First of all, you may already have some documentation and all you need is to find it.

If you have downloaded a source (tar or zip) archive for PPL version X.Y.Z, you will find in the doc subdirectory all of the configuration-independent user manuals:

  ppl-user-X.Y.Z.pdf
  ppl-user-X.Y.Z.ps.gz
  ppl-user-X.Y.Z-html.tar.gz
  ppl-user-c-interface-X.Y.Z.pdf
  ppl-user-c-interface-X.Y.Z.ps.gz
  ppl-user-c-interface-X.Y.Z-html.tar.gz
  ppl-user-java-interface-X.Y.Z.pdf
  ppl-user-java-interface-X.Y.Z.ps.gz
  ppl-user-java-interface-X.Y.Z-html.tar.gz
  ppl-user-ocaml-interface-X.Y.Z.pdf
  ppl-user-ocaml-interface-X.Y.Z.ps.gz
  ppl-user-ocaml-interface-X.Y.Z-html.tar.gz
  ppl-user-prolog-interface-X.Y.Z.pdf
  ppl-user-prolog-interface-X.Y.Z.ps.gz
  ppl-user-prolog-interface-X.Y.Z-html.tar.gz

If you have installed a binary package, then you may have the same set of manuals. Note that sometimes the documentation is distributed in a separate package. In the case of RPM packages, you can locate the manuals with a command such as `rpm -ql ppl-docs’ which will print, among other things, something like

  /usr/share/doc/ppl-X.Y.Z
  /usr/share/doc/ppl-X.Y.Z/README
  /usr/share/doc/ppl-X.Y.Z/ppl-user-X.Y.Z.pdf
  /usr/share/doc/ppl-X.Y.Z/ppl-user-X.Y.Z.ps.gz

[]{#download}

The Documentation You May Download

If you are using the latest released version of the library, you will find all the documentation in all formats at http://www.cs.unipr.it/ppl/Documentation/. []{#build}

The Documentation You May Build Yourself

When all else fails (which is the case, for example, when you are using a Git version) then you may build the documentation by yourself. In order to do that, you should have recent versions of Doxygen  and Graphviz  (you will also need ocamldoc if you plan to build the OCaml interface manuals). When you have all the tools installed and running, you should follow the following procedure.

First, if you have not yet done it, build the library itself (see the building instructions in the files INSTALL  and README.configure  in the top source directory).

The default build process, while essential in order to produce the documentation, will not generate it directly. For this reason you should go to the doc subdirectory of your build directory (i.e., the one where you compiled the library) and build all the documents you want by executing a command of the form

  make doc1 doc2 ...

Here, doc1, doc2 and so forth are either the exact names of the documents you want to build (this requires the knowledge of the library’s version number), or any of the following (easier) aliases:

  • user: builds all the configuration-independent user manuals, in all available formats;
  • user-html: the same as above, but only builds the manuals in the (.tar.gz) HTML format;
  • user-pdf: the same as above, but only builds the manuals in the PDF format;
  • user-ps: the same as above, but only builds the manuals in the (gzipped) PostScript format.

If the configuration-dependent manuals are meant, then the following target aliases should be used instead:

  • user-configured: builds the configuration-dependent user manuals, in all available formats;
  • user-configured-html: the same as above, but only builds the manuals in the (.tar.gz) HTML format;
  • user-configured-pdf: the same as above, but only builds the manuals in the PDF format;
  • user-configured-ps: the same as above, but only builds the manuals in the (gzipped) PostScript format.

The target `user-all’ will build both configuration-independent and configuration-dependent user manuals. Clearly, for the developer reference manuals, there are similar targets using the prefix `devref’ instead of `user’. Finally, the command `make world’ will build all the available documentation in all of the above formats. []{#TeX-Error}

A Common TeX Error Message and Its Solution

While compiling some PostScript or PDF documentation, it is possible that TeX dies with a TeX capacity exceeded error message. The error should contain the indication of the TeX buffer whose capacity has been exceeded, e.g.:

  ! TeX capacity exceeded, sorry [save size=5000].

You then need to edit the TeX configuration file that defines the buffer sizes so as to increase the value of the relevant buffer.

Note: the actual name and location of the configuration file will vary depending on the available TeX distribution: possible names include texmf.cnf, texmf.cfg and 20sizes.cnf.

Continuing our example, we can double save_size by editing the configuration file so that the relevant line becomes

  save_size = 10000        % for saving values outside current group

Any change to such configuration files should be followed by running a command like

  texconfig init

for the change to become effective (on some systems the texconfig-sys command should be used to configure TeX system-wide).

Last updated on
GNU GPLPapers