Fix HIT-SCIR#111 , add more document.

doc/faq.rst

@@ -0,0 +1,60 @@
+常见问题
+========
+
+1. *“我在本地使用ltp的时候出现 [ERROR] … in LTP::wordseg, failed to load segmentor resource 是怎么回事儿？”*
+
+这个提示的含义是模型加载失败。
+
+**可能原因一** ：模型不存在
+
+如果您没有下载模型，请参考 :ref:`ltpmodel-reference-label` 下载部署模型
+
+**可能原因二** ：模型与ltp版本不对应
+
+ltp在加载模型是会检查模型签名和当前版本号，所以请确定您使用的模型与您使用的ltp版本号对应。
+ltp版本号可以用 :code:`./bin/ltp_test --help` 查看。
+模型版本号可以通过 :code:`ltp_data/version` 查看。
+
+**未知原因**
+
+LTP模型使用二进制文件存储。
+由于 :code:`unsigned long long` 在不同编译器下长度不同，可能存在加载出错。
+对于这种问题，请在我们项目的issue tracker https://github.com/HIT-SCIR/ltp/issues 里面反馈问题。
+在提交issue时，请将您的编译器情况、系统情况（32bit/64bit等）反隐给我们。
+
+2. *“我使用分词词典了，但是为什么某些词典词还是被切开了”*
+
+ltp的分词模块 **并非采用词典匹配的策略** ，外部词典以特征方式加入机器学习算法，并不能保证所有的词都是按照词典里的方式进行切分。
+如果要完全按照词典匹配的方式切词，您可以尝试对切词结果进行后处理。
+
+3. *“可不可以把Java/Python调用LTP，或切词原理文档， 发我一份吗？”*
+
+使用Java或Python调用ltp请参考ltp4j和pyltp这两个项目以及文档中 :ref:`otherlang-reference-label` 部分。
+
+4. *“调用ltp_server时为什会出现400错误？”*
+
+**可能原因一** ：句子过长
+
+为了保证处理效率，ltp对于输入句子长度进行了限制。现在的限制是最大句子长度 *1024字* ，切词结果最多 *256词* 。
+
+**可能原因二** ：编码错误
+
+ltp只接受UTF8编码输入。如果您的输入是GBK编码，请转为 *UTF8无bom编码* 。
+
+5. *“我有很长很长的句子，如何才能打破1024字/256词的限制？”*
+
+**方案一** ：使用 :ref:`xxxcmdline-reference-label`
+
+您可以使用 :code:`xxx_cmdline` 作为替代。:code:`xxx_cmdline` 的分词模块、词性标注模块和命名实体识别模块是没有长度限制的。
+句法分析模块限制长度为1024词。
+
+**方案二** ：修改 :file:`src/ltp/Ltp.h`
+
+修改 :file:`src/ltp/Ltp.h`中 :code:`#define MAX_SENTENCE_LEN 1024` 和 :code:`#define MAX_WORDS_NUM 256` 两个宏，重新编译。
+
+6. *我没找到想要的答案，请问哪里能获得有关ltp的帮助*
+
+您可以在我们的Google group https://groups.google.com/forum/#!forum/ltp-cloud 中发帖提问。
+提问前，请再次确认您的问题没有现成的答案。并在提问时保持礼貌风度。
+有关提问的艺术，请参考池建强老师的博客 http://macshuo.com/?p=367 。
+

doc/index.rst

@@ -21,6 +21,7 @@
     otherlanguage
     train
     theory
+    faq
     paper
     appendix
     license

doc/ltpserver.rst

@@ -166,6 +166,29 @@ LTML 标准要求如下：
 | 400   | BAD XML FORMAT       | 输入句子不符合LTML格式 |
 +-------+----------------------+------------------------+
 
