manual: HTML updates in lib/db and db manual pages and README files

This PR provides minor HTML fixes to `lib/db/` and `db/` manual related files: - convert several `README` to `README.md` - update selected broken URLs - partially sync `grass-mysql.html` and `grass-mesql.html` incl. section order
OSGeo · Nov 24, 2024 · eded569 · eded569
1 parent bea8435
commit eded569
Show file tree

Hide file tree

Showing 12 changed files with 164 additions and 176 deletions.
diff --git a/db/db.connect/db.connect.html b/db/db.connect/db.connect.html
@@ -36,7 +36,7 @@ <h3>SQLite (default backend)</h3>
 <h3>PostgreSQL (local connection)</h3>
 
 Local storage, database tables stored in database "mydb"
-(may require the use of <em><a href=db.login.html>db.login</a></em>):
+(may require the use of <em><a href="db.login.html">db.login</a></em>):
 <br>
 <div class="code"><pre>
 db.connect driver=pg database=mydb
@@ -49,7 +49,7 @@ <h3>PostgreSQL (local connection)</h3>
 <h3>PostgreSQL (network connection)</h3>
 
 Network storage, database tables stored in database "mydb"
-(may require the use of <em><a href=db.login.html>db.login</a></em>):
+(may require the use of <em><a href="db.login.html">db.login</a></em>):
 <br>
 <div class="code"><pre>
 db.connect driver=pg database=mydb
@@ -62,7 +62,7 @@ <h3>PostgreSQL (network connection)</h3>
 <h3>MySQL (local connection)</h3>
 
 Local storage, database tables stored in database "mydb" (may require
-the use of <em><a href=db.login.html>db.login</a></em>):
+the use of <em><a href="db.login.html">db.login</a></em>):
 <br>
 <div class="code"><pre>
 db.connect driver=mysql database=mydb
@@ -75,7 +75,7 @@ <h3>MySQL (local connection)</h3>
 <h3>MySQL (network connection)</h3>
 
 Network storage, database tables stored in database "mydb"
-(may require the use of <em><a href=db.login.html>db.login</a></em>):
+(may require the use of <em><a href="db.login.html">db.login</a></em>):
 <br>
 <div class="code"><pre>
 db.connect driver=mysql database=mydb
@@ -88,7 +88,7 @@ <h3>MySQL (network connection)</h3>
 <h3>ODBC</h3>
 
 Network storage, database tables stored in database "mydb"
-(may require the use of <em><a href=db.login.html>db.login</a></em>):
+(may require the use of <em><a href="db.login.html">db.login</a></em>):
 <br>
 <div class="code"><pre>
 db.connect driver=odbc database=mydb

diff --git a/db/drivers/README b/db/drivers/README
diff --git a/db/drivers/README.md b/db/drivers/README.md
@@ -0,0 +1,30 @@
+This directory contains drivers for the DBMI library.
+The driver functions are for internal usage.
+
+The DBMI API to be used for module programming is available in:
+`lib/db/`
+
+NOTE:
+`db__driver_*` functions are implemented in a driver. If some of them
+are not used or defined, the driver will use stub functions in
+`lib/db/stubs/`.
+
+For some platforms like Cygwin, multiply defined symbols are not
+resolved in a way that UNIX does. Even worse is that it is impossible
+to build shared libraries with undefined symbols. For example,
+`libgrass*dbmidriver.so` cannot be built without any implementations
+of `db__driver*\*` functions which should be specific to a db driver.
+
+To work around this problem, function pointers are defined to use
+driver's implementations instead of those of the db stubs library.
+To do this automatically, run `../mk_dbdriver_h.sh` (GRASS GIS 6)
+in driver's directory, `#include "dbdriver.h"` from `main.c`, and
+execute `init_dbdriver()`.
+
+Function pointers are defined in `lib/db/dbmi_driver/dbstubs.h`
+This header file can be generated with
+`lib/db/dbmi_driver/mk_dbstubs_h.sh` (GRASS GIS 6).
+
+Please read lib/db/README.md and
+
+<https://grass.osgeo.org/programming8/dbmilib.html>
diff --git a/db/drivers/mysql/grass-mesql.html b/db/drivers/mysql/grass-mesql.html
@@ -1,28 +1,7 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
-<head>
-<title>GRASS-MySQL embedded driver - GRASS GIS manual</title>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <link rel="stylesheet" href="grassdocs.css" type="text/css">
- <meta http-equiv="content-language" content="en-us">
- <meta name="viewport" content="width=device-width, initial-scale=1">
-</head>
-<body bgcolor="white">
-
-<img src="grass_logo.png" alt="GRASS logo"><hr align=center size=6 noshade>
-
 <!-- meta page description: MySQL embedded driver -->
