kristapsdz / sqlite2mdoc

extract C reference manpages from SQLite header file

Synopsis

This utility accepts an SQLite header file sqlite3.h and produces a set of decently well-formed mdoc(7) files documenting the C API. These will be roughly equivalent to the C-language Interface Specification for SQLite.

You can also use it for any file(s) using the documentation standards of SQLite. See the sqlite2mdoc.1 manpage for syntax details.

Note: this only works with sqlite3, not the original sqlite.h format.

Release snapshots are archived in https://kristaps.bsd.lv/sqlite2mdoc/snapshots.

Installation

Run ./configure then make.

This utility isn't meant for installation, but for integration into your SQLite deployment phase. You can run make install, however, if you plan on using it for other documentation.

There are no compile-time or run-time dependencies.

This software has been tested and run on OpenBSD, FreeBSD, NetBSD, IllumOS, Solaris, Mac OS X, and Linux (glibc and musl).

Examples

I've used mandoc to generate some Markdown from the mdoc(7) output.

• sqlite3_open(3)
• SQLITE_FCNTL_LOCKSTATE(3)

License

All sources use the ISC (like OpenBSD) license. See the LICENSE.md file for details.

sqlite2mdoc's Issues

warning: ‘fgetln’ is deprecated: This functions cannot be safely ported, use getline(3) instead

Linux, fedora27, gcc 7.2.1 20170915 (Red Hat 7.2.1-2)

main.c: In function ‘main’:
main.c:1677:2: warning: ‘fgetln’ is deprecated: This functions cannot be safely ported, use getline(3) instead, as it is supported by GNU and POSIX.1-2008. [-Wdeprecated-declarations]
  while (NULL != (cp = fgetln(f, &len))) {
  ^~~~~
In file included from main.c:38:0:
/usr/include/bsd/stdio.h:53:7: note: declared here
 char *fgetln(FILE *fp, size_t *lenp)
       ^~~~~~
cc -o sqlite2mdoc main.o -lbsd
main.o: In function `main':
main.c:(.text.startup+0x1db): warning: This functions cannot be safely ported, use getline(3) instead, as it is supported by GNU and POSIX.1-2008.

fails with sqlite 3.41.2 ?

on the recent sqlite versions, producing the mdoc/manpage fails:

/usr/local/bin/sqlite2mdoc -p /usr/obj/ports/sqlite3-3.41.2/fake-amd64/usr/local/man/man3 /usr/obj/ports/sqlite3-3.41.2/fake-amd64/usr/local/include/sqlite3.h
sqlite2mdoc: /usr/obj/ports/sqlite3-3.41.2/fake-amd64/usr/local/include/sqlite3.h:768: warn: unexpected end of interface description
sqlite2mdoc: /usr/obj/ports/sqlite3-3.41.2/fake-amd64/usr/local/include/sqlite3.h:733: interface has errors, not producing manpage