sanzang 0.0.3 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ee6e8f6e1b7cbd116de22589a0089faa73b35726
+  data.tar.gz: 2110931d7a863e52dc6ade5b17c060d4dc9ab12e
+SHA512:
+  metadata.gz: 65710d20a08d6b20f82d3c909468c8e5d03b54fd5f96657247d0eaededc587d1394c66183660e50c654990f0bccfcb1efc600af5672e518cbaa777cd9a5ba3f8
+  data.tar.gz: 039837a397ed9f5561d5f2c6af23fe4a8991b305d134a7f4cfe6be3f67bad0506bf1ca6d8bf332586f51243a8bfbd1acb8302beb60b107e4ca165b56f66550ea

data/HACKING

@@ -1,54 +1,36 @@
-= Hacking Sanzang
+= Hacking \Sanzang
 
-== Testing and building
-
-* Use "rake test" to run all tests.
-* Use "rake build" to create a gem package in the "dist" directory.
-
-== Platforms
+== Supported platforms
 
 These programs should work on all platforms with Ruby 1.9 or later. Regular
-testing takes place on GNU/Linux operating systems.
+testing takes place on GNU/Linux operating systems. \Sanzang has not been fully
+tested on other implementations of Ruby (e.g. JRuby, Rubinius, etc.).
 
-== Languages
+== Languages and scope
 
 The translation program may not be very useful for all languages. It was
 designed specifically for dealing with the more difficult aspects of
 translating from ancient Chinese. For a language like Sanskrit or Tibetan, it
-may not be so useful. However, the limitations of this program have not yet
-been investigated.
-
-== Tables
-
-A valid translation table is necessary when using the translator. More
-information on this format is available in the README file. The following
-tokens are reserved: "~|", "|", and "|~", and these should not be used in table
-record data. No "escape sequences" are available for the inclusion of such
-tokens as data.
+may not be so useful.
 
-== Multiprocessing
+== Multiprocessing and fork(2)
 
 Most every Unix-like system supports the fork(2) system call and therefore has
-the potential to run Sanzang in a multiprocessing mode for batches. However,
-each Ruby implementation and port may be different, and Sanzang will check to
-see if the fork method has been implemented before attempting to use the
-"parallel" gem for multiprocessing.
-
-Batch mode will print a warning message if it cannot use the "parallel" gem.
-It will then process the batch, but will not utilize multiprocessing, so it
-will run slower. The "mingw" and "mswin" ports of Ruby do not have support for
-fork method, yet the "parallel" library attempts to fork anyhow. To avoid
-potential errors, the translator will not even attempt to use multiprocessing
-on platforms in which the fork method is not implemented.
-
-Note that for Windows, the "cygwin" port of Ruby does implement does support
-fork(2) perfectly, so Ruby 1.9+ on Cygwin can utilize the fork method and so
+the potential to run \Sanzang in a multiprocessing mode for batches. However,
+each Ruby implementation and port may be different, and \Sanzang will check to
+see if the fork method has been implemented before attempting to utilize
+multiprocessing. To avoid potential errors, the translator will not attempt to
+use multiprocessing on platforms in which fork(2) is not implemented.
+
+Note that for Windows, the Cygwin port of Ruby does implement does support
+fork(2) perfectly, so Ruby 1.9+ on Cygwin can utilize the fork method, so
 it supports standard multiprocessing. Therefore, Cygwin is the most robust
-environment for running Sanzang on a Windows PC.
+environment for running \Sanzang on a computer with Windows.
 
-== Encodings
+== Text encoding quirks
 
-Converters for several encodings have not yet been implemented by MRI Ruby.
-Most of these are obscure and not widely used anyways. Perhaps the most
-notable is EUC-TW, which is an old Unix encoding for traditional Chinese.
-However, even this most "notable" missing encoding is obscure and unimportant.
+Converters for several encodings have not yet been implemented by YARV. Most of
+these are obscure and not widely used. Perhaps the most notable is EUC-TW,
+which is an old Unix encoding for traditional Chinese. Encoding conversion is
+used by the _reflow_ command for formatting CJK text, but encoding conversion
+is not required for translation.

data/MANUAL

