[sqlite] C API reference manpages

[Kristaps Dzonsons]

> On Thu, 31 Mar 2016 10:21:53 -0400
> Richard Hipp  wrote:
> 
>> On 3/31/16, Kristaps Dzonsons  wrote:
>>>
>>> Is there any interest in integrating this tool to have manpages in
>>> the doc distribution without downstream bits?
>>>
>>
>> I think that would be cool.  Integrating your tool into the source
>> tree would mean that as the comment formats evolve, your tool would
>> evolve in lock-step.  
> 
> +1.  I'm another who's wanted SQLite man pages for a long time.  I hope
> you can see your way to integrating Kristaps's tool.  

Ping?

Any word on what can be done/I can do (CC0, whatever) to facilitate
getting our favourite database some mdoc(7) manpages?

(For those who weren't here: https://github.com/kristapsdz/sqlite2mdoc)

Best,

Kristaps

[sqlite] C API reference manpages

[Kristaps Dzonsons]

> How about the CC0 license? I think it's designed for these sorts of
> things (you want to make something public domain even if you're not
> allowed to) - https://creativecommons.org/about/cc0/

Jonathon,

I think the problem is that LV is similar to Norway[1] in this regard,
so something like CC0 doesn't work as one would expect it to.  However,
the manpages generated by sqlite2mdoc are in whatever license (or
no-license) you want, so at the end of the day, it doesn't affect the
library or its included documentation.  (After all, tcl isn't PD, and
that's required as it is!)

Licensing aside, if anybody has any comments or issues on the tool or
its mdoc(7) output, let me know!

Best,

Kristaps

[1]
http://lists.ibiblio.org/pipermail/cc-community/2014-October/thread.html#8863
(``Open Definition 2.0 released'')


-- next part --
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 842 bytes
Desc: OpenPGP digital signature
URL: 

[sqlite] C API reference manpages

[Jonathan Moules]

How about the CC0 license?
I think it's designed for these sorts of things (you want to make something 
public domain even if you're not allowed to) - 
https://creativecommons.org/about/cc0/

 On Fri, 01 Apr 2016 00:05:30 +0100 Kristaps Dzonsons  wrote  

>> As for public domain, I'm happy to put the sources under a similar 
>> license. I can't speak for the voodoo of the public domain and the EU 
>> (or is it country-by-country?), however. 
> 
> From an English translation I found of the Latvian law includes moral 
> rights and is closer to the droit d'auteur than copyright. So it seems 
> difficult to place your work in the public domain. 
> 
> I would advise you to contact the FSF, FSFE Legal or SFLC in this matter 
> if you want a general advice without legal fees. This entire topic as 
> been discussed in context of Wikimedia's projects, especially Wikipedia 
> and Wikimedia Commons, and CC0, so you might find information about 
> Latvia there. 

Matthias-Christian, 

I'm afraid I can't say anything useful about licenses, but in searching 
around, it appears that you're correct[1]. 

[sqlite] C API reference manpages

[James K. Lowden]

On Thu, 31 Mar 2016 10:21:53 -0400
Richard Hipp  wrote:

> On 3/31/16, Kristaps Dzonsons  wrote:
> >
> > Is there any interest in integrating this tool to have manpages in
> > the doc distribution without downstream bits?
> >
> 
> I think that would be cool.  Integrating your tool into the source
> tree would mean that as the comment formats evolve, your tool would
> evolve in lock-step.  

+1.  I'm another who's wanted SQLite man pages for a long time.  I hope
you can see your way to integrating Kristaps's tool.  

--jkl

[sqlite] C API reference manpages

[Kristaps Dzonsons]

>> As for public domain, I'm happy to put the sources under a similar
>> license.  I can't speak for the voodoo of the public domain and the EU
>> (or is it country-by-country?), however.
> 
> From an English translation I found of the Latvian law includes moral
> rights and is closer to the droit d'auteur than copyright. So it seems
> difficult to place your work in the public domain.
> 
> I would advise you to contact the FSF, FSFE Legal or SFLC in this matter
> if you want a general advice without legal fees. This entire topic as
> been discussed in context of Wikimedia's projects, especially Wikipedia
> and Wikimedia Commons, and CC0, so you might find information about
> Latvia there.

Matthias-Christian,

I'm afraid I can't say anything useful about licenses, but in searching
around, it appears that you're correct[1].

Assuming, arguendo, that this is true, I'm happy to continue keeping the
source where it is and tracking the header file--something I'd need to
do anyway, of course, regardless of where it sits.  Or if, as Richard
intimated, an ISC licensed file is acceptable in docsrc, it may be kept
there.  I'm open to suggestions!

Regarding the system itself, are there any desired features or
invocations that I can implement for ease of use and/or utility?  It
emits pretty standard mdoc(7) markup except for the IMPLEMENTATION
NOTES, which is non-canonical (but documented), where I stash the actual
declarations themselves.  In short, the manpages have everything in them
that I would need as a user.

Best,

Kristaps

[1] http://www.satori.lv/raksts/4336/Autortiesibasunbriva_kultura
(Link contents in Latvian.)

[sqlite] C API reference manpages

[Matthias-Christian Ott]

On 31/03/16 14:39, Kristaps Dzonsons wrote:
>>> Is there any interest in integrating this tool to have manpages in the
>>> doc distribution without downstream bits?
>>
>> I think that would be cool.  Integrating your tool into the source
>> tree would mean that as the comment formats evolve, your tool would
>> evolve in lock-step.  If your tool is kept separate, then we might
>> change the documentation comment format without telling you, and break
>> things.
>>
>> One issue is the license.  SQLite is public domain, not BSD (or ISC).
>> Is it even possible for citizens of Latvia to release something to the
>> public domain?  In any event, some paperwork would have to flow
>> between us to make that happen.  Though, maybe that is not a huge
>> concern as we are not nearly as persnickety with licensing for the
>> documentation as we are with the code, and this tool would go in the
>> separate documentation repository
>> (https://www.sqlite.org/docsrc/timeline), not in the main code
>> repository.
>>
>> Would an even better solution be to enhance the capi3ref TCL script to
>> spit out mdoc files in parallel to the HTML documentation it currently
>> produces?
> 
> Richard,
> 
> As for public domain, I'm happy to put the sources under a similar
> license.  I can't speak for the voodoo of the public domain and the EU
> (or is it country-by-country?), however.

>From an English translation I found of the Latvian law includes moral
rights and is closer to the droit d'auteur than copyright. So it seems
difficult to place your work in the public domain.

I would advise you to contact the FSF, FSFE Legal or SFLC in this matter
if you want a general advice without legal fees. This entire topic as
been discussed in context of Wikimedia's projects, especially Wikipedia
and Wikimedia Commons, and CC0, so you might find information about
Latvia there.

- Matthias-Christian

[sqlite] C API reference manpages

[Kristaps Dzonsons]

>> Is there any interest in integrating this tool to have manpages in the
>> doc distribution without downstream bits?
> 
> I think that would be cool.  Integrating your tool into the source
> tree would mean that as the comment formats evolve, your tool would
> evolve in lock-step.  If your tool is kept separate, then we might
> change the documentation comment format without telling you, and break
> things.
> 
> One issue is the license.  SQLite is public domain, not BSD (or ISC).
> Is it even possible for citizens of Latvia to release something to the
> public domain?  In any event, some paperwork would have to flow
> between us to make that happen.  Though, maybe that is not a huge
> concern as we are not nearly as persnickety with licensing for the
> documentation as we are with the code, and this tool would go in the
> separate documentation repository
> (https://www.sqlite.org/docsrc/timeline), not in the main code
> repository.
> 
> Would an even better solution be to enhance the capi3ref TCL script to
> spit out mdoc files in parallel to the HTML documentation it currently
> produces?

Richard,

As for public domain, I'm happy to put the sources under a similar
license.  I can't speak for the voodoo of the public domain and the EU
(or is it country-by-country?), however.

As for Tcl--I don't grok it myself or I'd have started modifying there.
 (I used capi3ref as a starting point.)  Be it C or Tcl, there's a lot
of string fiddling to get everything formatted for mdoc(7) (and to
collect refs), so it won't be pretty (or brief) in any language.

I'm happy maintaining the tool in or out of the tree--whatever's most
convenient.  I figured I'd just track changes to sqlite.h.in and update
the scanner if it was required.  (E.g. and in the most likely case: more
HTML tags.)  At the end of the day, I just want to use apropos and man
instead of the browser!

Best,

Kristaps

-- next part --
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 842 bytes
Desc: OpenPGP digital signature
URL: 

[sqlite] C API reference manpages

[Kristaps Dzonsons]

Hello,

I couldn't find any way to convert the SQLite docs (via sqlite.h) to
UNIX manpages, so I wrote a tool that does so:

 https://github.com/kristapsdz/sqlite2mdoc

This generates one manpage per API reference with the proper SEE ALSO
(from collected references) and IMPLEMENTATION NOTES (the raw
declarations and preprocessor statements).  Its deficiencies are in
handling HTML tables (prints verbatim--not bad except for sqlite3_open,
where the table is quite wide), the mdoc(7) isn't picture-perfect, and
in handling some un-closed markup seen here and there.

It follows the logic of the Tcl code in capi3ref[2], but does so in C
w/o dependencies unless running Linux.

Is there any interest in integrating this tool to have manpages in the
doc distribution without downstream bits?

I've been using this for a while as part of the manpage corpus on my
OpenBSD, Mac OS X, and Linux machines.

Best,

Kristaps

[1] http://man.openbsd.org/OpenBSD-current/man7/mdoc.7
[2] https://www.sqlite.org/cgi/docsrc/finfo?name=pages/capi3ref.in

[sqlite] C API reference manpages

[Richard Hipp]

On 3/31/16, Kristaps Dzonsons  wrote:
>
> Is there any interest in integrating this tool to have manpages in the
> doc distribution without downstream bits?
>

I think that would be cool.  Integrating your tool into the source
tree would mean that as the comment formats evolve, your tool would
evolve in lock-step.  If your tool is kept separate, then we might
change the documentation comment format without telling you, and break
things.

One issue is the license.  SQLite is public domain, not BSD (or ISC).
Is it even possible for citizens of Latvia to release something to the
public domain?  In any event, some paperwork would have to flow
between us to make that happen.  Though, maybe that is not a huge
concern as we are not nearly as persnickety with licensing for the
documentation as we are with the code, and this tool would go in the
separate documentation repository
(https://www.sqlite.org/docsrc/timeline), not in the main code
repository.

Would an even better solution be to enhance the capi3ref TCL script to
spit out mdoc files in parallel to the HTML documentation it currently
produces?

-- 
D. Richard Hipp
drh at sqlite.org