-<h1>MySQL embedded driver in GRASS</h1>
-
-<h2>KEYWORDS</h2>
-
-database, attribute table, driver
-
-<h2>DESCRIPTION</h2>
 
-MySQL database driver in GRASS enables GRASS to store vector
-attributes in MySQL embedded database without necessity
-to run MySQL server.
+MySQL database driver enables GRASS to store vector attributes
+in MySQL embedded database without necessity to run MySQL server.
 
 <h2>Driver and database name</h2>
 
@@ -68,14 +47,7 @@ <h2>Troubleshooting: SQL syntax error</h2>
 
 Attempting to use a reserved SQL word as column or table name will result
 in a "SQL syntax" error. The list of reserved words for MySQL can be
-found in the <a href="http://dev.mysql.com/doc/refman/5.7/en/reserved-words.html#table-reserved-words-5.7.4">MySQL manual</a>.
-
-<h2>SEE ALSO</h2>
-
-<em>
-<a href="db.connect.html">db.connect</a>,
-<a href="sql.html">SQL support in GRASS GIS</a>
-</em>
+found in the <a href="https://dev.mysql.com/doc/refman/8.4/en/keywords.html#keywords-in-current-series">MySQL manual</a>.
 
 <h2>AUTHOR</h2>
 
@@ -84,11 +56,11 @@ <h2>AUTHOR</h2>
 <p>
 Credits: Development of the driver was sponsored by
 <a href="https://www.faunalia.it">Faunalia</a> (Italy)
-as part of a project for <a href="http://www.atac.roma.it/">ATAC</a>.
+as part of a project for <a href="https://www.atac.roma.it/">ATAC</a>.
 
+<h2>SEE ALSO</h2>
 
-<hr class="header">
-<p><a href="index.html">Main index</a> - <a href="database.html">Database index</a> - <a href="topics.html">Topics index</a> - <a href="keywords.html">Keywords Index</a> - <a href="full_index.html">Full index</a></p>
-<p>&copy; 2003-2022 <a href="https://grass.osgeo.org">GRASS Development Team</a>, GRASS GIS 8 Reference Manual</p>
-</body>
-</html>
+<em>
+<a href="db.connect.html">db.connect</a>,
+<a href="sql.html">SQL support in GRASS GIS</a>
+</em>
diff --git a/db/drivers/mysql/grass-mysql.html b/db/drivers/mysql/grass-mysql.html
@@ -1,7 +1,7 @@
 <!-- meta page description: MySQL DATABASE DRIVER -->
 
-MySQL database driver enables GRASS to store vector attributes in
-MySQL server.
+MySQL database driver enables GRASS to store vector attributes
+in MySQL server.
 
 <p>
 Because vector attribute tables
@@ -36,30 +36,31 @@ <h2>Driver and database name</h2>
 	     <li> port - server port number
 	 </ul>
 </ul>
+<p>
 Examples of connection parameters:
 <pre>
-  db.connect driver=mysql database=mytest
-  db.connect driver=mysql database='dbname=mytest,host=test.grass.org'
+db.connect driver=mysql database=mytest
+db.connect driver=mysql database='dbname=mytest,host=test.grass.org'
 </pre>
 
 <h2>Data types</h2>
 
 GRASS supports almost all MySQL data types with following limitations:
 <ul>
-    <li> Binary columns (BINARY, VARBINARY, TINYBLOB, MEDIUMBLOB,
-    BLOB, LONGBLOB) are not not supported.
-    If a table with binary column(s) is used in GRASS
-    a warning is printed and only the supported columns are
-    returned in query results.
+<li> Binary columns (BINARY, VARBINARY, TINYBLOB, MEDIUMBLOB,
+BLOB, LONGBLOB) are not not supported.
+If a table with binary column(s) is used in GRASS
+a warning is printed and only the supported columns are
+returned in query results.
 
-    <li> Columns of type SET and ENUM are represented as string (VARCHAR).
+<li> Columns of type SET and ENUM are represented as string (VARCHAR).
 
