Man page of tw-admin(1)

tw-admin - Textweiser database administration

tw-admin [db-opt] [opt] -C

tw-admin [db-opt] [opt] -E

tw-admin [db-opt] [opt] -A -c CATEGORY

tw-admin [db-opt] [opt] -D -c CATEGORY

tw-admin [db-opt] [opt] -R -c CATEGORY -n CATEGORY_NEW

tw-admin [db-opt] [opt] -L

tw-admin [db-opt] [opt] -O

tw-admin handles common administration tasks of Textweiser databases.

In particular, tw-admin allows to

o

create/erase Textweiser databases,

o

add/delete/rename/list categories

o

and optimize Textweiser databases.

These options are required in order to establish a connection to the Textweiser database. They can either be given on the commandline and/or be supplied in a configuration file (-f / --config).

NOTE: If Textweiser uses an SQLite database backend, only the -d / --db_name option is required and all other database options are not available.

-d / --db_name database name

Name of the Textweiser database (UTF-8 encoded).

If Textweiser uses an SQLite database backend, database name is the path to the database file, not necessarily UTF-8 encoded.

-s / --host hostname

Hostname of the database server.

-u / --user username

Username to connect to the database.

-w / --passwd password

Password to connect to the database.

NOTE: If no password is given as an argument on the commandline and no password is set in the configuration file, you will be prompted to enter the password. The password will not be echoed during input.

-p / --port port

Port of the database on hostname.

If port is not set, the default port of the database is assumed.

-t / --instance instance

Name of the Microsoft SQL Server instance on hostname.

NOTE: This option is only available if Textweiser uses the Microsoft SQL Server database backend.

-e / --encrypt

Request communication to the database to be encrypted. If no encrypted connection can be established by the database driver, Textweiser will abort.

--trust-cert

Request to trust any certificate presented by the database server, without validation.

NOTE: In order to use self-signed certificates, this option has to be enabled.

NOTE: Passing this option implicitly enables communication encryption.

The database configuration may be given in a configuration file as well. For details, see CONFIGURATION FILE SYNTAX below.

-f / --config path

Path to a Textweiser database configuration file.

-v / --verbose

Enable verbose output.

-V / --version

Show version information and terminate.

-h / --help

Show a short help screen and terminate.

Only one mode can be chosen and executed per invocation.

All modes are selectable by the following capital letter options and their (small letter) suboptions:

-C / --create

Create a new Textweiser database.

-E / --erase

Erase all data from a Textweiser database.

-A / --add-cat

Add a new category to the Textweiser database. If a mono-hierarchical category ("taxonomy") is added, all missing top-level categories will be added automatically.

-c / --cat category name

Set the name of the category to add.

-D / --del-cat

Delete an existing category and all its data from the Textweiser database.

-c / --cat category name

Set the name of the category to delete.

-R / --ren-cat

Rename an existing category within the Textweiser database.

-c / --cat current category name

Set the current name of the category (UTF-8 encoded).

-n / --cat_new new category name

Set the new name of the category, that current category name should be renamed to (UTF-8 encoded).

-L / --list

List all categories known to the Textweiser database.

-O / --optimize

Optimize the Textweiser database. See tw_optimize_db(3) for details.

If an error occurs, the application terminates with an appropriate error code dependent on the operating system in use and prints an error message to stderr.

Textweiser handles mono-hierarchical categories ("taxonomies") in an intuitive manner that allows to use them with ease. Categories and their subcategories are separated using the sequence "::".

 Sports::Football::Managers
 ^^^^^^  ^^^^^^^^  ^^^^^^^^
 top-     sub-     sub-sub- category

Any maintenance steps required are automatically done by Textweiser.

For an in-depth description on how to use mono-hierarchical categories with Textweiser, have a look at the Textweiser User Manual.

The use of mono-hierarchical category structures is optional.

The syntax of Textweiser configuration files follows an easy to use key/value scheme. Empty lines and any leading/trailing whitespace is ignored. Lines starting with the character # are considered comments.

Values may be enclosed within matching single or double quotes and are assigned to keys using the = character.

host

Hostname of the database server.

user

Username for database authentification.

passwd

Password for database authentification.

db_name

Name of the Textweiser database.

port

Port number of the database server.

instance

Name of the Microsoft SQL Server instance.

encrypt

Enable/disable communication encryption.

The following values are recognized:

"yes" or "on"

Enable encryption.

"no" or "off"

Disable encryption.

In order to trust a server's certificate, append the "trust-cert" token to the value, separated by a comma and/or whitespace, i.e.

 encrypt = "yes, trust-cert"

o

All category names have to be encoded in UTF-8 and have to be of 255 bytes in length at most.

o

On Microsoft Windows an option may be started by the "/" character as well.

o

On any Unix-like system the common sequence "--" terminates parsing of options.

o

The character sequence "::" separates hierarchical categories. For in-depth information on how to use hierarchical categories ("taxonomies"), have a look at the Textweiser User Manual.

o

Any configuration file specified (-f / --config) is parsed and evaluated before other commandline arguments are evaluated. As a result, arguments given on the commandline overwrite settings given in a configuration file.

o

Communication encryption is the task of the database driver. Textweiser merely instructs the driver to enable or disable encryption according to the passed options and checks whether the operation did succeed.

For brevity, the following examples assume Textweiser is using the SQLite database backend.

Create a new Textweiser database:

Shell $ tw-admin -d example.sqlt -v -C
 Creating tables in example.sqlt

Add some (hierarchical) categories to the database and list all categories:

Shell $ tw-admin -d example.sqlt -A -c IT::Project
 $ tw-admin -d example.sqlt -A -c IT::Sales
 $ tw-admin -d example.sqlt -A -c Marketing
 $ tw-admin -d example.sqlt -v -L
 Categories in example.sqlt:
 01: IT
 02: IT::Project
 03: IT::Sales
 04: Marketing

Rename an existing category and list all categories again:

Shell $ tw-admin -d example.sqlt -v -R -c IT::Project -n IT::Projects
 Renaming category "IT::Project" to "IT::Projects"
 $ tw-admin -d example.sqlt -v -L
 Categories in example.sqlt:
 01: IT
 02: IT::Projects
 03: IT::Sales
 04: Marketing

Delete an existing category. In this example, the parent category "IT" is removed. As a result, its subcategories "Projects" and "Sales" are removed as well.

Shell $ tw-admin -d example.sqlt -v -D IT
 Deleting category "IT"
 $ tw-admin -d example.sqlt -v -L
 Categories in example.sqlt:
 01: Marketing

tw-learn(1), tw-classify(1), tw-backup(1)

Textweiser User Manual

http://www.lingua-systems.com/text-classifier/textweiser-library/

Copyright (c) 2010-2011 Lingua-Systems Software GmbH