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

…4751) 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 - fix typo: statemets -> statements Extra: - avoid <br> tags within <em> as not converted properly to Markdown
OSGeo · Nov 25, 2024 · ef06e40 · ef06e40
1 parent c594891
commit ef06e40
Show file tree

Hide file tree

Showing 21 changed files with 183 additions and 186 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/db/drivers/postgres/execute.c b/db/drivers/postgres/execute.c
@@ -1,7 +1,7 @@
 /*!
    \file db/driver/postgres/execute.c
 
-   \brief DBMI - Low Level PostgreSQL database driver - execute statemets
+   \brief DBMI - Low Level PostgreSQL database driver - execute statements
 
    This program is free software under the GNU General Public License
    (>=v2). Read the file COPYING that comes with GRASS for details.

diff --git a/db/drivers/sqlite/grass-sqlite.html b/db/drivers/sqlite/grass-sqlite.html
@@ -69,9 +69,13 @@ <h2>SEE ALSO</h2>
   <a href="db.connect.html">db.connect</a>,
   <a href="db.execute.html">db.execute</a>,
   <a href="db.select.html">db.select</a>
-  <br><br>
+</em>
+<br><br>
+<em>
   <a href="sql.html">SQL support in GRASS GIS</a>
-  <br><br>
+</em>
+<br><br>
+<em>
   <a href="https://www.sqlite.org">SQLite web site</a>,
   <a href="https://www.sqlite.org/quickstart.html">SQLite manual</a>,
   <a href="https://www.sqlite.org/cvstrac/wiki?p=ManagementTools">sqlite - Management Tools</a>

diff --git a/doc/vector/TODO b/doc/vector/TODO
@@ -205,7 +205,7 @@ implemented in all drivers.
 SQLite driver
 -------------
 Current implementation is very slow with large updates/inserts. I
-think that it is because all statemets are parsed and it should be
+think that it is because all statements are parsed and it should be
 possible to improve by insert/update cursors (see above).
 
 DBF driver

diff --git a/lib/db/README b/lib/db/README