Abstract
We describe lpdoc, a tool which generates documentation manuals automatically from one or more logic program source files, written in Ciao, ISO-Prolog, and other (C)LP languages. It is particularly useful for documenting library modules, for which it automatically generates a rich description of the module interface. However, it can also be used quite successfully to document full applications. A fundamental advantage of using lpdoc is that it helps maintaining a true correspondence between the program and its documentation, and also identifying precisely to what version of the program a given printed manual corresponds. The quality of the documentation generated can be greatly enhanced by including within the program text assertions (declarations with types, modes, etc....) for the predicates in the program, and machine-readable comments. One of the main novelties of lpdoc is that these assertions and comments are written using the Ciao system assertion language, which is also the language of communication between the compiler and the user and between the components of the compiler. This allows a significant synergy among specification, debugging, documentation, optimization, etc. A simple compatibility library allows conventional (C)LP systems to ignore these assertions and comments and treat normally programs documented in this way. The documentation can be generated interactively from emacs or from the command line, in many formats including texinfo, dvi, ps, pdf, info, ascii, html/css, Unix nroff/man, Windows help, etc., and can include bibliographic citations and images. lpdoc can also generate “man” pages (Unix man page format), nicely formatted plain ASCII “readme” files, installation scripts useful when the manuals are included in software distributions, brief descriptions in html/css or info formats suitable for inclusion in on-line indices of manuals, and even complete WWW and info sites containing on-line catalogs of documents and software distributions. The lpdoc manual, all other Ciao system manuals, and parts of this paper are generated by lpdoc.
This is a preview of subscription content, log in via an institution to check access.
Access this chapter
Tax calculation will be finalised at checkout
Purchases are for personal use only
Preview
Unable to display preview. Download preview PDF.
References
F. Bueno, D. Cabeza, M. Carro, M. Hermenegildo, P. López-García, and G. Puebla. The Ciao Prolog System. Reference Manual. TR CLIP3/97.1, School of Computer Science, Technical University of Madrid (UPM), August 1997.
D. Cabeza and M. Hermenegildo. A New Module System for Prolog. In International Conference on Computational Logic, CL2000, LNCS. Springer-Verlag, July 2000. To appear.
D. Cabeza and M. Hermenegildo. The Ciao Modular, Standalone Compiler and Its Generic Program Processing Library. In Special Issue on Parallelism and Implementation of (C)LP Systems. To appear, Electronic Notes in Theoretical Computer Science. Elsevier-North Holland, 2000.
D. Cordes and M. Brown. The Literate Programming Paradigm. IEEE Computer Magazine, June 1991.
B. Demoen, M. Garcia de la Banda, W. Harvey, K. Marriott, and P. Stuckey. Herbrand Constraint Solving in HAL. In Int. Conf. on Logic Programming. MIT Press, Cambridge, MA, U.S.A., November 1999.
P. Deransart, A. Ed-Dbali, and L. Cervoni. Prolog: The Standard. Springer-Verlag, 1996.
Lisa Friendly. The Design of Distributed Hyperlink Program Documentation. In Int’l. WS on Hypermedia Design, Workshops in Computing. Springer, June 1996. Available from http://java.sun.com/docs/javadoc-paper.html.
M. Hermenegildo, F. Bueno, G. Puebla, and P. López-García. Program Analysis, Debugging and Optimization Using the Ciao System Preprocessor. In 1999 International Conference on Logic Programming, pages 52–66, Cambridge, MA, November 1999. MIT Press.
M. Hermenegildo and The CLIP Group. An Automatic Documentation Generator for (C)LP-Reference Manual. The Ciao System Documentation Series-TR CLIP5/97.3, Facultad de Informática, UPM, August 1997.
M. Hermenegildo, G. Puebla, and F. Bueno. Using Global Analysis, Partial Specifications, and an Extensible Assertion Language for Program Validation and Debugging. In K. R. Apt, V. Marek, M. Truszczynski, and D. S. Warren, editors, The Logic Programming Paradigm: a 25-Year Perspective, pages 161–192. Springer-Verlag, July 1999.
D. Knuth. Literate programming. Computer Journal, 27:97–111, 1984.
G. Puebla, F. Bueno, and M. Hermenegildo. An Assertion Language for Debugging of Constraint Logic Programs. In ILPS’97 WS on Tools and Environments for (C)LP, October 1997. ftp://clip.dia.fi.upm.es/pub/papers/assert/langtrdiscipldeliv.ps.gz
G. Puebla, F. Bueno, and M. Hermenegildo. An Assertion Language for Debugging of Constraint Logic Programs. In P. Deransart, M. Hermenegildo, and J. Maluszynski, editors, Analysis and Visualization Tools for Constraint Programming, LNCS. Springer-Verlag, 2000. To appear.
G. Puebla and M. Hermenegildo. Some Issues in Analysis and Specialization of Modular Ciao-Prolog Programs. In Special Issue on Optimization and Implementation of Declarative Programming Languages, volume 30 of Electronic Notes in Theoretical Computer Science. Elsevier-North Holland, March 2000.
Z. Somogyi, F. Henderson, and T. Conway. The execution algorithm of Mercury: an efficient purely declarative logic programming language. JLP, 29(1–3), October 1996.
Author information
Authors and Affiliations
Editor information
Editors and Affiliations
Rights and permissions
Copyright information
© 2000 Springer-Verlag Berlin Heidelberg
About this paper
Cite this paper
Hermenegildo, M. (2000). A Documentation Generator for (C)LP Systems. In: Lloyd, J., et al. Computational Logic — CL 2000. CL 2000. Lecture Notes in Computer Science(), vol 1861. Springer, Berlin, Heidelberg. https://doi.org/10.1007/3-540-44957-4_90
Download citation
DOI: https://doi.org/10.1007/3-540-44957-4_90
Published:
Publisher Name: Springer, Berlin, Heidelberg
Print ISBN: 978-3-540-67797-0
Online ISBN: 978-3-540-44957-7
eBook Packages: Springer Book Archive