先提交一波，后面再继续补

source/about.rst

@@ -1,4 +1,8 @@
 关于 xresloader
 ===============================================
 
++ 工具集Github仓库地址: https://github.com/xresloader
++ 作者: `owent <https://owent.net>`
 
+
+联系作者请发邮件到 admin@owent.net 或 owt5008137@live.com 。

source/index.rst

@@ -6,7 +6,12 @@
 xresloader文档
 ===============================================
 
-`xresloader`_ 是一组用于把Excel数据结构化并导出为程序可读的数据文件的导表工具集。它包含了一系列的工具、协议描述和数据读取代码。
+`xresloader`_ 是一组用于把Excel数据结构化并导出为程序可读的数据文件的导表工具集。它包含了一系列跨平台的工具、协议描述和数据读取代码。
+
+`xresloader`_ 可以把Excel数据按开发者指定的结构输出成 **基于协议的二进制** 、**Msgpack二进制** 、**Lua代码** 、**Javascript代码** 、**XML** 和 **JSON** 等格式。并且提供一系列读取数据的方法。
+
+同时为了方便开发者在不同的开发环境和平台中使用同一份配置， `xresloader`_  还提供了把协议里的某些枚举量导出成协议层所没有原生支持的代码的功能。
+比如，我们可以把protobuf描述的枚举类型导出成 ``json`` 或者 ``lua`` 代码，方便项目中使用。
 
 +----------------------------------------------+--------------------------------------------------------------------------------------+
 |                    构建环境                  |                               Linux (Oracle JDK 8)                                   |
@@ -42,10 +47,9 @@ xresloader文档
    users/xresloader_core
    users/data_mapping
    users/output_format
-   users/data_loading
+   users/xresconv
    users/data_types
    users/advance_usage
-   users/xresconv
    users/faq
 
 .. _development-docs:

source/users/advance_usage.rst

@@ -86,7 +86,7 @@
 使用 ``skill_effect`` 转出如上的表， ``属性`` 这个字段的验证器设为了 ``unit_attribute`` ，``attr_type`` 的类型是int32。
 这时在转出数据的时候，转出的数据是 ``unit_attribute.hp`` 的字段编号 ``1`` 。
 
-只导出部分字段
+仅导出部分字段
 ---------------------------------------------
 
 如果我们需要给客户端和服务器读取同一张Excel表里的不同字段的数据，只要proto不一样即可。对于proto中不存在的字段，我们在转换的时候会忽略掉。
@@ -104,4 +104,4 @@
 定长数组
 ---------------------------------------------
 
-详见 :doc:`./data_types`
+详见 :ref:`数据类型说明-定长数组 <data-types-stable-array>` 章节。

source/users/data_mapping.rst

@@ -16,7 +16,7 @@
 ---------------------------------------------
 
 所有的数据源和规则设置都是Key-Value的形式。并且Value有三个，分别是**主配置，次要配置，补充配置**。
-这三个参数对于不同配置的含义是不同的，具体没想配置的含义请参照 `available_options`_ 章节。
+这三个参数对于不同配置的含义是不同的，具体没想配置的含义请参照 `data-mapping-available-options`_ 章节。
 
 数据映射-Scheme
 ---------------------------------------------
@@ -51,7 +51,7 @@
 
 以上示例是 `xresloader sample`_ 中的 ``arr_in_arr`` 表。
 
-.. _available_options:
+.. _data-mapping-available-options:
 
 可用的配置项
 ---------------------------------------------
@@ -219,4 +219,4 @@
 完整的样例
 ---------------------------------------------
 
-以上配置选项在 `xresloader sample`_ 中都有示例。
+以上配置选项在 `xresloader sample`_ 中有完整的示例，并且在。 `xresloader`_ 的 ``README.md`` 中有举例说明。

source/users/data_types.rst

@@ -21,6 +21,8 @@
 
 这样转出来的数据 ``col`` 的数组长度是2，其中： ``col[0]=123, col[1]=456`` 。
 
+.. _data-types-stable-array:
+
 定长数组
 ---------------------------------------------
 

source/users/faq.rst

@@ -1,2 +1,68 @@
 FAQ
 ===============