@@ -0,0 +1,312 @@
+= The \Sanzang Manual
+
+== Introduction
+
+\Sanzang is a compact, cross-platform machine translation system. This program
+was developed specifically to fill the need for a competent application for
+aiding translators of the Chinese Buddhist canon into other languages. However,
+the translation method it uses is general enough that it may extend to other
+translation domains as well, especially translations with CJK source languages
+(Chinese, Japanese, and Korean). The name \Sanzang (三藏) is a literal
+translation of the Sanskrit word “Tripitaka,” which is a general term for the
+Buddhist canon.
+
+\Sanzang is implemented as a Unix style "command suite" program that executes
+in your operating system's command shell. The _sanzang_ command includes
+subcommands for carrying out each of the available functions of the system.
+
+\Sanzang is programmed in the Ruby programming language and is free software
+("free as in freedom"). This program is licensed under the GNU General Public
+License, version 3, which ensures that anyone can use the program for any
+purpose, and that extensions to this program will remain freely available to
+others.
+
+== Background
+
+At the time of this writing, nearly all machine translation systems available
+are based on statistical machine translation (SMT), a method which has not
+proven very useful for ancient Chinese texts. \Sanzang was developed as an
+alternative simply because there was the practical need for a better and more
+reliable tool.
+
+The most significant difference between \Sanzang and other machine translation
+systems is that it does not attempt to interpret or translate grammar. Instead,
+it simply translates names, terms, and phrases based on rules stored in a
+translation table. The \Sanzang translator applies this translation table at
+runtime to generate a text listing as the output.
+
+This method is simple and efficient, and produces predictable results that can
+be made immediately available to the user for verification. To facilitate this
+task, all translation listings generated by the program are collated
+line-by-line with the original source text.
+
+== Translation Method
+
+\Sanzang provides mainly a simple machine translation engine. To use this
+translation engine, it will also be necessary to have a text file in which all
+translation rules are defined. This is called a translation table, and its
+format is simple delimited text. At runtime, the translation rules in this file
+are applied to the source text to generate the translation listing.
+
+In a translation table text file, each line is a translation rule containing a
+source term and its equivalent meanings in other languages. Each line starts
+with "~|", has records delimited by "|", and ends with "|~". In the translation
+table, the first column represents the source language, while the subsequent
+columns represent destination languages. In this example, we want to create a
+table capable of rendering the following title into English:
+
+    金剛般若波羅蜜經
+
+We start by creating a new text file, named _table.txt_, or something similar.
+In this text file, we may add the following rules:
+
+    ~|波羅蜜| pāramitā|~
+    ~|金剛| diamond|~
+    ~|般若| prajñā|~
+    ~|經| sūtra/classic|~
+
+Notice that spaces were included prior to the English equivalents. This is
+because Chinese does not typically include spaces between words, so we need to
+insert our own leading spaces as part of the translation rules we are defining.
+After we have written this table file, we can then run the \Sanzang translation
+engine with our table. When it reads the Chinese title as the input text, it
+then produces the following translation listing:
+
+    1.1 金剛般若波羅蜜經
+    1.2  diamond prajñā pāramitā sūtra/classic
+
+The program first sorted our terms by the length of the source column, and
+then applied each of these rules in sequence. It then collated the output and
+created a translation listing. In the left margin, we can see numbers denoting
+the line number of the source text, along with the column number of the
+translation table.
+
+As a final example, below is a snippet from an Indian Buddhist meditation text,
+which was processed by the \Sanzang translation engine in the same manner:
+
+    105.1 阿難白佛言。
+    105.2  ānán bái-fó-yán ¶
+    105.3  ānanda addressed-the-buddha-saying ¶
+
+    106.1 唯然世尊。
+    106.2  wéi-rán shìzūn ¶
+    106.3  just-so bhagavān ¶
+
+    107.1 願樂欲聞。
+    107.2  yuànlè-yù-wén ¶
+    107.3  joyfully-wish-to-hear ¶
+
+Here we can see a three-column translation table at work. The first column has
+the traditional Chinese source text, the second column contains the Pinyin
+transliteration, and the third column contains English. In this example we can
+see that well-defined translation rules lead to a clear translation listing,
+in which the meaning of the original text is readily understandable in English.
+
+Considering the examples above, we can see that knowledge of the source
+language and expertise in the relevant literary field is often still necessary.
+Here again we can see that this translation system does not position itself as
+a “silver bullet” for creating finished translations, but is rather a practical
+tool for the purpose of assisting human readers and translators.
+
+== Installation
+
+=== Requirements
+
+The standard way of installing \Sanzang is as a Ruby gem. To do this, the only
+requirement is Ruby 1.9 or later, along with an Internet connection.
+
+If you do not have an Internet connection available on the host computer, then
+you may download the gem file and install it manually. If you choose this
+route, then please be aware that the “sanzang” gem depends on the “parallel”
+gem for multiprocessing.
+
+For users of Microsoft Windows, please be aware that Windows ports of Ruby
+typically do not include full multiprocessing support using the standard Unix
+system calls. If you will be using \Sanzang in a Windows environment and you
+require support for fast batch processing, then you should use the Cygwin port
+of Ruby, which does not have this limitation. Unix-based platforms such as
+Linux, BSD, and Mac OS X are unaffected by this issue.
+
+In addition to installation requirements, it may also be very useful to have a
+text editor that is aware of Unicode and other encodings, and able to display
+multilingual texts. One such application that is known to work well for this
+task is the _gedit_ text editor, which is free software and is available on a
+variety of platforms.
+
+=== Installation
+
+To install \Sanzang, the following command should suffice.
+
+    # gem install sanzang
+
+This command will download and install \Sanzang into your Ruby environment.
+
+If you have installed Ruby 1.9 but cannot run the _gem_ command, then you may
+need to set up your PATH environment variable first, so you can run _ruby_ and
+_gem_ from the command line.
+
+== Commands
+
+\Sanzang functions are accessible through the _sanzang_ command and its
+subcommands. Runtime behavior is set through command line options and
+parameters. This allows _sanzang_ to be easily scripted and automated.
+
+\Sanzang subcommands can also be abbreviated for the sake of convenience. For
+example, the "translate" subcommand could be abbreviated as "trans", "tr", or
+even the one letter "t".
+
+=== _sanzang_
+
+The main _sanzang_ program acts as a front-end to subcommands, and also
+includes options for printing platform and version information.
+
+    Usage: sanzang [options]
+    Usage: sanzang <command> [options] [args]
+
+    Sanzang commands:
+        batch       translate many files in parallel
+        reflow      format CJK text for translation
+        translate   standard single text translation
+
+    Options:
+        -h, --help                       show this help message and exit
+        -P, --platform                   show platform information and exit
+        -V, --version                    show version number and exit
+
+=== _sanzang_ _batch_
+
+The _sanzang_ _batch_ command can translates files in parallel. A list of files
+is read from STDIN, while progress information is printed to STDERR. The list
+of output files written is printed to STDOUT at the end of the batch. The
+output directory is specified as a parameter.
+
+    Usage: sanzang batch [options] table output_dir < queue
+
+    Options:
+        -h, --help                       show this help message and exit
+        -E, --encoding=ENC               set data encoding to ENC
+        -L, --list-encodings             list possible encodings
+        -j, --jobs=N                     allow N concurrent processes
+
+=== _sanzang_ _reflow_
+
+The command _sanzang_ _reflow_ can reformat Chinese, Japanese, or Korean text,
+in which terms are often split between lines. This formatter "reflows" the text
+based on its punctuation and horizontal spacing, separating the source text
+into lines that are much safer for translation.
+
+    Usage: sanzang reflow [options]
+
+    Options:
+        -h, --help                       show this help message and exit
+        -E, --encoding=ENC               set data encoding to ENC
+        -L, --list-encodings             list possible encodings
+        -i, --infile=FILE                read input text from FILE
+        -o, --outfile=FILE               write output text to FILE
+
+=== _sanzang_ _translate_
+
+The command _sanzang_ _translate_ can perform translation of a single text
+stream or file. By default, this command reads from STDIN and writes to STDOUT.
+For concurrent translation of multiple files, see the _batch_ command.
+
+    Usage: sanzang translate [options] table
+
+    Options:
+        -h, --help                       show this help message and exit
+        -E, --encoding=ENC               set data encoding to ENC
+        -L, --list-encodings             list possible encodings
+        -i, --infile=FILE                read input text from FILE
+        -o, --outfile=FILE               write output text to FILE
+
+== Basic Usage
+
+In the following example, we are working with a small text that we want to
+translate. With the first command, we reformat the text using _reflow_.
+Then we run _translate_ with our translation table, to generate a translation
+listing.
+
+    $ sanzang reflow -i xinjing.txt -o lines.txt
+    $ sanzang translate -i lines.txt -o trans.txt TABLE.txt
+
+The next two commands illustrate how these programs use standard input and
+output streams by default, how they can easily operate as text filters, and
+the way that _sanzang_ subcommands can be abbreviated.
+
+    $ sanzang r < xinjing.txt | sanzang t TABLE.txt > trans.txt
+    $ cat xinjing.txt | sanzang r | sanzang t TABLE.txt | less
+
+== Advanced Usage
+
+=== Batch Mode
+
+We may have thousands of texts that we want to generate translation listings
+for with our translation table. For example, if our translation table was
+updated recently, we may want to regenerate an entire corpus of translation
+listings. To do this, we can use the _find_ command to retrieve the file paths
+to our text files, and then pipe that output into _sanzang_ _batch_.
+
+    $ find /srv/texts -type f | sanzang batch TABLE.txt /srv/trans
+
+This command will find all files in the location specified, and then feed the
+file paths to _sanzang_ _batch_, which will process them as a batch. If
+multiprocessing is supported on your platform, then the batch will be divided
+among all available processors.
+
+To determine whether multiprocessing is available in your version of Ruby, you
+can run the _sanzang_ command with the "-P" option:
+
+    $ sanzang -P
+
+If you see that "Fork implemented" is "true", then your platform supports Unix
+style multiprocessing, and you can gain performance benefits from using the
+_batch_ command. You should also examine the value for "Processors found".
+This is the number of logical processors detected on your platform.
+
+If you see that only one processor is detected and you know that there are more
+available on your platform, then you may want to use the "-j" flag when running
+the batch command, to manually specify the number of processes to use. This
+number can be set to the number of CPU cores available on your system. This
+option may be necessary on some less common platforms, such as some BSD
+distributions and commercial Unix variants.
+
+Microsoft Windows ports of Ruby typically do not support Unix style
+multiprocessing. If you require higher performance and utilizing multiple CPU
+cores, then you should look into the Cygwin port of Ruby, which does not have
+this limitation.
+
+The performance benefits of running in batch mode with multiprocessing may be
+very significant. The performance increases are typically proportional to the
+number of CPU cores available on the system. For example, on a large SMP system
+with 50 processors available, _sanzang_ _batch_ can run up to 50x as fast.
+
+=== Text Encodings
+
+\Sanzang supports many possible text encodings. Option "-L" will list all
+available text encodings. Option "-E" will set the encoding to be used for all
+text data such as input texts, output texts, and table files. The other program
+I/O, such as messages for the terminal, will still be in the default encoding
+of the environment. For example, in a Windows environment that by default uses
+the IBM-437 encoding, specifying "-E" with a value of "UTF-16LE" will cause
+\Sanzang to read and write all text data in UTF-16LE, but all other program
+messages will still be displayed in the console's native IBM-437 encoding.
+
+    $ sanzang t -E UTF-16LE -i in.txt -o out.txt TABLE.txt
+
+If the "-E" option is not specified, then \Sanzang will use the default
+encoding inherited from the environment. For example, a GNU/Linux user running
+\Sanzang in a UTF-8 terminal will by default have all text data read and
+written to in the UTF-8 encoding. The one *exception* to this is for
+environments using the IBM-437 encoding (typically an old Windows command
+shell). In this case, \Sanzang will take pity on you and automatically switch
+to UTF-8 by default, as if you had specified the option "-E" with value
+"UTF-8".
+
+== Responsible Use
+
+With comprehensive translation tables, \Sanzang can often be quite accurate
+and effective. However, this program is still comparable to a simple machine,
+and it can never replace a human translator. Please understand the scope of
+this translation system when using it. No machines can take responsibility for
+a poor translation. In the end, it is you who are responsible for any and all
+publications.