-    <li> Very large integers in columns of type BIGINT can be lost
-    or corrupted because GRASS does not support 64 bin integeres
-    on most platforms.
+<li> Very large integers in columns of type BIGINT can be lost
+or corrupted because GRASS does not support 64 bin integeres
+on most platforms.
 
-    <li> GRASS does not currently distinguish types TIMESTAMP and
-    DATETIME. Both types are in GRASS interpreted as TIMESTAMP.
+<li> GRASS does not currently distinguish types TIMESTAMP and
+DATETIME. Both types are in GRASS interpreted as TIMESTAMP.
 </ul>
 
 <h2>Indexes</h2>
@@ -104,21 +105,20 @@ <h2>Troubleshooting: SQL syntax error</h2>
 
 Attempting to use a reserved SQL word as column or table name will result
 in a "SQL syntax" error. The list of reserved words for MySQL can be
-found in the <a href="http://dev.mysql.com/doc/refman/5.7/en/reserved-words.html#table-reserved-words-5.7.4">MySQL manual</a>.
+found in the <a href="https://dev.mysql.com/doc/refman/8.4/en/keywords.html#keywords-in-current-series">MySQL manual</a>.
+
+<h2>AUTHOR</h2>
+
+Radim Blazek
+
+<p>
+Credits: Development of the driver was sponsored by
+<a href="https://www.faunalia.it">Faunalia</a> (Italy)
+as part of a project for <a href="https://www.atac.roma.it/">ATAC</a>.
 
 <h2>SEE ALSO</h2>
 
 <em>
 <a href="db.connect.html">db.connect</a>,
 <a href="sql.html">SQL support in GRASS GIS</a>
 </em>
-
-<h2>Credits</h2>
-
-Development of the driver was sponsored by
-<a href="https://www.faunalia.it">Faunalia</a> (Italy)
-as part of a project for <a href="http://www.atac.roma.it/">ATAC</a>.
-
-<h2>AUTHOR</h2>
-
-Radim Blazek
diff --git a/lib/db/README b/lib/db/README
diff --git a/lib/db/README.md b/lib/db/README.md
@@ -0,0 +1,59 @@
+## DBMI library
+
+### Purpose
+
+Database management functions for modules and drivers.
+
+### Authors
+
+Original author:
+
+- Joel Jones (CERL/UIUC) (jjones zorro.cecer.army.mil)
+
+Ref: <https://lists.osgeo.org/pipermail/grass-dev/1995-February/002015.html>
+
+Further authors:
+
+- Radim Blazek (radim.blazek gmail.com)
+- Brad Douglas (rez touchofmadness.com)
+- Glynn Clements (glynn gclements.plus.com)
+- Roberto Flor, Hamish Bowman (hamish_b yahoo.com)
+- Markus Neteler (neteler itc.it)
+- Huidae Cho (grass4u gmail.com)
+- Paul Kelly (paul-grass stjohnspoint.co.uk)
+- Martin Landa (landa.martin gmail.com)
+- Moritz Lennert (mlennert club.worldonline.be)
+- Daniel Calvelo Aros (dca.gis gmail.com)
+- Bernhard Reiter (bernhard intevation.de)
+- Alex Shevlakov (sixote yahoo.com)
+
+### Copyright
+
+(C) 2003-2024 by the GRASS Development Team
+
+### License
+
+This program is free software under the GNU General Public
+License (>=v2). Read the file COPYING that comes with GRASS
+for details.
+
+### Directory contents
+
+- `dbmi/`: DataBase Management Interface (`db_*()` functions)
+  - `dbmi_base/`: contains functions for modules, drivers (`../../db/drivers/`)
+  - `dbmi_client/`: contains functions for modules
+  - `dbmi_driver/`: contains functions for drivers (`../../db/drivers/`)
+- `sqlp/`: SQL parser library
+- `stubs/`: stubs for unimplemented DB functions
+
+The DBMI drivers are stored in
+`../../db/drivers/`
+
+The DBMI user modules are stored in
+`../../db/base/`
+
+NOTE:
+Please read db/drivers/README.md
+
+To generate `dbmi_driver/dbstubs.h` automatically, run `./mk_dbstubs_h.sh` in
+`dbmi_driver/` directory (GRASS GIS 6).
diff --git a/lib/db/sqlp/README b/lib/db/sqlp/README