     [file version.texi not included]

BookView: NDTP client written in Tcl/Tk, by Motoyuki Kasahara.

Copyright © 1997, 1998, 1999  Motoyuki Kasahara

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by Free Software Foundation, Inc.

This is edition EDITION, for BookView version VERSION.

What is BookView?
*****************

BookView is a NDTP (Network Dictionary Transfer Protocol) client written in Tcl/Tk. It requires Tcl/Tk 8.3 or later or 8.0jp (`jp' means `Japanized version').

BookView is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

BookView is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

This edition corresponds to version VERSION of BookView.

Invoke BookView
***************

Invoke BookView from a Command Line
===================================

To invoke BookView from a command line on UNIX derived system, type as follows:

     	/usr/local/bin/bookview

(It assumes that BookView has been installed under /usr/local.)

The environment variable BOOKVIEW_LANG determines the language of messages BookView shows. By default, Japanese are chosen. BookView displays English messages by setting the variable to en. Japanese and English messages are currently avaiable.

Summary of Options to wish
==========================

The following command line options are recognized by wish:

-colormap new
     Colormap for main window

-display DISPLAY
     Display to use

-geometry GEOMETRY
     Initial geometry for window

-name NAME
     Name to use for application

-sync
     Use synchronous mode for display server

-visual
     Visual for main window

--
     Pass all remaining arguments through to script

Summary of Options to bookview
==============================

The following command line options are recognized by bookview itself:

-bg COLOR
-background COLOR
     Specify a background color

-fg COLOR
-foreground COLOR
     Specify a foreground color

-fn FONT
-font FONT
     Specify a font

-fk FONT
-kanjifont FONT
     Specify a kanji font

-iconic
     Iconify the window

-title TITLE
     Specify a title of the window

-version
     Output version number, then exit

Setup...
========

Select the Setup... command in the File menu. A setup sub-window will be popped up. There are three server frames in the sub-window, so that you can specify three servers maximum.

In a hostname entry, you can specify a hostname (e.g. localhost) or an address (e.g. 127.0.0.1). ad In a port entry, you can specify a service name (e.g. ndtp) or a port number (e.g. 2010). In the port entries, the service name ndtp are filled by default, but it can be used only when your system recognizes ndtp as the service name. Both on UNIX derived OS and Windows, you can register the service name by editing the system configuration file (see Services). If you cannot or would not like to edit the file, specify port number, instead of ndtp.

Each server entry also has an extra entry options. It is possible to set advanced configuration parameters in those entries. Please keep the default if you aren't experienced at using BookView. Option parameters in a entry must be separated by a semicolon (;). The following options are currently available.

group=GROUP-ID,TITLE,BOOK-ID[,BOOK-ID...]
     That defines book group. Book group is virtual book which consists of one or more real books (listed as BOOK-ID,...). When you command BookView to search a book group, it searches all books in the book group. BookView automatically defines the book group all which is compsite of all books on the server.

     The group name must not contain equal (=), comma (,), at (@), space or tab character.

start=BOOK-ID
start=@GROUP-ID
     The book (BOOK-ID) is selected automatically whenever BookView connects to the server. You can also specify book group-ID preceded with an at (@) character (e.g. @all).

demand-load=BOOK-ID[,BOOK-ID...]
     When the first time you select a certain book, BookView loads bitmap data of all local charactes defined in the book by default. This option disables this behavior. BookView loads bitmap data of a local character in the specified books just before the first time it displyas the character. (Please note that loaded bitmap data are deleted when the connection is closed regardless of this option.)

     You can also specify book group-ID preceded with an at (@) character.

This is a sample of the option parameter list.

     start=super2000/chujiten; demand-load=super2000/kojien,izumi/file1

When setup have been done, click the Ok button in the sub-window. The setup sub-window will be destroyed. The configuration is saved on a file (see Configuration File) and it is automatically loaded at start of BookView, so that you don't have to setup at the next time you invoke BookView.

When you click the Cancel button, the setup sub-window will be destroyed and all modifications in the sub-window will be discarded.

services File
=============

Please edit a system configuration file, if you would like to make your OS recognize the service name ndtp (see Setup). If you cannot or would not like to do it, use port number instead of service name.

On Windows, the configuration file is \WINDOWS\SERVICES. On UNIX derived OS, the file is usualy /etc/services, but if your host runs as NIS client, you have to edit the NIS map on the NIS server, instead. The formats of the files are the same both on Windows and UNIX.

To register the service name ndtp, add the following line to the file, if missing.

     ndtp          tcp/2010

The configuration file on your system may have had the tcp/2010 line with a different service name, like that:

     search        tcp/2010

In this case, please add the service name ndtp as an alias:

     search        tcp/2010        ndtp

(For details, please read the manual for your system.)

Configuration File
==================

When BookView ends or you press the Ok button on the Setup window, the current configuration is recorded to a file. On an UNIX derived system, the configuration file is ~/.bookview. On Windows, the file is C:\\Program Files\\BookView\\setup if you have installed BookView on C:\\Program Files\\BookView. The configuration file is automatically loaded at start of BookView.

On an UNIX derive system, You can also prepare the system common setup file. If your system has some users, this file is convinient because they don't have to setup by themselves.

The common configuration file is /usr/local/etc/bookview.conf. (It assumes that BookView has been installed under /usr/local). The format of the personal configuration file (~/.bookview) and that of common configuration file are the same. To prepare the common setup file, someone invokes BookView, setup BookView with the Setup window, and copy ~/.bookview to /usr/local/etc/bookview.conf.

At loading the configuration file, BookView try to open a personal configuration file and then try a common configuration file. Please note that BookView reads either, not both.

Basic Use of BookView
*********************

This chapter explains basic usage of BookView.

Select Server
=============

Click the Server menu in the menu bar. The servers specified at setup will be listed here. Selcet a server in the list, and then BookView connects to the server.

If you have set the start book ID for the server, BookView selects the server. Otherwise, the book list of the server is displayed.

Select Book
===========

Available books on the current selected server, and book groups (see Setup) are listed in the Book: menu. Please select a book or book group in the list.

Select Search Method
====================

BookView supports the following search methods.

Exact-Word Search
     looks for entires that matches exactly to a given word.

Word Search
     looks for entires whose heads are matched to a given word.

End-Word Search
     looks for entires whose tails are matched to a given word.

Keyword Search
     looks for entries that contains given words.

These method names are also listed the Method: menu. Search is done according with the selected method in this menu. Disabled search method means that the current selected book doesn't support the method. Please note that BookView enables all the methods when the current book is book group. BookView enables all even if no book in the book group doesn't support a certain method.

Search
======

Input a pattern to search in the Word: entry, and then press Return or click the Query button. For keyword search, please list keywords with a separator semicolon (;) between keywords, like this:

     have; to; do

You can specify 5 keywords maximum.

BookView will send a search request to the current server according with the current search method, and receive a response from the server. Candidates matched to the input word will be listed in the first text area (Hits area). Each candidate has (->text) in its tail. Click here and then the corresponding text to the entry will be displayed in the second text area (Text area).

For convinience, special character in the pattern overrides the current search method.

  * When the pattern has one or more semicolons (;), Keyword Search is done.

  * When the pattern begins with an asterisk (*), End-Word Search is done for rest of the pattern.

  * When a pattern ends with an asterisk (*), Word search is done for rest of the pattern.

The Clear button makes the Word: entry be empty.

Menu
====

If the selected book supports Menu search, the menu button in the tool bar and the Menu command in the View menu come to be enabled. Click the button or select the command to enter the Menu search mode.

Copyright Notice
================

If the selected book has copyright notice, the copyright-mark button in the tool bar and the Copyright command in the View menu come to be enabled. Click the button or select the command to view the copyright notice.

Reference
=========

If text in the Text area contain a reference, it is displayed as (->link) with underline and colored blue. Click it, and then referenced text will be displayed.

History Operations
==================

BookView records a history of text displayed in the Text area. The history is listed in the Go menu in the menu bar. Select an item in the list, and then BookView displays the corresponding text in the Text area.

To take a step backward in a history list, click the left-arrow button in the tool bar, select the Previous command in the Go menu, or type Alt+P or Alt+Left. To take a step forward in a history list, click the right-arrow button in the tool bar, select the Next command in the Go menu, or type Alt+N or Alt+Right.

Visit Next or Previous Paragraph
================================

To visit next paragraph of text that BookView displays in its Text Arra, type Alt+J or click the down-arrow button in the bottom of the window, or select the Forward paragraph command in the Go menu.

To visit previous paragraph, type Alt+K or click the up-arrow button in the bottom of the window, or select the Backward paragraph command in the Go menu.

Help
====

Select the Document... or Help (Japanese)... in the Help menu. A sub-window is popped up, and this document will be displayed in it.

Quit
====

Select the Quit command in the File menu or type Alt+Q, then quit.

Advanced Use of BookView
************************

This chapter explains functions for expert users.

Search the Selection
====================

There is the Q Sel button between the Query and Clear buttons. Q Sel is the Query Selection short-cut button; is clears the Word: entry, pastes the selection onto the entry, and then query the word.

Also the Query Selection command in the View menu, and Alt+Return do the same action.

Find Pattern in Text
====================

Find in Text... command in the View menu and the lupe button in the tool bar are equvalend. They are used to search a word in the Text area. Choosing this command, then the sub-window find word in text will be popped up. Type a pattern you want to find in the Find: entry, and then hit Return or click the Find button, then BookView finds the pattern in the Text area.

Book List
=========

Choosing the Book List command in the View menu, BookView shows the book list that the current server provides. When a connection to the server is established, and if you have not set the start book ID for the server, BookView shows this list automatically.

Display or Hide Bitmaps
=======================

Whether BookView displays text with bitmaps or not can be switched by the Display Bitmaps check-button in the View menu. By default, bitmaps are displayed.

Display or Hide Bitmaps
=======================

Whether BookView displays the tool bar or not can be switched by the Display Tool Bar check-button in the View menu.

By default, the tool bar is displayed.

Adjust Text Spacing
===================

The Text Spacing command in the View menu has a cascade menu. The cascade menu has, in tern, five items; 0, 2, 4, 6, 8 pixels. These items are used to determines space between lines in the Text area. The default value is 0 pixel.

Keyboard Operation
******************

You can invoke all functions of BookView by keyboard. This chapter explains how to operate BookView with keyboard.

Focus Operations
================

The following key operations move the focus on a widget. These operations are sensed anywhere on the BookView main window.

Alt+F
     Pull the File menu down and grab it.

Alt+V
     Pull the View menu down and grab it.

Alt+S
     Pull the Server menu down and grab it.

Alt+G
     Pull the Go menu down and grab it.

Alt+H
     Pull the Help menu down and grab it.

Alt+B
     Pull the Book: menu down and grab it.

Alt+M
     Pull the Method: menu down and grab it.

Alt+W
     Focus on the Word: Entry.

Tab
     Move the focus to the Word entry, Hits area, and Text area, in that order.

Operations In Menu
==================

In a grabbed menu, you can do the following operations.

Up
Control+P
     Move the highlight entry up.

Down
Control+N
     Move the highlight entry down.

Return
     Select the highlight entry.

Esc
     Abort a menu selection.

Some other operations are defined by Tk itself. See the manual page of menu(n) for more details.

Operations In Word Entry
========================

In the Word: entry, the following keyboard operations are sensed.

Left
Control+B
     Move the cursor backward by a character.

Right
Control+F
     Move the cursor forward by a character.

Home
Control+A
     Move the cursor to the beginning of the entry.

End
Control+E
     Move the cursor to the end of the entry.

Backspace
Control+H
     Delete a character to the left of the cursor.

Delete
Control+D
     Delete a character to the right of the cursor.

Control+K
     Delete all characters to the right of the cursor.

Some other operations are defined by Tk itself. See the manual page of entry(n) for more details.

Operations In Hits Area
=======================

In the Hits area, the following keyboard operations are sensed.

Up
Control+P
     Move the cursor one line down.

Down
Control+N
     Move the cursor one line up.

Prior (Page Up)
Alt+V
     Move the cursor backward by one page.

Next (Page Down)
Control+V
     Move the cursor forward by one page.

Return
     Choose the hit entry at the inesrtion cursor. Text of the hit entry is displayed at the Text area.

Some other operations are defined by Tk itself. See the manual page of text(n) for more details.

Operations In Text Area
=======================

In the Text area, the following keyboard operations are sensed.

Left
Control+B
     Move the cursor backward by a character.

Right
Control+F
     Move the cursor forward by a character.

Down
Control+N
     Move the cursor one line up.

Up
Control+P
     Move the cursor one line down.

Prior (Page Up)
Alt+V
     Move the cursor backward by one page.

Next (Page Down)
Control+V
     Move the cursor forward by one page.

space
     Move the cursor to the next anchor ((->link)) in the text.

BackSpace
     Move the cursor to the previous anchor ((->link)) in the text.

Return
     If the cursor is on the anchor, jump to the reference.

Some other operations are defined by Tk itself. See the manual page of text(n) for more details.

Miscellaneous Operations
========================

These operations are sensed anywhere on the BookView main window.

Alt+Q
     Quit. This key operation is equivalent to the Quit command in the File menu.

Alt+Return
     Query selection. This key operation is equivalent to the Query Selection command in the View menu.

Alt+Left
Alt+P
     Take a step backward in a history list. This key operation is equivalent to the Previous command in the Go menu.

Alt+Right
Alt+N
     Take a step forward in a history list. This key operation is equivalent to the Next command in the Go menu.

Alt+/
     Pop up the Find in Text sub-window, and grab it. This key operation is equivalent to the Find in Text... command in the View menu.

Frequently Asked Questions
**************************

Question 1 (Input Japanese character)
=====================================

Question
     How do I input Japanese character on BookView window?

Answer
     Use Kinput2, or an input frondend that supports XIM.

Question 2 (I cannot input Japanese character)
==============================================

Question
     I'm running kinput2, but I cannot input Japanese character on the BookView window.

Answer
     Which protocol is used between Tk8.0jp interpreter and kinput2, kinput or XIM?  Can your kinput2 accept the protocol?

     Unless the environment variable TK_KCPROTO is defined, the protocol is chosen by the follwoing rule. If you set the environment variable XMODIFIERS, and its value is not empty, Tk8.0jp interpreter try to talk to kinput2 with the XIM protocol. Otherwise, kinput is used.

     Please note that XIM is chosen even when XMODIFIERS is set to @im=none, intended to use the kinput protocol. In this case, please unset XMODIFIERS, or set TK_KCPROTO to kinput.

     To set the TK_KCPROTO, please do:

          (C compatible shell such as csh and tcsh)
          % setenv TK_KCPROTO kinput

          (Bourne-compatible shell such as sh, ksh, bash and zsh)
          $ export TK_KCPROTO; TK_KCPROTO=kinput

Question 3 (customize kinput2 start key)
========================================

Question
     How do I customize kinput2 start key on BookView window?

Answer
     Please set the X resource, like this:

          bookview*tkKinputStartKeys: <Shift-space> <Control-backslash>