SQLITE2MDOC(1)

NAME
sqlite2mdoc - extract C reference manpages from SQLite header file

SYNOPSIS
sqlite2mdoc [-nv] [-p prefix] [file]

DESCRIPTION
The sqlite2mdoc utility extracts C interface descriptions from a header file composed using the SQLite documentation syntax (see SYNTAX). It then emits the corresponding set of mdoc(7) manpages, one per interface description. By default, sqlite2mdoc reads from standard input and outputs files into the current directory. Its arguments are as follows:

-n  Don't create files in prefix: just dump everything to stdout.

-N  Emit only the manpage names that would be created. Automatically sets -n and ignores -p prefix.

-v  Show all missing references.

-p prefix
    Output into prefix, which must already exist.

This tool was designed for SQLite3's header file sqlite3.h, although it will work for any document following the SYNTAX. Historically, all of the SQLite C reference documentation (called the “C-language Interface Specification”) was only available in HTML.

The mdoc(7) pages generated by sqlite2mdoc consist of the usual prologue, the NAME section consisting of all extracted function or preprocessor parts and the description, the main DESCRIPTION body of the documentation, the raw declarations and preprocessor statements in an IMPLEMENTATION NOTES section, and all references collected into the SEE ALSO.

SYNTAX
The syntax for the interface descriptions is as follows:

    /*
    ** CAPI3REF: A Brief Description Here
    ** KEYWORDS: {multiword keyword} single_keyword
    **
    ** This is a longer description following the blank line.
    ** You can refer to [other descriptions] by enclosing references to
    ** keywords (or declaration names) in brackets.
    ** If the brackets have [some_keyword | a bar] within them, the
    ** second part is shown while the first is used as a reference.
    ** Each reference will be collected and its corresponding manpage,
    ** if found, will be listed in SEE ALSO.
    **
    ** You can embed <b>HTML</b>, but you must limit this to lists
    ** (ordered, unordered, description).
    **
    ** See also: [another_keyword], although since we're the only
    ** reference, none of these will be found.
    ** Anything not in [function() | quotes] will be discarded.
    **
    ** Now we end the comment.  Anything after this, until the next
    ** blank line, is taken as declarations.
    */
    int function_name(char *anarg, char *another);
    #define A_DEFINITION "text"
    struct a_struct {
    	struct embedded_struct {
    		int foo;
    		int bar;
    	};
    };
    typedef void (*fptr)(const char *a, const char *b);

It's important that the opening and closing comment parts are flush left and not followed by spaces. Paragraph breaks (empty comment lines) should also not have any spaces.

There are many SQLite-specific bits that are purposely not documented so that people don't use them.

EXIT STATUS

SEE ALSO
mdoc(7), C-language Interface Specification for SQLite: https://www.sqlite.org/capi3ref.html

AUTHORS
sqlite2mdoc was written by Kristaps Dzonsons <kristaps@bsd.lv>.

CAVEATS
There are some missing bits:

•   Obviously-broken HTML (e.g., unmatched </dt>) isn't worked around. Some HTML (like tables and anchors) is just thrown away.

•   Structure definitions are discarded except for the structure name.

•   Comments in definitions will cause extra white-space.

BUGS
Absolutely.