docs: describe how drivers/driver manager relate

Fixes #1651.

docs/mermaid.makefile

@@ -18,6 +18,9 @@
 # Generate Mermaid diagrams statically.  Sphinx has a mermaid
 # extension, but this causes issues with the page shifting during
 # load.
+# First: npm install -g @mermaid-js/mermaid-cli
+# (if you are using Conda, this will not be "global" but rather install to
+# your Conda prefix)
 # Use as: make -f mermaid.makefile -j all
 
 MERMAID := $(shell find source/ -type f -name '*.mmd')
@@ -27,7 +30,10 @@ define LICENSE
 endef
 
 %.mmd.svg : %.mmd
-	mmdc --input $< --output $@
+# XXX: mermaid doesn't properly handle comments in all layouts (the parser is
+# written entirely from scratch each time, it looks like), so strip them
+# manually
+	grep -E -v "^%" $< | mmdc --input - --output $@
 # Prepend the license header
 	mv $@ [email protected]
 	echo "<!--" >> $@

docs/source/_static/css/custom.css

@@ -24,3 +24,14 @@ p.admonition-title {
     display: block;
     margin: 0 auto;
 }
+
+figcaption {
+    font-style: italic;
+    margin: 0 auto;
+    text-wrap: balance;
+    width: 90%;
+}
+
+h1, h2, h3, h4 {
+    text-wrap: balance;
+}

docs/source/faq.rst

@@ -146,6 +146,17 @@ JDBC driver in a bespoke Arrow-based API.
 .. _arrow-jdbc: https://central.sonatype.com/artifact/org.apache.arrow/arrow-jdbc/11.0.0
 .. _Turbodbc: https://turbodbc.readthedocs.io/en/latest/
 
+What is the ADBC driver manager?
+================================
+
+The driver manager (in C/C++) is a library that implements the driver API but
+dynamically loads and manages multiple drivers behind the scenes.  It allows
+applications to link to a single library but use more than one driver at a
+time.  This avoids symbol conflicts between multiple drivers that would
+otherwise all provide the same ADBC APIs under the same names.
+
+For an in-depth look, see :doc:`format/how_manager`.
+
 What is the ADBC SQL dialect?
 =============================
 

docs/source/format/DriverAlias.mmd

@@ -0,0 +1,32 @@
+%% Licensed to the Apache Software Foundation (ASF) under one
+%% or more contributor license agreements.  See the NOTICE file
+%% distributed with this work for additional information
+%% regarding copyright ownership.  The ASF licenses this file
+%% to you under the Apache License, Version 2.0 (the
+%% "License"); you may not use this file except in compliance
+%% with the License.  You may obtain a copy of the License at
+%%
+%%   http://www.apache.org/licenses/LICENSE-2.0
+%%
+%% Unless required by applicable law or agreed to in writing,
+%% software distributed under the License is distributed on an
+%% "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+%% KIND, either express or implied.  See the License for the
+%% specific language governing permissions and limitations
+%% under the License.
+
+block-beta
+    columns 3
+    app["<b>Application</b>"]:3
+
+    space:3
+
+    driver["<b>Driver</b>"]:3
+    AdbcStatementExecuteQuery
+    AdbcStatementSetSqlQuery
+    ...
+    SqliteStatementExecuteQuery
+    SqliteStatementSetSqlQuery
+    ...
+
+    app --> SqliteStatementExecuteQuery

docs/source/format/DriverDirectLink.mmd

@@ -0,0 +1,29 @@
+%% Licensed to the Apache Software Foundation (ASF) under one
+%% or more contributor license agreements.  See the NOTICE file
+%% distributed with this work for additional information
+%% regarding copyright ownership.  The ASF licenses this file
+%% to you under the Apache License, Version 2.0 (the
+%% "License"); you may not use this file except in compliance
+%% with the License.  You may obtain a copy of the License at
+%%
+%%   http://www.apache.org/licenses/LICENSE-2.0
+%%
+%% Unless required by applicable law or agreed to in writing,
+%% software distributed under the License is distributed on an
+%% "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+%% KIND, either express or implied.  See the License for the
+%% specific language governing permissions and limitations
+%% under the License.
+
+block-beta
+    columns 3
+    app["<b>Application</b>"]:3
+
+    space:3
+
+    driver["<b>Driver</b>"]:3
+    AdbcStatementExecuteQuery
+    AdbcStatementSetSqlQuery
+    ...
+
+    app --> AdbcStatementExecuteQuery