Installing and using Mandoku

Installing the bundle version of Mandoku

Mandoku for Windows is now distributed as a bundle, which includes all needed software in one archive file. This now is much more complete than the previous versions. Much work has been invested in making the installation procedure more smooth, so as to enable more people to use it.

On other platforms, most of the required files are already installed or can be used as originally distributed; only the Emacs packages needed for the operation, including Mandoku, need to be installed as described below.

Requirements:

  • On all platforms, git and python are required for the installation process and software updates, to run the program of course Emacs is also needed.
  • A working network connection
  • About 400 MB of free space on the system harddisk

Installing a bundle for Windows

(A) The Sinomacs bundle

This is now the preferred version for Windows, since it not only installs the Mandoku package, but the whole Sinomacs customization for Emacs. New users should find it easier to work with this package. As I found some problems with the binary of Emacs 25.1, for the time being the included version is 24.5. This is still very new and might not work as expected. If you encounter problems, please raise an issue on the Github site. You might also try the older Mandoku bundle below.

The installation procedure is simple:

  1. Download the installation bundle sinomacs-bundle-2017-02.zip (200MB).
  2. Double-click on the package and move the folder krp, which is found inside the package to a destination on a root directory of your computer, such as C:, D: and so on as a destination.
  3. Within the folder krp, navigate to the bin folder found there and then click on the file "start-mandoku", which is a batchfile that sets up the environment and then starts Emacs. This file can also be accessed through a shortcut placed on the the Desktop, so you can easily find it next time. To make such a shortcut, right-click on the file "start-mandoku" and select "Send-to", then "Desktop (create shortcut)". You will then be able to use that shortcut to start Emacs (and Mandoku) next time. Alternatively, you can also pin it to the taskbar for convenient access.
  4. When started for the first time, Emacs will install Sinomacs and other packages that are required. It will also try to install a workspace from your GitHub user account. For best results, you should use this workspace and thus have your credentials for GitHub ready. Emacs will ask you for your account name and the password. This will be used to ask the GitHub site to create a "token" for you. This token is stored and used for subsequent access from this machine; you will need the password only once and it will not be stored. The startup process might take a while, but this is only necessary for the first time.

(B) The mandoku bundle

The bundle for Windows has been tested on Windows 8 and 10. It might work on earlier versions, but there might also be problems. Currently there is no 32 bit version of the package. The Emacs application included in the Mandoku package below is version 25.1 from the NTemacs project, this is known to work with the input methods for Chinese and Japanese. The installation procedure is similar to Sinomacs:

  1. The Mandoku bundle includes a version of the git program, which is used to download and update necessary files. If you want to use git outside of Mandoku, it is recommended to download and install the git software from the Git for Windows software repository. The current version known to work is v2.7.2.
  2. Download the Mandoku installation bundle mandoku-2016-12.zip (200MB).
  3. Doubleclick on the package and move the folder krp, which is found inside the package to a destination on a root directory of your computer, such as C:, D: and so on as a destination.
  4. Within the folder krp, navigate to the bin folder found there and then click on the file "start-mandoku", which is a batchfile that sets up the environment and then starts Emacs. This file can also be accessed through a shortcut placed on the the Desktop, so you can easily find it next time. To make such a shortcut, right-click on the file "start-mandoku" and select "Send-to", then "Desktop (create shortcut)". You will then be able to use that shortcut to start Emacs (and Mandoku) next time. Alternatively, you can also pin it to the taskbar for convenient access.
  5. When started for the first time, Emacs will install Mandoku and other packages that are required. It will also try to install a workspace from your GitHub user account. For best results, you should use this workspace and thus have your credentials for GitHub ready. Emacs will ask you for your account name and the password. This will be used to ask the GitHub site to create a "token" for you. This token is stored and used for subsequent access from this machine; you will need the password only once and it will not be stored. The startup process might take a while, but this is only necessary for the first time.

Installing Mandoku on a Macintosh computer

