From 7eec5bca8898f271d58ed6c556eaaecfc2ad30fb Mon Sep 17 00:00:00 2001
From: Suguru ARAKAWA <arakawa@nautilus-technologies.com>
Date: Wed, 27 Dec 2023 22:09:45 +0900
Subject: [PATCH] docs: revise tgsql README.

---
 README.md                         | 10 ++--
 docs/grammar-rule.md              |  8 +--
 modules/tgsql/{cli => }/README.md | 90 +++++++++++++++++++------------
 3 files changed, 62 insertions(+), 46 deletions(-)
 rename modules/tgsql/{cli => }/README.md (57%)

diff --git a/README.md b/README.md
index a4f2996..b846ae0 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 ## Available Tools
 
-* [tgsql](./modules/tgsql/cli) - Text based SQL client program.
+* [tgsql](./modules/tgsql) - Text based SQL client program.
 * [tgdump](./modules/tgdump) - Table Dump Tool.
 
 ## Requirements
@@ -32,16 +32,12 @@ allprojects { project ->
 ## How to test
 
 ```sh
-./gradle test
+./gradlew test
 ```
 
 ## How to run SQL console CLI
 
-see [modules/tgsql/cli/README.md](modules/tgsql/cli/README.md).
-
-## SQL language
-
-see [docs/grammar-rule.md](docs/grammar-rule.md).
+see [modules/tgsql/README.md](modules/tgsql/README.md).
 
 ## License
 
diff --git a/docs/grammar-rule.md b/docs/grammar-rule.md
index 0393881..c7c47ea 100644
--- a/docs/grammar-rule.md
+++ b/docs/grammar-rule.md
@@ -1,6 +1,6 @@
-# Tsurugi SQL grammar rule
+# Tsurugi SQL console grammar rule
 
-### Notation
+## Notation
 
 * `<symbol>` - a non-terminal symbol or token
 * `"image"` - a token
@@ -12,7 +12,7 @@
 * `<rule> *` - the rule appears zero or more times
 * `<rule> +` - the rule appears one or more times
 
-### Grammar
+## Grammar
 
 ```bnf
 <script> ::= <statement>+
@@ -96,7 +96,7 @@
                        |  EOF
 ```
 
-### Tokens
+## Tokens
 
 ```bnf
 <whitespace> ::= ( " " | "\t" | "\r" | "\n" )
diff --git a/modules/tgsql/cli/README.md b/modules/tgsql/README.md
similarity index 57%
rename from modules/tgsql/cli/README.md
rename to modules/tgsql/README.md
index 8acee6e..f152a31 100644
--- a/modules/tgsql/cli/README.md
+++ b/modules/tgsql/README.md
@@ -1,42 +1,70 @@
-# Tsurugi SQL console CLI
+# Tsurugi SQL console
 
-This module provides a Java program entry for Tsurugi SQL console.
+The Tsurugi SQL console (`tgsql`) is an application designed for executing SQL commands directly on the Tsurugi server. It is available as a command-line tool, providing access to Tsurugi from various operating systems.
 
-* [Main] - Executes SQL script files.
+This tool encompasses three main modes:
 
-[Main]:src/main/java/com/tsurugidb/console/cli/Main.java
+* [SQL console mode](#launch-sql-console)
+  * Execute SQL commands in a REPL environment
+* [SQL statement mode](#execute-a-sql-statement)
+  * Execute a single SQL statement
+* [SQL script file mode](#execute-sql-script-file)
+  * Execute a file containing one or more SQL statements
+
+## Build and Install
+
+Execute the below command in this directory (`/modules/tgsql`):
+
+```sh
+../../gradlew assemble
+```
+
+This will create the following distribution archives:
+
+* `cli/build/distributions/tgsql-<version>.zip`
+* `cli/build/distributions/tgsql-<version>.tar.gz`
+* `cli/build/distributions/tgsql-<version>-shadow.zip`
+* `cli/build/distributions/tgsql-<version>-shadow.tar.gz`
+
+Each of the archives above contains the following contents:
+
+* `tgsql-<version>(-shadow)/bin/tgsql`
+  * A script for executing the command
+  * Additionally, `tgsql.bat` is included for Windows users
+* `tgsql-<version>(-shadow)/lib/*.jar`
+  * Java libraries used by the command
+  * For the -shadow archives, the above is packaged into a single "Uber JAR" file
+
+Deploy the files mentioned above, and the `tgsql` command will be available for use.
 
 ## Execute
 
-### SQL console
+### Launch SQL console
 
 ```sh
-# cd modules/cli
-java -Dorg.slf4j.simpleLogger.defaultLogLevel=debug -jar build/libs/sql-console-*-all.jar -c tcp://localhost:12345
+tgsql -c tcp://localhost:12345
 ```
 
 Please type `\help` to show available commands.
 
-### execute a SQL statement
+### Execute a SQL statement
 
 ```sh
-# cd modules/cli
-java -Dorg.slf4j.simpleLogger.defaultLogLevel=debug -jar build/libs/sql-console-*-all.jar --exec -c tcp://localhost:12345 "select * from test"
+tgsql --exec -c tcp://localhost:12345 "select * from test"
 ```
 
-### execute SQL script file
+### Execute SQL script file
 
 ```sh
-# cd modules/cli
-java -Dorg.slf4j.simpleLogger.defaultLogLevel=debug -jar build/libs/sql-console-*-all.jar --script -c tcp://localhost:12345 -e UTF-8 /path/to/script.sql
+tgsql --script -c tcp://localhost:12345 -e UTF-8 /path/to/script.sql
 ```
 
 ## Program arguments
 
-### common
+### Arguments common to all modes
 
 * `--help, -h` - show help
-* `--connection,-c` - connection url (`tcp://...`, `ipc://...`, etc. compliant with end-point URI of [SessionBuilder.connect](https://github.com/project-tsurugi/tsubakuro/blob/98fa342082af04cf927b875b9d898dd7961f575e/modules/session/src/main/java/com/nautilus_technologies/tsubakuro/low/common/SessionBuilder.java#L35-L45) )
+* `--connection,-c` - connection URL (`tcp://...`, `ipc://...`, etc. compliant with end-point URI of [SessionBuilder.connect](https://github.com/project-tsurugi/tsubakuro/blob/98fa342082af04cf927b875b9d898dd7961f575e/modules/session/src/main/java/com/nautilus_technologies/tsubakuro/low/common/SessionBuilder.java#L35-L45) )
 * `--property,-P` - SQL properties (corresponds to `SET <key> TO <value>` , multiple specifications allowed)
 * client variable
   * `-D` - client variable (corresponds to `\set <key> <value>`, multiple specifications allowed)
@@ -53,8 +81,7 @@ java -Dorg.slf4j.simpleLogger.defaultLogLevel=debug -jar build/libs/sql-console-
   * `--execute` - (`PRIOR`|`EXCLUDING`) (`DEFERRABLE`|`IMMEDIATE`)?
   * `--label` - label
   * `--with` - transaction settings (multiple specifications allowed)
-* credential
-
+* credentials
   * `--user` - user name
     * enter the password via the password prompt after booting.
   * `--auth-token` - authentication token
@@ -66,10 +93,10 @@ java -Dorg.slf4j.simpleLogger.defaultLogLevel=debug -jar build/libs/sql-console-
     3. do not use authentication mechanism. (if an authentication error occurs, proceed to step 4）
     4. display a prompt to enter the username, and use the entered string as the username if it is not empty. (then a password prompt will also be displayed)
 
-### SQL console
+### Arguments for SQL console mode
 
-```txt
-java Main --console <common options> [--auto-commit|--no-auto-commit]
+```sh
+tgsql --console <common options> [--auto-commit|--no-auto-commit]
 ```
 
 * `--auto-commit` - commit each statement
@@ -77,20 +104,20 @@ java Main --console <common options> [--auto-commit|--no-auto-commit]
 
 If a transaction is started implicitly, commit for each statement.
 
-### execute a SQL statement
+### Arguments for SQL statement mode
 
-```txt
-java Main --exec <common options> [--commit|--no-commit] <statement>
+```sh
+tgsql --exec <common options> [--commit|--no-commit] <statement>
 ```
 
 * `<statement>` - statement to execute
 * `--commit` - commit if the statement executes successfully, rollback if it fails (default)
 * `--no-commit` - always rollback regardless of success or failure
 
-### execute SQL script file
+### Arguments for SQL script file mode
 
-```txt
-java Main --script <common options> [[--encoding|-e] <charset-encoding>] [--auto-commit|--no-auto-commit|--commit|--no-commit] </path/to/script.sql>
+```sh
+tgsql --script <common options> [[--encoding|-e] <charset-encoding>] [--auto-commit|--no-auto-commit|--commit|--no-commit] </path/to/script.sql>
 ```
 
 * `</path/to/script.sql>` - script file to execute
@@ -100,13 +127,6 @@ java Main --script <common options> [[--encoding|-e] <charset-encoding>] [--auto
 * `--commit` - commit if the statement executes successfully, rollback if it fails (default)
 * `--no-commit` - always rollback regardless of success or failure
 
+## Grammar rules
 
-
-## How to build
-
-```bash
-cd /path/to/tanzawa/modules/cli/
-../../gradlew shadowJar
-ls build/libs/sql-console-*-all.jar
-```
-
+see [docs/grammar-rule.md](../../docs/grammar-rule.md).