add option to open SQLite3 database read-only

from https://gist.github.com/ippeiukai/8034454
Minor cleanup for previous commit

Use typecast_value_boolean instead of !! for converting read_only
flag.  This allows you to turn it off/on using a connection
string parameter.

Also, update the RDoc method formatting and add note to database
connection guide.