data/README

@@ -1,280 +1,50 @@
-= Sanzang (三藏)
-
-== Contents
-
-* Introduction
-* Concepts
-* Installation
-* Components
-* Basic Usage
-* Advanced Usage
-* Responsible Use
+= \Sanzang (三藏)
 
 == Introduction
 
-Sanzang is a compact, cross-platform machine translation system. This program
-was developed specifically to fill the need for a competent application for
-aiding translators of the Chinese Buddhist canon into other languages. However,
-the translation method it uses is general enough that it may extend to other
-translation domains as well, especially those in which Chinese is the source
-language. Sanzang (三藏) is a literal translation of the Sanskrit word
-"Tripitaka," a general term for the Buddhist canon. Sanzang is alternately
-a translation of "trepitaka," the title for someone who is a master of such
-teachings.
-
-Sanzang is implemented as a small set of programs written in the Ruby
-programming language. This system is free software (“free as in freedom”), and
-it is licensed under the GNU General Public License, version 3. This ensures
-that anyone can use the program for any purpose, and that any extensions to
-Sanzang will remain freely available to others.
-
-== Background
-
-The most significant difference between Sanzang and other machine translation
-systems is that it does not attempt to interpret grammar in any way. Instead,
-it relies on direct translation of names, terms, and phrases based on a large
-translation table. The Sanzang translator simply applies this translation table
-at runtime, and does not attempt to interpret grammar or syntax in any way
-whatsoever. The end result is that the accuracy of the translation is highly
-dependent on the accuracy of the translation table.
-
-The strength of the Sanzang method is that it is extremely simple and easy to
-work with, and eliminates virtually all complexity in the translation process.
-This system will never produce incorrect syntax because it does not interpret
-syntax in the first place. This method is also efficient and yields predictable
-results that can be made immediately available to the user for verification. To
-facilitate this task, all translation listings are collated line-by-line with
-the original source text.
-
-== Concepts
-
-Sanzang provides mainly a simple translation engine. For any actual
-translation work, Sanzang requires a translation table in which all
-translation rules are defined. This translation table is stored in a simple
-text file. Each line is a record containing a source term and its equivalent
-meanings in other languages. Each line starts with "~|", has records delimited
-by "|", and ends with "|~". In a table, the first column represents the source
-language, while the subsequent columns represent destination languages. In
-this example, we want to create a table capable of rendering the following
-title into English:
-
-    金剛般若波羅蜜經
-
-We start by creating a new text file, named TABLE.txt or something similar. In
-this text file, we may add the following rules:
-
-    ~|波羅蜜| pāramitā|~
-    ~|金剛| diamond|~
-    ~|般若| prajñā|~
-    ~|經| sūtra|~
-
-Did you notice that we included spaces prior to the translations of these
-terms? This is because Chinese does not typically include spaces between
-words, so we need to insert our own leading spaces as part of the rules we are
-defining. After we have written this table file, we can run the Sanzang
-translator with our table. When it reads the Chinese title as the input text,
-it then produces the following translation listing:
-
-    1.1 金剛般若波羅蜜經
-    1.2  diamond prajñā pāramitā sūtra
+\Sanzang is a compact and simple cross-platform machine translation system.
+This program is especially useful for translating from CJK languages (Chinese,
+Korean, and Japanese), and it is very suitable for ancient and otherwise
+difficult texts. Due to its origins in translating texts from the Chinese
+Buddhist canon, the program is called \Sanzang (三藏), a literal translation of
+the Sanskrit word "Tripitaka," which is a general term for the Buddhist canon.
+As demonstrated by the _sanzang_ program itself:
 
