mangen

A command-line tool to generate Linux manual pages from C source code.

Description

mangen is, as said above, a program to generate Linux manual pages from C source code. At invocation, mangen is given a type of token to generate manual pages for, like a file overview, or for specific functions, and then it is given files to operate on.

Example using looks like so:

mangen token [FILE] ... [OPTIONS]

Tokens

mangen can handle several types of tokens to generate manual pages for. What follows is each token, and a brief explanation of it.

overview - produce an 'overview' of all the files given, using block comments at the top of the file, as well as some other parts of the file to generate the manual page, like for constants.

function - produce unique manual pages for each function in each source code file provided, extracting data from a block comment at the top of each function.

Design

To keep things modular, and possibly extendable, mangen generators are segmented into their own files, and are invoked through mangen's entry point. When the correct token is determined, the arguments are passed to the chosen generator, where argument parsing continues. This allows for individual generators to have their own configuration.

When mangen is invoked, mangen will create a new mangen-docs folder, where the chosen generator will dump its manuals into. However, the generator will make its own unique folder inside of mangen-docs. For example, mangen overview will create a folder named overview inside mangen-docs. This is to keep things organized.

Syntax

mangen's syntax is composed of 'tags' which act as directives to the generator of choice. All tags are grouped inside of a 'start' and 'end' tag. For example, an overview of a main file might be:

/*
* @mg_start
* Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer sagittis
* turpis et nulla vulputate tristique. Maecenas euismod urna ut nulla eleifend
* vulputate. Nullam non augue vel dolor cursus volutpat nec vel diam. Vivamus
* nec arcu lacus. Praesent a eros a nunc gravida egestas tincidunt nec dui.
* Donec ut laoreet magna.
* @mg_end
*/

Where tags can be parsed, they must be grouped inside of an mg_start and mg_end tag. Inside of these groups, there are 'blocks' and 'attributes.' Blocks are used to group text into sections, like a description, or synopsis. An attribute is a one-line tag that is used to attach metadata to the manual page, like version number, standards conforming, etc. For example:

/*
 * @mg_start
 * @description_start
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer sagittis
 * turpis et nulla vulputate tristique. Maecenas euismod urna ut nulla eleifend
 * vulputate. Nullam non augue vel dolor cursus volutpat nec vel diam. Vivamus
 * nec arcu lacus. Praesent a eros a nunc gravida egestas tincidunt nec dui.
 * Donec ut laoreet magna.
 * @description_end
 *
 * @conforming This program conforms to C89.
 * @see_also lorem(3), ipsum(3), dolor(3)
 *
 * @mg_end
*/

An important tag that must be included in every block is the 'type' tag. This describes what kind of group it is describing, like a function, macro, or overview. Building upon our previous example:

/*
 * @mg_start
 * @type function
 *
 * @description_start
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer sagittis
 * turpis et nulla vulputate tristique. Maecenas euismod urna ut nulla eleifend
 * vulputate. Nullam non augue vel dolor cursus volutpat nec vel diam. Vivamus
 * nec arcu lacus. Praesent a eros a nunc gravida egestas tincidunt nec dui.
 * Donec ut laoreet magna.
 * @description_end
 *
 * @conforming This program conforms to C89.
 * @see_also lorem(3), ipsum(3), dolor(3)
 *
 * @mg_end
*/

The 'type' tag must always be the first tag after mg_start.

Rationale

To put it simply, I feel like manual pages (and offline documentation in general) is quite an underrated resource. I find that roff, while not terrible, often times involves writing what is essentially boilerplate in textual form. It is also irritating to search through existing manual pages to update things when I could simply have a tool automatically regenerate it, while also taking advantage of something such as Make for generating documentation.