+
+哪里有完整的示例？
+-------------------------------------------------------------------------------------------------------
+
+转表功能和二进制数据读取的示例见： https://github.com/xresloader/xresloader/tree/master/sample
+
+文本和Msgpack数据读取示例见： https://github.com/xresloader/xresloader/tree/master/loader-binding
+
+批量转表配置的示例见： https://github.com/xresloader/xresconv-conf
+
+为什么会读到很多空数据？
+-------------------------------------------------------------------------------------------------------
+
+Excel里编辑过的单元格即便删除了也会留下不可见的样式配置，这时候会导致转出的数据有空行。可以通过在Excel里删除行解决
+
+
+为什么Excel里填的时间，但是转出来是一个负数？
+-------------------------------------------------------------------------------------------------------
+
+Excel里的日期时间类型转成协议里整数时会转为Unix时间戳，但是Excel的时间是以1900年1月0号为基准的，这意味着如果时间格式是 ``hh:mm:ss`` 的话，``49:30:01`` 会被转为 ``1900-1-2 1:31:01`` 。
+时间戳因为是相对于 ``1970-01-01 00:00:00`` 的秒数，所以会是一个绝对值很大的负数。
+
+
+Windows下控制台里执行执行会报文件编码错误？（java.nio.charset.UnsupportedCharsetException: cp65001）
+-------------------------------------------------------------------------------------------------------
+
+这个问题涉及的几个Exception是： 
+
+.. code-block:: bash
+
+    ERROR StatusLogger Unable to inject fields into builder class for plugin type class org.apache.logging.log4j.core.appender.ConsoleAppender, element Console.
+    java.nio.charset.UnsupportedCharsetException: cp65001
+            at java.nio.charset.Charset.forName(Unknown Source)
+            at org.apache.logging.log4j.util.PropertiesUtil.getCharsetProperty(PropertiesUtil.java:146)
+            at org.apache.logging.log4j.util.PropertiesUtil.getCharsetProperty(PropertiesUtil.java:134)
+            at org.apache.logging.log4j.core.appender.ConsoleAppender$Target.getCharset(ConsoleAppender.java:85)
+            at org.apache.logging.log4j.core.appender.ConsoleAppender$Target$1.getDefaultCharset(ConsoleAppender.java:71)
+            at org.apache.logging.log4j.core.appender.ConsoleAppender$Builder.build(ConsoleAppender.java:218)
+            at org.apache.logging.log4j.core.appender.ConsoleAppender$Builder.build(ConsoleAppender.java:185)
+            at org.apache.logging.log4j.core.config.plugins.util.PluginBuilder.build(PluginBuilder.java:122)
+    ...
+
+和
+
+.. code-block:: bash
+
+    ERROR StatusLogger Unable to invoke factory method in class class org.apache.logging.log4j.core.appender.ConsoleAppender for element Console.
+    java.lang.IllegalStateException: No factory method found for class org.apache.logging.log4j.core.appender.ConsoleAppender
+            at org.apache.logging.log4j.core.config.plugins.util.PluginBuilder.findFactoryMethod(PluginBuilder.java:224)
+            at org.apache.logging.log4j.core.config.plugins.util.PluginBuilder.build(PluginBuilder.java:130)
+            at org.apache.logging.log4j.core.config.AbstractConfiguration.createPluginObject(AbstractConfiguration.java:952)
+            at org.apache.logging.log4j.core.config.AbstractConfiguration.createConfiguration(AbstractConfiguration.java:892)
+            at org.apache.logging.log4j.core.config.AbstractConfiguration.createConfiguration(AbstractConfiguration.java:884)
+            at org.apache.logging.log4j.core.config.AbstractConfiguration.doConfigure(AbstractConfiguration.java:508)
+            at org.apache.logging.log4j.core.config.AbstractConfiguration.initialize(AbstractConfiguration.java:232)
+            at org.apache.logging.log4j.core.config.AbstractConfiguration.start(AbstractConfiguration.java:244)
+            at org.apache.logging.log4j.core.LoggerContext.setConfiguration(LoggerContext.java:545)
+            at org.apache.logging.log4j.core.LoggerContext.reconfigure(LoggerContext.java:617)
+            at org.apache.logging.log4j.core.LoggerContext.reconfigure(LoggerContext.java:634)
+            at org.apache.logging.log4j.core.LoggerContext.start(LoggerContext.java:229)
+    ...
+
+这是因为在Windows控制台中，如果编码是UTF-8，java获取编码时会获取到cp65001，而这个编码java本身是不识别的。这种情况可以按下面的方法解决：
+
++ 第一种: 执行xresloader之前先执行 chcp 936，切换到GBK编码
++ 第二种: 在powershell里执行

source/users/output_format.rst

@@ -1,53 +1,70 @@
-数据的输出类型和加载方式
+数据的输出类型和数据加载
 =============================================
 