-The program first sorted our terms by the length of the source column, and
-then applied each of these rules in sequence. It then collated the output and
-created a translation listing. In the left margin, we can see numbers denoting
-the line number of the source text, along with the column number of the
-translation table.
+    $ echo '三藏' | sanzang t sztab
+    [1.1] 三藏
+    [1.2]  sānzàng
+    [1.3]  tripiṭaka
 
-As a final example, below is a snippet from an ancient meditation text, which
-was also processed by the Sanzang translator in the same manner:
+Anyone can learn how to use \Sanzang, and use it to read and analyze texts.
+Unlike most other systems, \Sanzang is small and approachable. Any user can
+develop his or her own translation rules, and these are simply stored in a text
+file that the program can read. For full details, refer to the MANUAL.
 
-    105.1 阿難白佛言。
-    105.2  ānán bái-fó-yán ¶
-    105.3  ānanda addressed-the-buddha-saying ¶
+\Sanzang is free software ("free as in freedom"), and it is released under the
+GNU General Public License, version 3.
 
-    106.1 唯然世尊。
-    106.2  wéi-rán shìzūn ¶
-    106.3  just-so bhagavān ¶
+== Quick Install
 
-    107.1 願樂欲聞。
-    107.2  yuànlè-yù-wén ¶
-    107.3  joyfully-wish-to-hear ¶
-
-Here we can see a three-column translation table at work. The first column has
-the traditional Chinese source text, the second column contains the Pinyin
-transliteration, and the third column contains English. In this example we can
-see that well-defined translation rules lead to a clear translation listing,
-at which the meaning of the original text is readily understandable in
-English. If we wished to add additional columns for simplified Chinese,
-Vietnamese, Japanese, Spanish, French, German, Russian, or any other languages,
-then these could all be handled similarly without any technical difficulties.
-
-Comprehensive translation tables could be quite large, containing tens of
-thousands of entries. However, the work of building such a table is not so
-significant compared to the long-term benefits which may be gained from such
-tables. In addition, rules in these translation tables may be translated into
-other languages as well. There is a potential here to assist readers all over
-the world with understanding otherwise difficult works.
-
-Considering the examples above, we can see that knowledge of the source
-language and expertise in the relevant literary field is often still necessary.
-Here again we can see that this translation system does not position itself as
-a “silver bullet” for creating finished translations, but is rather a practical
-set of utilities for the purpose of assisting human readers and translators.
-
-== Installation
-
-=== Requirements
-
-The Sanzang system can be installed either as a Ruby gem, or manually from
-an archive file. The only prerequisite to using Sanzang is:
-
-* Ruby 1.9 or later
-
-The "parallel" gem is required by Sanzang, but is installed automatically when
-installing Sanzang using the standard method. Using the "parallel" gem, Sanzang
-can support multiprocessing in batch mode (if the platform supports it).
-Currently this method of multiprocessing will work automatically on Ruby ports
-that implement the Process#fork system call.
-
-In addition to the actual runtime requirements, it may also be very useful to
-have a text editor that is aware of Unicode and other encodings, and able to
-display multilingual texts. One such application that is known to work well
-for this task is the _gedit_ text editor, which is free software and also
-available on a variety of platforms.
-
-=== Installation
-
-To install Sanzang, the following command should suffice.
+To install \Sanzang, the prerequisite is Ruby 1.9 or later. After Ruby has been
+installed, you can run the _gem_ command from a command shell to automatically
+download and install \Sanzang onto your computer.
 
     # gem install sanzang
 
