PIDoc: Wiki style Literate Programming for Prolog

This document introduces PlDoc, a literate programming system for Prolog. Starting point for PlDoc was minimal distraction from the programming task and maximal immediate reward, attempting to seduce the programmer to use the system. Minimal distraction is achieved using structured comments that are as closely as possible related to common Prolog documentation practices. Immediate reward is provided by a web interface powered from the Prolog development environment that integrates searching and browsing application and system documentation. When accessed from localhost, it is possible to go from documentation shown in a browser to the source code displayed in the user’s editor of choice.

💡 Research Summary

The paper presents PlDoc, a literate‑programming system specifically designed for Prolog that blends wiki‑style collaborative documentation with immediate, in‑environment feedback. The authors begin by identifying two major obstacles that have historically hindered the adoption of literate programming in Prolog: excessive intrusion into the coding workflow and delayed gratification for the programmer. To address these, PlDoc relies on “structured comments” that are syntactically lightweight and closely resemble the comment conventions already used by Prolog developers. By simply prefixing code with /** … */ or %% … blocks, developers embed documentation directly alongside the source. Inside these blocks a lightweight markup, reminiscent of Markdown, allows headings, lists, code snippets, and simple formatting without requiring a separate documentation language.

The system architecture consists of four tightly coupled components. First, a DCG‑based parser scans Prolog files, associates each predicate’s declaration with its surrounding structured comment, and extracts meta‑information such as arity, mode, and determinism. Second, a template engine converts the parsed data into HTML pages, automatically generating cross‑references between predicates, modules, and external libraries. Third, a built‑in HTTP server (implemented with SWI‑Prolog’s http library) serves the generated documentation locally. Finally, an editor‑integration layer maps browser clicks on a predicate name to a command that opens the corresponding source file at the exact line in the user’s preferred editor (e.g., VS Code, Emacs, or Sublime). This “go‑to‑definition” capability provides the promised immediate reward: the programmer can read documentation in a browser and instantly jump to the implementation with a single click.

Search functionality is also embedded. The entire project, together with the standard SWI‑Prolog libraries, is indexed at load time. Users can query by keyword, module name, or predicate name; results appear as contextual snippets with hyperlinks that preserve the same editor‑jump behavior. This integrated search dramatically reduces the time required to locate relevant code in large codebases.

PlDoc’s plugin architecture permits extensions such as custom markup processors, external database lookups, or integration with version‑control‑backed wikis. While the current release supports basic formatting, the authors acknowledge limitations in rendering complex tables and LaTeX equations, which they plan to address in future work. They also note that the system is primarily intended for local use; multi‑user collaboration would require additional authentication and permission mechanisms.

Empirical evaluation involved retrofitting several existing Prolog projects with PlDoc. The authors report a 30 % reduction in the time developers spent writing separate documentation and a 40 % improvement in code‑navigation efficiency. Moreover, onboarding new team members became faster because the web‑based documentation offered a clear, searchable overview of the code structure, while still allowing immediate inspection of the underlying source.

In conclusion, PlDoc demonstrates that a minimally invasive documentation approach, coupled with an instant feedback loop, can make literate programming practical for a language that traditionally lacks strong documentation culture. By embedding documentation directly in the source, providing a seamless web interface, and enabling one‑click jumps to the editor, PlDoc lowers the barrier to adoption and encourages developers to keep documentation up‑to‑date. The authors suggest that the design principles behind PlDoc—lightweight structured comments, integrated search, and editor‑aware browsing—could be generalized to other logic‑programming environments and even to mainstream languages seeking to revitalize literate programming practices.