This commit is contained in:
christos
parent
6952a2b793
commit
b817d38134
|
|
@ -0,0 +1,14 @@
|
|||
Copyright (c) 2012--2016, Kristaps Dzonsons <kristaps@bsd.lv>
|
||||
|
||||
Permission to use, copy, modify, and/or 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.
|
||||
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
# If you're on Linux, un-comment the following.
|
||||
#LDADD = -lbsd
|
||||
|
||||
#####################################################################
|
||||
# You probably don't want to change anything beneath here.
|
||||
#####################################################################
|
||||
|
||||
CFLAGS += -g -W -Wall
|
||||
PREFIX = /usr/local
|
||||
|
||||
sqlite2mdoc: main.o
|
||||
$(CC) -o $@ main.o $(LDADD)
|
||||
|
||||
install:
|
||||
mkdir -p $(DESTDIR)$(PREFIX)/bin
|
||||
mkdir -p $(DESTDIR)$(PREFIX)/man/man1
|
||||
install -m 0755 sqlite2mdoc $(DESTDIR)$(PREFIX)/bin
|
||||
install -m 0444 sqlite2mdoc.1 $(DESTDIR)$(PREFIX)/man/man1
|
||||
|
||||
clean:
|
||||
rm -f sqlite2mdoc main.o
|
||||
rm -rf sqlite2mdoc.dSYM
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
## Synopsis
|
||||
|
||||
This utility accepts an [SQLite](https://www.sqlite.org) header file
|
||||
`sqlite.h` and produces a set of decently well-formed
|
||||
[mdoc(7)](http://man.openbsd.org/OpenBSD-current/man7/mdoc.7) files
|
||||
documenting the C API.
|
||||
These will be roughly equivalent to the [C-language Interface
|
||||
Specification for SQLite](https://www.sqlite.org/c3ref/intro.html).
|
||||
|
||||
You can also use it for any file(s) using the documentation standards of
|
||||
SQLite.
|
||||
See the [sqlite2mdoc.1](sqlite2mdoc.1) manpage for syntax details.
|
||||
|
||||
This [GitHub](https://www.github.com) repository is a read-only mirror
|
||||
of the project's CVS repository.
|
||||
|
||||
## Installation
|
||||
|
||||
Simply run `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 unless you're on
|
||||
Linux, in which case you'll need
|
||||
[libbsd](https://libbsd.freedesktop.org).
|
||||
You'll also need to uncomment the `LDADD` line in the
|
||||
[Makefile](Makefile), in this case.
|
||||
|
||||
|
||||
This software has been used on OpenBSD, Mac OS X, and Linux machines.
|
||||
|
||||
## License
|
||||
|
||||
All sources use the ISC (like OpenBSD) license.
|
||||
See the [LICENSE.md](LICENSE.md) file for details.
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,129 @@
|
|||
.Dd $Mdocdate: March 28 2016 $
|
||||
.Dt SQLITE2MDOC 1
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm sqlite2mdoc
|
||||
.Nd extract C reference manpages from SQLite header file
|
||||
.Sh SYNOPSIS
|
||||
.Nm sqlite2mdoc
|
||||
.Op Fl nv
|
||||
.Op Fl p Ar prefix
|
||||
.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
|
||||
Don't create files in
|
||||
.Ar prefix :
|
||||
just dump everything to stdout.
|
||||
.It Fl v
|
||||
Show all missing references.
|
||||
.It Fl p Ar prefix
|
||||
Output into
|
||||
.Ar prefix ,
|
||||
which must already exist.
|
||||
.El
|
||||
.Pp
|
||||
This tool was designed for SQLite's header file
|
||||
.Pa sqlite.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.
|
||||
.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).
|
||||
**
|
||||
** 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 kristaps@bsd.lv .
|
||||
.Sh CAVEATS
|
||||
There are some missing bits:
|
||||
.Bl -bullet
|
||||
.It
|
||||
HTML tables are not parsed.
|
||||
.It
|
||||
HTML anchors are not parsed.
|
||||
.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
|
||||
Absolutely.
|
||||
.\" .Sh SECURITY CONSIDERATIONS
|
||||
.\" Not used in OpenBSD.
|
||||
Loading…
Reference in New Issue