-If you have installed Ruby 1.9 but cannot run the "gem" command, then you may
-need to set up your PATH environment variable first, so you can run _ruby_ and
-_gem_ from the command line.
-
-== Components
-
-The programs in Sanzang are designed in a traditional Unix style in which
-programs are executed in a terminal, and program settings are specified
-through command line options and parameters. This allows Sanzang programs
-to be easily scripted and automated.
-
-=== sanzang-reflow
-
-The program sanzang-reflow can reformat Chinese, Japanese, or Korean text, in
-which terms are often split between lines. This formatter "reflows" the text
-instead based on its punctuation and horizontal spacing, separating the source
-text into lines that are much safer for translation using the sanzang-translate
-program.
-
-    Usage: sanzang-reflow [options]
-
-    Options:
-        -h, --help                       show this help message and exit
-        -E, --encoding=ENC               set data encoding to ENC
-        -L, --list-encodings             list possible encodings
-        -i, --infile=FILE                read input text from FILE
-        -o, --outfile=FILE               write output text to FILE
-        -V, --version                    show version number and exit
-
-=== sanzang-translate
-
-The program sanzang-translate (1) reads a translation table file, (2) applies
-this table's rules to an input text, and then (3) generates a translation
-listing. This program can also run in a special batch mode that can utilize
-multiprocessing (multiple processors and processor cores) for high
-performance.
-
-    Usage: sanzang-translate [options] table
-    Usage: sanzang-translate -B output_dir table < file_list
-
-    Options:
-        -h, --help                       show this help message and exit
-        -B, --batch-dir=DIR              process from a queue into DIR
-        -E, --encoding=ENC               set data encoding to ENC
-        -L, --list-encodings             list possible encodings
-        -i, --infile=FILE                read input text from FILE
-        -o, --outfile=FILE               write output text to FILE
-        -P, --platform                   show platform information
-        -V, --version                    show version number and exit
-
-== Basic Usage
-
-=== Formatting and translating a single text
-
-In the following example, we are working with a small text that we want to
-translate. With the first command, we reformat the text using sanzang-reflow.
-Then we run the sanzang-translate program with our translation table, to
-generate a translation listing.
-
-    $ sanzang-reflow -i xinjing.txt -o lines.txt
-    $ sanzang-translate -i lines.txt -o trans.txt TABLE.txt
-
-=== Redirecting I/O
-
-The next two commands illustrate how these programs use standard input and
-output streams by default, and how they can easily operate as text filters.
-
-    $ sanzang-reflow -i xinjing.txt | sanzang-translate -o trans.txt TABLE.txt
-    $ cat xinjing.txt | sanzang-reflow | sanzang-translate TABLE.txt | less
-
-== Advanced Usage
-
-=== Batch Mode and Multiprocessing
-
-In the following example, we may have several thousand texts that we want to
-run through sanzang-translate with our translation table. For example, if our
-translation table was updated recently, we may want to regenerate our corpus
-of translation listings. To do this, we can use the "find" command to retrieve
-the file paths to our text files, and then pipe that output into the Sanzang
-translation program.
-
-    $ find /srv/texts -type f | sanzang-translate -B /srv/trans TABLE.txt
-
-This command will find all files in the location specified, and then feed the
-file paths to sanzang-translate, which will process them as a batch. If the
-"parallel" gem is available and functioning on the system, then the batch will
-be divided among all available processors.
-
-If this gem has been installed, then when running in batch mode, if we have six
-CPU cores on the local machine, then we should be able to expect six
-translation processes running concurrently. The exception to this is on the
-"mswin" and "mingw" platforms, which do not have the necessary system calls
-for Unix style multiprocessing. In this case, running Sanzang in the
-Cygwin environment is a viable alternative.
-
-The performance benefits of running with the "parallel" library can be very
-significant, leading to a series of translation listings being generated in a
-mere fraction of the time it would take to process them otherwise. This
-performance gain is typically proportional to the number of processors and
-processor cores available on the local system.
-
-=== Text Encodings
-
-Sanzang supports many possible text encodings. Option "-L" will list all
-available text encodings. Option "-E" will set the encoding to be used for all
-text data such as input texts, output texts, and table files. The other program
-I/O, such as messages for the terminal, will still be in the default encoding
-of the environment. For example, in a Windows environment that by default uses
-the IBM-437 encoding, specifying "-E" with a value of "UTF-16LE" will cause
-Sanzang to read and write all text data in UTF-16LE, but all other program
-messages will still be displayed in the console's native IBM-437 encoding.
+After this, you should be able to run the _sanzang_ command. Run the following
+command to verify your installation and print platform information.
 
