-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathsqlite2mdoc.1
157 lines (157 loc) · 4.74 KB
/
sqlite2mdoc.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
.\"
.\" Copyright (c) Kristaps Dzonsons <[email protected]>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt SQLITE2MDOC 1
.Os
.Sh NAME
.Nm sqlite2mdoc
.Nd extract C reference manpages from SQLite header file
.Sh SYNOPSIS
.Nm sqlite2mdoc
.Op Fl Nnv
.Op Fl p Ar prefix
.Op Ar file
.Sh DESCRIPTION
The
.Nm
utility extracts C interface descriptions from a header file composed
using the SQLite documentation syntax (see
.Sx SYNTAX ) .
It then emits the corresponding set of
.Xr mdoc 7
manpages, one per interface description.
By default,
.Nm
reads from standard input and outputs files into the current directory.
Its arguments are as follows:
.Bl -tag -width Ds
.It Fl N
Emit only the manpage names that would be created.
Automatically sets
.Fl n
and ignores
.Fl p Ar prefix .
.It Fl n
Don't create files in
.Ar prefix :
just dump everything to stdout.
.It Fl v
Show parse and link warnings.
.It Fl p Ar prefix
Output into
.Ar prefix ,
which must already exist.
.El
.Pp
This tool was designed for SQLite3's header file
.Pa sqlite3.h ,
although it will work for any document following the
.Sx SYNTAX .
Historically, all of the SQLite C reference documentation (called the
.Dq C-language Interface Specification )
was only available in HTML.
.Pp
The
.Xr mdoc 7
pages generated by
.Nm
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.
.Sh SYNTAX
The syntax for the interface descriptions is as follows:
.Bd -literal
/*
** 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). Tables, anchors, and some
** other HTML are also supported.
**
** 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);
.Ed
.Pp
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.
.Pp
There are many SQLite-specific bits that are purposely not documented so
that people don't use them.
.\" .Sh CONTEXT
.\" For section 9 functions only.
.\" .Sh IMPLEMENTATION NOTES
.\" Not used in OpenBSD.
.\" .Sh RETURN VALUES
.\" For sections 2, 3, and 9 function return values only.
.\" .Sh ENVIRONMENT
.\" For sections 1, 6, 7, and 8 only.
.\" .Sh FILES
.Sh EXIT STATUS
.Ex -std
.\" For sections 1, 6, and 8 only.
.\" .Sh EXAMPLES
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.\" .Sh ERRORS
.\" For sections 2, 3, 4, and 9 errno settings only.
.Sh SEE ALSO
.Xr mdoc 7 ,
.Lk https://www.sqlite.org/capi3ref.html "C-language Interface Specification for SQLite"
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh AUTHORS
.Nm
was written by
.An Kristaps Dzonsons Aq Mt [email protected] .
.Sh CAVEATS
There are some missing bits:
.Bl -bullet
.It
Obviously-broken HTML (e.g., unmatched </dt>) isn't worked around.
.It
Structure definitions are discarded except for the structure name.
.It
Comments in definitions will cause extra white-space.
.El
.\" .Sh BUGS
.\" .Sh SECURITY CONSIDERATIONS
.\" Not used in OpenBSD.