+所有输出的数据的结构都是按照 https://github.com/xresloader/xresloader/blob/master/header/pb_header_v3.proto 的 ``xresloader_datablocks`` 的结构。
+
+转表功能和二进制数据读取的示例见： https://github.com/xresloader/xresloader/tree/master/sample
+
+文本和Msgpack数据读取示例见： https://github.com/xresloader/xresloader/tree/master/loader-binding
+
+下面我们对转出数据和加载进一步说明。
+
 输出类型
 -----------------------------------------------
 
 在 :doc:`./xresloader_core` 里可以看到，转表工具可以把Excel数据源导出成多种输出。下面列举重要的几种，项目可以根据自己的情况选择一种或几种导出方式。比如如果做Web端的GM工具，可以使用导出成xml或者javascript代码。
 
-.. _export binary:
+.. _output-format-export binary:
+
+导出为协议二进制数据 (推荐)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+对应 ``-t bin`` 。这是推荐的转出方式，导出的是 ``xresloader_datablocks`` 打包后的二进制数据，文件占用最小。任何支持protobuf的语言和开发环境都可以读取。
+
+其中每个 ``data_block`` 数据块都对应Excel里的一行数据，里面的数据格式是用户指定的协议打包成二进制后的数据。
+
+.. _output-format-export text:
 
-Step-5-1(推荐): 导出为协议二进制数据
+导出为json、xml、lua代码等文本数据 (可选)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. _export text:
+.. _output-format-export msgpack:
 
-Step-5-2(可选): 导出为json、xml、lua代码等文本数据
+导出为Msgpack打包的二进制数据 (可选)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. _export enum:
+.. _output-format-export enum:
 
-Step-5-3(可选): 导出枚举类型成代码
+导出枚举类型成代码 (可选)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-加载数据
+数据加载
 -----------------------------------------------
 
 加载数据可以有多种方法，项目可以根据自己的需要选择任意一种或几种合适的加载方法。
 
 Step-6-1(推荐): 使用C++加载二进制数据
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-此加载方式需要上面的 :ref:`export binary`
+此加载方式需要上面的 :ref:`output-format-export binary`
 
 Step-6-2(推荐): 使用lua-pbc加载二进制数据
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-此加载方式需要上面的 :ref:`export binary`
+此加载方式需要上面的 :ref:`output-format-export binary`
 
 Step-6-3(推荐): 使用C#和DynamicMessage-net加载二进制数据
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-此加载方式需要上面的 :ref:`export binary`
+此加载方式需要上面的 :ref:`output-format-export binary`
 
 Step-6-4(可选): 使用node.js加载javascript文本数据
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-此加载方式需要上面的 :ref:`export text`
+此加载方式需要上面的 :ref:`output-format-export text`
 
 Step-6-5(可选): 使用lua加载导出的枚举类型
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-此加载方式需要上面的 :ref:`export enum`
+此加载方式需要上面的 :ref:`output-format-export enum`

source/users/quick_start.rst

@@ -10,7 +10,7 @@
 Step-1: 下载转表工具
 -----------------------------------------------
 
-#. 打开 :doc:`download` 。下载最新版本的 **转表工具-xresloader** (xresloader-\*.jar)。
+#. 打开 :doc:`./download` 。下载最新版本的 **转表工具-xresloader** (xresloader-\*.jar)。
 #. 如果要使用命令行版本的批量转换工具则要额外下载 **命令行批量转表工具-xresconv-cli**
 #. 如果要使用GUI版本的批量转换工具则要额外下载 **GUI批量转表工具-xresconv-gui**
 #. 下载或自己编译protobuf官方的protoc工具，可以去 https://github.com/google/protobuf/releases 下载预编译好的protoc
@@ -80,7 +80,7 @@ Step-4: 配置批量转表配置文件
     :language: xml
     :encoding: utf-8
 
-对于文件路径配置的说明: ``work_dir`` 、 ``xresloader_path`` 和 ``include`` （具体含义请参考 :doc:`./advance_usage` ） 配置的路径是相对于xml文件的路径。其他的涉及路径配置的地方如果不是绝对路径的，都是相对于 ``work_dir`` 的路径。
+对于文件路径配置的说明: ``work_dir`` 、 ``xresloader_path`` 和 ``include`` 配置的路径是相对于xml文件的路径。其他的涉及路径配置的地方如果不是绝对路径的，都是相对于 ``work_dir`` 的路径。（具体含义请参考 :doc:`./xresconv` ）
 
 在查找Excel文件的时候，如果有配置 ``data_src_dir`` ，则会相对于这个配置的路径读取Excel，否则也是相对于 ``work_dir`` 。
 