-    $ sanzang-translate -E UTF-16LE -i in.txt -o out.txt TABLE.txt
+    # sanzang -P
 
-If the "-E" option is not specified, then Sanzang will use the default encoding
-inherited from the environment. For example, a GNU/Linux user running Sanzang in
-a UTF-8 terminal will by default have all text data read and written to in the
-UTF-8 encoding. The one *exception* to this is for environments using the
-IBM-437 encoding (typically an old Windows command shell). In this case,
-Sanzang will take pity on you and automatically switch to UTF-8 by default, as
-if you had specified the option "-E" with value "UTF-8".
+This command should show a summary of your platform for running \Sanzang.
 
-== Responsible Use
+    Ruby platform: x86_64-linux
+    Ruby version: 2.0.0
+    External encoding: UTF-8
+    Internal encoding: none
+    Fork implemented: true
+    Parallel version: 0.6.4
+    Processors found: 4
+    Sanzang version: 1.0.0
 
-With comprehensive translation tables, Sanzang can often be quite accurate
-and effective. However, this program is still comparable to a simple machine,
-and it can never replace a human translator. Please understand the scope of
-this translation system when using it. No machines can take responsibility for
-a poor translation. In the end, it is you who are responsible for any and all
-publications.
+You now have \Sanzang installed and running on your computer.