Automatic Manual Page Generation

Maintaining manual pages is a very tedious task. At best it involves hand editing the manual page source every time a new feature is added (that is user visible), but often degenerates to periodic mass uptakes of numerous changes into the manual page. Manual page source is also reasonable annoying to write and very particular about placement and syntax. A simple command entry in the xmms2(1) man page might look like:

.TP .I remove playlist_position Removes a song from the playlist at the position given by .I playlist_position.

Clearly just writing the entries can be tedious but it is also a pain to dig through the source and help output of the command to determine just how a command works and how it should be used.

With this in mind I offer a proposal for automatically generating the more dynamic parts of the manual pages from comments in the source files, much like is done for the API using Doxygen.

Supported Sections

Initial support for the dynamic generation of manual page sections will be for:

Commands
Options
Files
Environmental Variables
Additional Sections (this is currently intended for generating the ET Packet specfication, but could be used for anything that followed a similar list format and was composed of dynamic content)

Comment Format

Manual Page Template

Much of the text in the manual page is best left done by hand. Particularly the description, and even the history and Author sections are not worth automating (or possibly made worse by automating). With that in mind, the proposed implementation will work with a manual page template. The template will consist of the static bits of the manual page with Template Commands in the places where dynamic content would be. The current opening of xmms2(1) looks something like,

.\" Begin Preamble .TH XMMS2 1 .SH NAME .I xmms2 offers a simple command-line interface to the .B XMMS2 daemon. .\" End Preamble .\" Begin Synopsis .SH SYNOPSIS .I xmms2 .B command .P .I xmms2 .B mlib .B command .P .\" End Synopsis

With templating it may become something like,

.\" ##Template [Preamble]## .\" ##Template [Synopsis]##

The preamble and synopsis text will be automatically generated from the Master Manual Page comment.

This method will follow through into later sections of the manual page as well. The current command listing in xmms2(1) begins something like this:

.\" Begin Command-Preamble .I xmms2 includes many commands that allow the user to execute actions on .I xmms2d. .TP .BR These commands are currently recognized: .\" End Command-Preamble .\" Begin Command-List[1] .TP .I add url Adds a URL to the playlist. .\" End Command-List[1] .\" Begin Command-List[2] .TP .I addid medialib_id Adds a song to the playlist using its Media Library ID. .\" End Command-List[2] .\" Command-List continues...