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

   Copyright (C) 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 3.2, for BookView version 3.2.

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 3.2 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>