At the moment, there is no package for the Mac. To install, use a recent version of Emacs (the version containing the patch by Yamamoto Mitsuharu of Chiba University, available at GitHub user railwaycat's account, since this version supports the whole range of Unicode).

Once you have Emacs installed, open it and find the "scratch" buffer. This buffer might not be listed on the Buffer menu, but you can always find it in the Buffer list, which is available on the Buffer menu. Once in the scratch buffer, paste the following code there:

(progn
(require 'package)
(add-to-list 'package-archives
             '("melpa" . "http://melpa.org/packages/"))
(package-initialize)
(package-refresh-contents)
(package-install 'mandoku)
(mandoku-show-catalog)
)

Then move the cursor to the very end of the buffer, in a position after the last closing ")" parenthesis and press the keys "C-x" and "C-e" (that is, press the control key and while keeping it pressed, also press the "x" key. Then release both keys, press the control key again, followed by the "e"). This should get things going: Emacs will install Mandoku and other packages that are required.

To start using Mandoku for the first time, you will have to manually ask it to show the catalog. This is done by typing "M-x" (M on the Mac is usually the command key, but in some configurations it could also be the "option" or "alt" key, just try to see which one works on your machine and then keep it pressed and also press "x"). Once you release the keys, you will see a prompt in the bottom most space of the Emacs window, this is called the minibuffer. Now type "mandoku-show-catalog", and then the enter key. This will initialize the mandoku package. This process will make sure that next time the catalog will be loaded right away, so you need to do this only once.

Mandoku will now aks you where you want to put the files related to the use of the Kanseki Repository, that is mostly the texts, but also some other data files, the data you produce while you work with it, etc. The program will suggest "~/krp" for you, which is the "krp" folder in your home directory. You can either accept this by pressing enter, or enter a different path name followed by enter.

Mandoku will also try to install a workspace from your GitHub user account. For best results, you should use this workspace and thus have your credentials for GitHub ready. Emacs will ask you for your account name and the password. This will be used to ask the GitHub site to create a "token" for you. This token is stored and used for subsequent access from this machine; you will need the password only once and it will not be stored. The startup process might take a while, but this is only necessary for the first time. If you do not want to mess around with accounts and passwords right now, you can also skip this step and use Mandoku right away. Using your GitHub credentials will be necessary next when you want to download texts from the Kanseki Repository for local use.

Once all is done, you should see a catalog file. You can now continue below under "Using the preview version".

Installing Mandoku into existing Emacs installations

Mandoku consists of a package with Emacs-lisp code. The code itself is available in the melpa package. If you already have melpa in your list of package repositories, just go there and install the "mandoku" package. Otherwise follow the instructions given for Macintosh users above.

Using Mandoku

At the moment, only a small fraction of the planned functionality has been realized.

After starting Emacs with the Mandoku package installed, Emacs will display the file mandoku-catalog.txt, which is a list of titles available. The file will look a bit different now, as the screenshot is from an earlier version.

In some cases, the catalog file might be obscured by the Emacs splash screen. In such a case, the file can be brought to the front using the buffer menu as shown here:

Emacs splash screen

Another purpose of displaying the catalog list is the fact that this allows the menu for Mandoku to appear. This menu is only available in Mandoku files (Emacs can display a large number of different file types, most of them are accompanied by corresponding menu entries). Mandoku files are recognizable by the string "mandoku-view" in the lower part of the part of the screen that displays this file, in addition to that, they also show the title of the text and some more information about the text and the current location within the text.

Here is the file mandoku-catalog.txt in the upper part and the catalog for the section 佛部 in the lower part:

Mandoku catalog file

The Mandoku menu has the following top level entries:

  • Display
  • Browse
  • Search
  • Maintenance

Of these, we will first look at the "Search" menu, which has the following entries:

  • Texts <f6>
  • Titles <f7>
  • My files

There are three different search actions, that is, within the texts, within the titles of the texts and within the dictionaries. We will look at these in turns, but before that I want to mention that the mysterious "<f6>", "<f7>" and "<f5>" that appear on the menu are the keys that can be used to access this same functionality; usually it is much faster to use the keyboard.

Text search

At the moment, the text search function conducts a full-text search in the index, that has been generated for this purpose and displays the results as a keywoard in context (KWIC) list of matches.

When activating the menu or pressing the key F6, Mandoku will look at the characters immediately following the current position in the text displayed and offer them as default search key at the bottom of the Emacs application window. (This is called the minibuffer and serves a similar purpose dialog boxes have in other applications, that is, they are used for interaction with the user)

Mandoku suggests six characters, but in most cases fewer characters are sufficient as search word. However, at the moment Mandoku will refuse to display more than 2000 hits, so a search for just one or two characters will in many cases go over the limit, which then only displays a breakdown of the number of hits across the different parts of the collection, so it is recommended to use at least 3 characters for searching. If necessary, the suggested characters can of course be completely deleted and the desired search term given.

If there are less than 2000 matches, a list of these matches is displayed. The display is in a very simple table, that gives the location of the match (usually the juan number, page and line), a few characters left and right of the match and the text, where this match is found. The text identification consists of the text number and the title of the text. Both the location and the text title are active links. Clicking on the location will open the text at the place where this passage is found and usually highlight the search term (this will not work always, unfortunately). Clicking on the text title will open the corresponding catalog file and display the entry for this text.

The search result is a text file, similar to the format of the texts themselves. It can be copied, saved and reopened or edited as needed. The order of the displayed items is according to the text following the term, which should put related passages in the vicinity of each other. It is also possible to change the order of the displayed items, but that is an advanced topic that will be dicussed later.

Text files are fetched for display from the remote server and cached locally in a temporary location. At the moment, it is not yet possible to download full texts, access different editions of a text or look at the digital facsimile of a text, but all these are features to be implemented.

Here is a selection of a index display for "修行人", which has 1095 matches in the text corpus:

Emacs index display

Title search

To locate a text and start reading it, title search is most convenient. Title search is activated with F7 or from the menu as shown. Again it will display a prompt at the bottom of the screen and ask for the title to search for.

The result of the search will be displayed in a separate buffer in a table with several columns, displaying the "Bu" (Section), text number, text title, dynasty and author (or otherwise responsible person) for the text. This information is taken from the catalog file, but pre-indexed for faster access. Changes in the catalog file will require a re-indexing.

As usual, the cursor can be moved around to go to the desired row in the file. The original order is by title, but clicking on the top row, where the column names are displayed, will change the sort order according to the column, this allows for example texts from the same dynasty or the same author to be displayed closely together. On the row with the desired text, pressing "t" (text) will display the text, while pressing "i" (information) or "c" (catalog) will go to the catalog entry.

Here is an example of the title display:

Emacs title display

Date: 2016-03-01

Author: Christian Wittern

Created: 2017-02-09 Thu 14:16

Validate