source/users/xresconv.rst

@@ -10,7 +10,15 @@
 批量转表分为 `命令行批量转表工具-xresconv-cli <xresconv-cli>`_ 和 `GUI批量转表工具-xresconv-gui <xresconv-gui>`_ 两个工具。
 
 前者用于服务器和客户端发布流程的集成，后者主要提供给临时转表和策划验证数据时可以拿来转出部分数据。
-这两个工具都以 `批量转表配置模板仓库-xresconv-conf <xresconv-conf>`_ 种的配置为配置规范。具体的配置说明如下： 
+这两个工具都以 `批量转表配置模板仓库-xresconv-conf <xresconv-conf>`_ 中的配置为配置规范。
+
+我们在 :ref:`快速上手-配置批量转表配置文件 <quick-start-configure-sheme>` 章节里也提供了一个简单的例子：
+
+.. literalinclude:: ../sample/quick_start/sample-conf/sample.xml
+    :language: xml
+    :encoding: utf-8
+
+更多具体的配置说明如下： 
 
 .. literalinclude:: ../sample/xresconv_conf.xml
     :language: xml
@@ -24,26 +32,27 @@
 + ``//root/global/work_dir`` : 运行 `xresloader`_ 的目录。如果是相对目录的话相对于xml配置文件。
 + ``//root/global/xresloader_path`` : `xresloader`_ 的jar包的路径。如果是相对目录的话相对于xml配置文件。
 + ``//root/global/java_option`` : 用于传给java命令。所有的条目都会附加到java选项种。比如示例种的 ``-Xmx2048m`` 用于设置最大堆为2GB，用于对于比较大的Excel导表的时候可能会临时占用较高内存。
-+ ``//root/global/default_scheme`` : 默认的导表映射关系的配置（详见 :doc:`./data_mapping` ）。对所有转换条目都会附加这里面的配置项。
-+ ``//root/list/item/scheme`` : 导表映射关系的配置（详见 :doc:`./data_mapping` ）。如果和上面 ``default_scheme``  冲突则会覆盖默认配置，仅对这个条目生效。
++ ``//root/global/default_scheme`` : 默认的导表映射关系的配置（详见 :ref:`data-mapping-available-options` ）。对所有转换条目都会附加这里面的配置项。可多个。
++ ``//root/list/item/scheme`` : 导表映射关系的配置（详见 :ref:`data-mapping-available-options` ）。如果和上面 ``default_scheme``  冲突则会覆盖默认配置，仅对这个条目生效。可多个。
++ ``//root/list/item/option`` : 运行 `xresloader`_ 的额外附加参数（详见 :doc:`./xresloader_core` ）。比如使用 ``--enable-empty-list`` 可以不移除Excel里的空数据，仅对这个条目生效。可多个。
 
 
 其他得配置看内容应该比较容易理解，唯一有个仅用于 `GUI工具 <xresconv-gui>`_ 的配置： ``//root/gui/set_name`` 需要特别说明一下。
-这是里面必须是一个有效的javascript函数，参数是
+这是里面必须是一个有效的javascript函数，参数只有一个，结构是
 
 .. code-block:: javascript
 
-    item_data: {
-        id: ID,
-        file: 文件名,
-        scheme: 涉及的scheme表名称,
-        name: 该条目名称,
-        cat: 该条目的分类,
-        options: [ 选项列表 ],
+    {
+        id: "ID",
+        file: "文件名",
+        scheme: "涉及的scheme表名称",
+        name: "该条目名称，将显示在GUI得树形展示区",
+        cat: "该条目的分类",
+        options: [ "选项列表，对应option配置" ],
         desc: 描述信息,
-        scheme_data: { 转换规则数据 }
+        scheme_data: { "转换规则数据，对应scheme和default_scheme配置" }
     }
 
 这个结构。在 `GUI工具 <xresconv-gui>`_ 显示每个条目的时候会运行这个函数并传入上述结构，在函数离我们可以通过改变 ``name`` 和 ``desc`` 来改变 `GUI工具 <xresconv-gui>`_ 工具的显示内容。
 
-比如我们有个项目所有的表都有个统一前缀，我们就可以在该函数移除掉这个前缀。
+比如 `批量转表配置模板仓库-xresconv-conf <xresconv-conf>`_ 中的 ``sample.xml`` 文件，我们给所有条目的名字附加上了不带后缀的文件名。