Update documents.

Author: ChenPi11

README.md

@@ -14,7 +14,7 @@ See [docs/](docs/README.md) for full requirements list.
 
 **We are planning to use [Rubisco](https://github.com/cppp-project/rubisco) to manage submodules. But it is not ready yet. So we don not use git submodule for now. Please clone them manually.**
 
-Use the following command to fetch source code:
+Use the following command to fetch source code, or download source package:
 
 ```shell
 git clone https://github.com/cppp-project/cppp-reiconv
@@ -175,7 +175,7 @@ This library installs:
 
 + A shared library `libcppp-reiconv`.
 + A static library `libcppp-reiconv.static`.
-+ Header files
++ Header files.
 
 ```text
 include

README.zh_CN.md

@@ -0,0 +1,206 @@
+# cppp-reiconv
+
+<img alt="C+++" src="https://avatars.githubusercontent.com/u/130828670" width="10%">
+
+一个基于 GNU LIBICONV 的字符集转换库。**支持 C 和 C++20。**
+
+如果你的 C++ 标准低于 C++20，需要修改一些代码。
+
+## 构建
+
+此库需要 `build-aux` 和 `cppp-platform` 两个子模块用于构建。
+
+参见 [docs/](docs/zh_CN/README.md) 获取完整依赖列表。
+
+**我们正在使用 [Rubisco](https://github.com/cppp-project/rubisco) 管理子模块。但它还没有准备好。所以我们现在不使用 git submodule。请手动克隆它们。**
+
+使用以下命令克隆源代码，或者直接下载源码包：
+
+```shell
+git clone https://github.com/cppp-project/cppp-reiconv
+cd cppp-reiconv
+git clone https://github.com/cppp-project/build-aux --depth 1
+git clone https://github.com/cppp-project/rubisco --depth 1
+```
+
+使用以下命令构建和安装：
+
+```shell
+mkdir build
+cd build
+cmake .. -DCMAKE_BUILD_TYPE=[[BUILD_TYPE]] -DCMAKE_INSTALL_PREFIX=[[PREFIX]]
+cmake --build . --config=[[BUILD_TYPE]]
+cmake --install . --config=[[BUILD_TYPE]]
+```
+
+## 简单的用法
+
+```cpp
+#include <cppp/reiconv.hpp>
+
+#include <cstdlib>
+#include <iostream>
+
+int main()
+{
+    const std::string_view src = "\xb8\xfc\xcf\xb2\xe1\xba\xc9\xbd\xc7\xa7\xc0\xef\xd1\xa9\xa3\xac\xc8\xfd\xbe\xfc\xb9\xfd\xba\xf3\xbe\xa1\xbf\xaa\xd1\xd5\xa3\xa1";
+
+    std::string result = reiconv::convert("GB18030", "UTF-8", src);
+
+    std::cout << result << std::endl;
+
+    const std::string_view correct_result = "\u66f4\u559c\u5cb7\u5c71\u5343\u91cc\u96ea\uff0c\u4e09\u519b\u8fc7\u540e\u5c3d\u5f00\u989c\uff01";
+
+    if (result == correct_result)
+    {
+        std::cout << "正确！" << std::endl;
+    }
+    else
+    {
+        // 如果发生了这个，请提 issue！
+        std::cout << "错误！" << std::endl;
+    }
+
+    return EXIT_SUCCESS;
+}
+```
+
+完整文档参见 [docs/](docs/zh_CN/README.md)。
+
+## 支持的编码
+
+和 GNU LIBICONV 一样，它提供了以下编码的支持：
+
++ 欧洲语言
+  + ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16},
+  + KOI8-R, KOI8-U, KOI8-RU,
+  + CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
+  + Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
+  + Mac{Cyrillic,Ukraine,Greek,Turkish},
+  + Macintosh
++ 闪米特诸族语言
+  + ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}
++ 日本语
+  + EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2, ISO-2022-JP-1,
+  + ISO-2022-JP-MS
++ 中文
+  + EUC-CN, HZ, GBK, CP936, GB18030, GB18030:2022, EUC-TW, BIG5, CP950,
+  + BIG5-HKSCS, BIG5-HKSCS:2004, BIG5-HKSCS:2001, BIG5-HKSCS:1999,
+  + ISO-2022-CN, ISO-2022-CN-EXT
++ 韩语
+  + EUC-KR, CP949, ISO-2022-KR, JOHAB
++ 亚美尼亚语
+  + ARMSCII-8
++ 格鲁吉亚语
+  + Georgian-Academy, Georgian-PS
++ 塔吉克语
+  + KOI8-T
++ 哈萨克语
+  + PT154, RK1048
++ 泰语
+  + ISO-8859-11, TIS-620, CP874, MacThai
++ 老挝语
+  + MuleLao-1, CP1133
++ 越南语
+  + VISCII, TCVN, CP1258
++ 平台特定
+  + HP-ROMAN8, NEXTSTEP
++ 完整的 Unicode
+  + UTF-8
+  + UCS-2, UCS-2BE, UCS-2LE
+  + UCS-4, UCS-4BE, UCS-4LE
+  + UTF-16, UTF-16BE, UTF-16LE
+  + UTF-32, UTF-32BE, UTF-32LE
+  + UTF-7
+  + C99, JAVA
++ 完整的 Unicode，以 'uint16_t' 或 'uint32_t' 表示
+  + UCS-2-INTERNAL, UCS-4-INTERNAL （具有设备依赖的字节序和对齐）
+
+一些额外的编码。这些编码是 GNU LIBICONV 的额外编码。
+
++ 欧洲语言
+  + CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}
++ 闪米特诸族语言
+  + CP864
++ 日本语
+  + EUC-JISX0213, Shift_JISX0213, ISO-2022-JP-3
++ 中文
+  + BIG5-2003 (experimental)
++ 土库曼语
+  + TDS565
++ 平台特定
+  + ATARIST, RISCOS-LATIN1
++ EBCDIC 兼容编码（不兼容ASCII，几乎不使用）
+  + 欧洲语言
+    + IBM-{037,273,277,278,280,282,284,285,297,423,500,870,871,875,880},
+    + IBM-{905,924,1025,1026,1047,1112,1122,1123,1140,1141,1142,1143},
+    + IBM-{1144,1145,1146,1147,1148,1149,1153,1154,1155,1156,1157,1158},
+    + IBM-{1165,1166,4971}
+  + 闪米特诸族语言
+    + IBM-{424,425,12712,16804}
+  + 波斯语
+    + IBM-1097
+  + 泰语
+    + IBM-{838,1160}
+  + 老挝语
+    + IBM-1132
+  + 越南语
+    + IBM-{1130,1164}
+  + 印度语
+    + IBM-1137
+
+它可以通过 Unicode 从这些编码中的任何一种转换为任何其他编码
+转换。
+
+## 编译选项
+
+使用 CMake 进行构建
+
++ `BUILD_TESTING`: 编译测试工具。默认为 `ON`.
+
+```shell
+cmake .. -DBUILD_TESTING=ON
+cmake --build . --config=RelWithDebInfo
+ctest -C RelWithDebInfo --output-on-failure
+```
+
++ `ICONV_COMPAT`: 启用 iconv 兼容。默认为 `OFF`.
+
+如果 `ICONV_COMPAT` 开启，会安装 `iconv.h` 和基本的函数。
+但是我们不支持 POSIX:2024 的所有功能。参见 [TODO](TODO).
+
+## 安装
+
+此库安装：
+
++ 动态库 `libcppp-reiconv`。
++ 静态库 `libcppp-reiconv.static`。
++ 头文件。
+
+```text
+include
+├── cppp
+│   ├── cppp-platform.h
+│   ├── encodings
+│   │   ├── reiconv.h
+│   │   └── reiconv.hpp
+│   ├── reiconv.h
+│   └── reiconv.hpp
+└── iconv.h       # 仅当 ICONV_COMPAT 开启才存在
+```
+
+## 版权
+
+cppp-reiconv 使用 LGPLv3，参见 [LICENSE](./LICENSE).
+
+## 下载
+
+参见 <https://github.com/cppp-project/cppp-reiconv/releases>
+
+## 主页
+
+<https://github.com/cppp-project/cppp-reiconv>
+
+## Bug 反馈
+
++ 请在 GitHub 创建 issue [来一个](https://github.com/cppp-project/cppp-reiconv/issues/new/)

docs/README.md

@@ -1,5 +1,7 @@
 # cppp-reiconv documentation
 
+[[Simplified Chinese]](zh_CN/README.md)
+
 ## Introduction
 
 These docs is for `cppp-reiconv 3.0.0`.
@@ -18,7 +20,7 @@ encodings and locale charset detection.
 
 ### Runtime
 
-- C runtime
+- C runtime.
 - C++ runtime with C++20 support.
 
 ### Build with data generation

docs/c-api.md

@@ -2,7 +2,7 @@
 
 Although we have C API, we still require C++20 runtime.
 
-header file `cppp/reiconv.h` contains all C API.
+Header file `cppp/reiconv.h` contains all C API.
 
 ## Version Information API
 
@@ -42,12 +42,12 @@ extern _CPPP_API size_t reiconv_name_canonicalize(const char *name, char *outbuf
 
 #### Description
 
-Canonicalize an encoding name. the `canonical` means the internal name of
+Canonicalize an encoding name. The `canonical` means the internal name of
 encoding. Not the canonical name of IANA.
 We will ignore '-' and '_', and uppercase all characters.
 
 Segment fault if `name` or `outbuf` is `nullptr`. We will not check the
-length of `outbuf`
+length of `outbuf`.
 
 **This function is not recommended to use.**
 
@@ -343,7 +343,7 @@ Get the size of converted string.
 
 #### Return
 
-The size of converted string. If the conversion failed, returns `(size_t)(-1)`
+The size of converted string. If the conversion failed, returns `(size_t)(-1)`.
 
 **It's don't support flags now, so `flags` is always `REICONV_NO_FLAGS`. We will**
 **support it in the next version. So this API will change in the next version.**
@@ -378,7 +378,7 @@ If the output buffer is too small, -1 is returned.
 If the output buffer is too big, the rest of the buffer will not change.
 
 This function is useful when you want to convert a string to a fixed size buffer
-like stack buffer. It's faster than `reiconv_convert`
+like stack buffer. It's faster than `reiconv_convert`.
 
 #### Parameters
 
@@ -441,7 +441,7 @@ Bruno Haible put this file into the public domain.
 we will allocate memory for you and set it to the result buffer. If pointed but
 not `NULL`, we will use it as the output buffer but reallocate it. So it must be
 a pointer that can be modified.
-**But don't let it value to `NULL`!**
+**But don't let output_data_ptr's value to `NULL`!**
 - `output_length_ptr`: The length of output buffer. If NULL, error will be occured.
 
 #### Return
@@ -550,8 +550,6 @@ printf("Your locale charset is: %s\n", charset);
 Iconv compatibility is disabled by default. You can enable it by defining
 `-DICONV_COMPAT=ON` when you configure cppp-reiconv.
 
-See "Iconv support" section below.
-
 ### `iconv_t`, aka `reiconv_t` in `cppp/reiconv.h`
 
 #### Definition

docs/cpp-api.md

@@ -199,7 +199,7 @@ memory for the output string.
 
 #### Throws
 
-std::system_error if the conversion failed. Use it because it's has errno set.
+- `std::system_error` If the conversion failed. Use it because it's has errno set.
 
 #### Example
 
@@ -233,7 +233,7 @@ The current locale's character encoding.
 
 #### Example
 
-```c
+```cpp
 std::setlocale(LC_ALL, "");
 std::string_view charset = reiconv::locale_charset();
 std::cout <<"Your locale charset is: " << charset << std::endl;

docs/zh_CN/README.md

@@ -0,0 +1,41 @@
+# cppp-reiconv 文档
+
+## 介绍
+
+这是 `cppp-reiconv 3.0.0` 文档。不稳定版本。
+
+cppp-reiconv 是一个可移植的 C/C++ 库，用于字符编码之间的转换和字符集检测。
+
+## 依赖
+
+### 构建
+
+- 一个支持 C++20 的 C++ 编译器。
+- CMake 3.12 或更高版本.
+
+### 运行时
+
+- C 运行时。
+- 支持 C++20 的 C++ 运行时。
+
+### 生成数据
+
+我们需要为编码生成索引，它们存储在 `lib/generated` 中。
+
+**如果你不感兴趣，你可以跳过这步骤。**
+**我们已经在 Git 仓库和源码包提供了相关数据。**
+
+- GNU Make.
+- GNU Gperf.
+- 一个 POSIX 操作系统.
+
+安装以上工具以后，你可以用下面的命令生成数据：
+
+```shell
+make -f Makefile.devel -B
+```
+
+## API 参考
+
+- [C API 和 iconv 兼容 API 参考](c-api.md)
+- [C++ API 参考](cpp-api.md)