+当前版本服务性能
+----------------
+
+版本：3.3.0
+
+测试使用Xeon(R) CPU E5-2620 0 @ 2.00GHz，4线程，请求时间：3分钟，测试脚本使用pylot 1.26。
+
+Number of agents = 10
+
++------------+----------------------+----------------------+
+| Last Stage | Response Time (secs) | Throughput (req/sec) |
++============+======================+======================+
+| ws         | 0.010                | 643.308              |
++------------+----------------------+----------------------+
+| pos        | 0.012                | 743.809              |
++------------+----------------------+----------------------+
+| dp         | 0.016                | 574.785              |
++------------+----------------------+----------------------+
+| ne	     | 0.014                | 673.661              |
++------------+----------------------+----------------------+
+| srl/all    | 0.036                | 266.094              |
++------------+----------------------+----------------------+
+
 .. rubric:: 注
 
 .. [#f1] 如需指定监听其他端口，请在 :file:`src/server/ltp_server.cpp` 中将宏 `LISTENING_PORT "12345"` 设置为其他整数即可。

doc/ltptest.rst

@@ -3,6 +3,8 @@
 
 一般来讲，基于统计机器学习方法构建的自然语言处理工具通常包括两部分，即：算法逻辑以及模型。模型从数据中学习而得，通常保存在文件中以持久化；而算法逻辑则与程序对应。
 
+.. _ltpmodel-reference-label:
+
 LTP模型文件
 -----------
 
@@ -107,6 +109,8 @@ Pipeline与last-stage参数
 
 默认情况下，LTP将进行至语义角色标注的分析。但是，对于一部分用户，某些分析并不必要。举例来讲，如果用户只需进行词性标注，则ltp_test的pipeline分析只需进行到pos，`last-stage`用来指明分析的最后状态。同时，如果`last-stage`指定为pos，句法分析、命名实体识别和语义角色标注的模型将不被加载。
 
+.. _xxxcmdline-reference-label:
+
 xxx_cmdline
 -----------
 除了 :code:`ltp_test` 将全部分析器整合起来，LTP也提供拆分各模块单独分析的命令行程序。他们包括：
@@ -129,16 +133,62 @@ xxx_cmdline的主要目标是提供不同于xml，同时可自由组合的语言
 
 关于各模块的用法，与ltp_test基本类似。细节请参考 :code:`xxx_cmdline -h`。
 
+细节
+----
+
+.. _ltpexlex-reference-label:
+
+外部词典
+~~~~~~~~
+
+分词外部词典样例如下所示。每个制定一个词。例如 ::
+
+    苯并芘
+    亚硝酸盐
+
+词性标注外部词典样例如下所示。每行指定一个词，第一列指定单词，第二列之后指定该词的候选词性（可以有多项，每一项占一列），列与列之间用空格区分。 ::
+
+	雷人 v a
+	】 wp
+
+ltp项目中可以使用外部词典的模块包括
+
+* :file:`./bin/ltp_test` ：分词、词性外部词典
+* :file:`./bin/ltp_server` ：分词、词性外部词典
+* :file:`./bin/examples/cws_cmdline` ：分词外部词典
+* :file:`./bin/examples/pos_cmdline` ：词性外部词典
+* :file:`./tools/train/otcws` ：分词外部词典
+* :file:`./tools/train/otpos` ：词性外部词典
+
 Window动态链接库
------------------
+~~~~~~~~~~~~~~~~
 
 在Window下首次运行LTP会提示找不到动态链接库，这时请将编译产生的lib/\*.dll拷贝到bin/Release/下，即可正常运行。
 
 编码以及显示
--------------
+~~~~~~~~~~~~
 
 LTP的所有模型文件均使用UTF8 [#f1]_ 编码训练，故请确保待分析文本的编码为UTF8格式。
 
+兼容性测试
+----------
+
+当前版本LTP在以下一些平台和编译器环境下通过测试
+
++-----------------+---------+---------+----------+----------+------------+----------+----------+
+| 系统            | 编译器  | 版本    | ltp_test | 训练套件 | ltp_server | 单元测试 | 模型加载 |
++=================+=========+=========+==========+==========+============+==========+==========+
+| Linux (64bit)   | gnu-c++ | 4.4-4.8 | 支持     | 支持     | 支持       | 支持     | 通过     |
++-----------------+---------+---------+----------+----------+------------+----------+----------+
+| Linux (64bit)   | clang   | 3.4     | 支持     | 支持     | 支持       | 支持     | 通过     |
++-----------------+---------+---------+----------+----------+------------+----------+----------+
+| Windows (64bit) | MSVC    | 12      | 支持     | 支持     | 不支持     | 不支持   | 通过     |
++-----------------+---------+---------+----------+----------+------------+----------+----------+
+| Cygwin (64bit)  | gnu-c++ | 4.8     | 支持     | 支持     | 支持       | 支持     | 通过     |
++-----------------+---------+---------+----------+----------+------------+----------+----------+
+| mingw (64bit)   | gnu-c++ | 4.7     | 支持     | 支持     | 不支持     | 不支持   | 通过     |
++-----------------+---------+---------+----------+----------+------------+----------+----------+
+
 .. rubric:: 注
 
 .. [#f1] 由于Windows终端采用gbk编码显示，运行 :file:`ltp_test` 后会在终端输出乱码。您可以将标准输出重定向到文件，以UTF8方式查看文件，就可以解决乱码的问题。

doc/otherlanguage.rst

@@ -1,3 +1,5 @@
+.. _otherlang-reference-label:
+
 使用其他语言调用ltp
 =======================
 

doc/train.rst

@@ -83,6 +83,8 @@ otcws是ltp分词模型的训练套件，用户可以使用otcws训练获得ltp
 * input：指定输入文件
 * evaluate：true或false，指定是否进行切词结果准确率的评价。如果进行评价，输入的文件应该是人工切分的数据。
 
+外部词典 (lexicon) 格式请参考 :ref:`ltpexlex-reference-label` 。
+
 切分结果将输入到标准io中。
 
 词性标注训练套件otpos用法
@@ -109,11 +111,7 @@ otpos是ltp分词模型的训练套件，用户可以使用otpos训练获得ltp
                             '_' concatenated tag
       -h [ --help ]         Show help information
 
-lexicon文件样例如下所示。每行指定一个词，第一列指定单词，第二列之后指定该词的候选词性（可以有多项，每一项占一列），列与列之间用空格区分。::
-
-	雷人 v a
-	】 wp
-
+外部词典 (lexicon) 格式请参考 :ref:`ltpexlex-reference-label` 。
 
 命名实体识别训练套件otner用法
 -------------------------------

src/console/ltp_test.cpp

@@ -147,7 +147,7 @@ int main(int argc, char *argv[]) {
 
   std::string postagger_model = "ltp_data/pos.model";
   if (vm.count("postagger-model")) {
-    postagger_model= vm["segmentor-model"].as<std::string>();
+    postagger_model= vm["postagger-model"].as<std::string>();
   }
 
   std::string postagger_lexcion = "";

src/framework/io.h

@@ -24,6 +24,7 @@ class LineCountsReader: public Reader {
   LineCountsReader(std::istream& _is): cursor(0), buffer(0), Reader(_is) {
     nr_lines = number_of_lines();
     interval = nr_lines / 10;
+    if (interval == 0) { interval = 1; } /* less than 10 lines. */
   }
 
   ~LineCountsReader() { if (buffer) { delete[](buffer); } }