1.Dd $Mdocdate: March 28 2016 $ 2.Dt SQLITE2MDOC 1 3.Os 4.Sh NAME 5.Nm sqlite2mdoc 6.Nd extract C reference manpages from SQLite header file 7.Sh SYNOPSIS 8.Nm sqlite2mdoc 9.Op Fl nv 10.Op Fl p Ar prefix 11.Sh DESCRIPTION 12The 13.Nm 14utility extracts C interface descriptions from a header file composed 15using the SQLite documentation syntax (see 16.Sx SYNTAX ) . 17It then emits the corresponding set of 18.Xr mdoc 7 19manpages, one per interface description. 20By default, 21.Nm 22reads from standard input and outputs files into the current directory. 23Its arguments are as follows: 24.Bl -tag -width Ds 25.It Fl n 26Don't create files in 27.Ar prefix : 28just dump everything to stdout. 29.It Fl v 30Show all missing references. 31.It Fl p Ar prefix 32Output into 33.Ar prefix , 34which must already exist. 35.El 36.Pp 37This tool was designed for SQLite's header file 38.Pa sqlite.h , 39although it will work for any document following the 40.Sx SYNTAX . 41Historically, all of the SQLite C reference documentation (called the 42.Dq C-language Interface Specification ) 43was only available in HTML. 44.Sh SYNTAX 45The syntax for the interface descriptions is as follows: 46.Bd -literal 47/* 48** CAPI3REF: A Brief Description Here 49** KEYWORDS: {multiword keyword} single_keyword 50** 51** This is a longer description following the blank line. 52** You can refer to [other descriptions] by enclosing references to 53** keywords (or declaration names) in brackets. 54** If the brackets have [some_keyword | a bar] within them, the 55** second part is shown while the first is used as a reference. 56** Each reference will be collected and its corresponding manpage, 57** if found, will be listed in SEE ALSO. 58** 59** You can embed <b>HTML</b>, but you must limit this to lists 60** (ordered, unordered, description). 61** 62** See also: [another_keyword], although since we're the only 63** reference, none of these will be found. 64** Anything not in [function() | quotes] will be discarded. 65** 66** Now we end the comment. Anything after this, until the next 67** blank line, is taken as declarations. 68*/ 69int function_name(char *anarg, char *another); 70#define A_DEFINITION "text" 71struct a_struct { 72 struct embedded_struct { 73 int foo; 74 int bar; 75 }; 76}; 77typedef void (*fptr)(const char *a, const char *b); 78.Ed 79.Pp 80It's important that the opening and closing comment parts are flush left 81and not followed by spaces. 82Paragraph breaks (empty comment lines) should also not have any spaces. 83.Pp 84There are many SQLite-specific bits that are purposely not documented so 85that people don't use them. 86.\" .Sh CONTEXT 87.\" For section 9 functions only. 88.\" .Sh IMPLEMENTATION NOTES 89.\" Not used in OpenBSD. 90.\" .Sh RETURN VALUES 91.\" For sections 2, 3, and 9 function return values only. 92.\" .Sh ENVIRONMENT 93.\" For sections 1, 6, 7, and 8 only. 94.\" .Sh FILES 95.Sh EXIT STATUS 96.Ex -std 97.\" For sections 1, 6, and 8 only. 98.\" .Sh EXAMPLES 99.\" .Sh DIAGNOSTICS 100.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. 101.\" .Sh ERRORS 102.\" For sections 2, 3, 4, and 9 errno settings only. 103.Sh SEE ALSO 104.Xr mdoc 7 , 105.Lk https://www.sqlite.org/capi3ref.html "C-language Interface Specification for SQLite" 106.\" .Sh STANDARDS 107.\" .Sh HISTORY 108.Sh AUTHORS 109.Nm 110was written by 111.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 112.Sh CAVEATS 113There are some missing bits: 114.Bl -bullet 115.It 116HTML tables are not parsed. 117.It 118HTML anchors are not parsed. 119.It 120Obviously-broken HTML (e.g., unmatched </dt>) isn't worked around. 121.It 122Structure definitions are discarded except for the structure name. 123.It 124Comments in definitions will cause extra white-space. 125.El 126.Sh BUGS 127Absolutely. 128.\" .Sh SECURITY CONSIDERATIONS 129.\" Not used in OpenBSD. 130