Merge pull request #6 from misonyo/master

[更新]文档格式调整

README.md

@@ -46,7 +46,7 @@ WebNet 软件包遵循 GPL2+ 商业双许可。该软件包可以根据 GNU 标
 
 使用 WebNet软件包需要在 RT-Thread 的包管理中选中它，具体路径如下： 
 
-```shell
+```c
 RT-Thread online packages
     IoT - internet of things  --->
     	[*] WebNet: A HTTP Server for RT-Thread
@@ -95,7 +95,7 @@ RT-Thread online packages
 ## 4、注意事项
 
 - WebNet 软件包使用需要文件系统支持，需要确保运行设备上能使用文件系统。
-- WebNet 软件包默认未开启任何模块功能支持，使用的需要根据[软件包介绍](docs/introduction.md)在 ENV 中开启需要的功能。
+- WebNet 软件包默认未开启任何模块功能支持，使用的需要根据[软件包介绍](docs/introduction.md)在 Env 中开启需要的功能。
 
 ## 5、联系方式 & 感谢
 

docs/README.md

@@ -6,7 +6,7 @@
 
 ## 文档列表
 
-|文件名                             |描述|
+|**文件名**                             |**描述**|
 |:-----                             |:----|
 |[version.md](version.md)           |版本信息|
 |[introduction.md](introduction.md) |详细介绍|

docs/api.md

@@ -4,233 +4,269 @@
 
 ## 初始化函数
 
-> int webnet_init(void);
+```c
+int webnet_init(void);
+```
 
 用于初始化 WebNet 服务器，包括创建线程用于监听客户端连接事件、初始化开启的功能模块等功能；
 
-| 参数     | 描述       |
+|**参数**     | **描述**       |
 | :------- | :--------- |
 | 无       | 无         |
-| **返回** | **描述**   |
+| **返回** | **--**   |
 | = 0      | 初始化成功 |
 | < 0      | 初始化失败 |
 
 ## 设置监听套接字端口
 
-> void webnet_set_port(int port);
+```c
+void webnet_set_port(int port);
+```
 
 用于设置当前 WebNet 服务器监听端口号，WebNet 服务器默认监听端口号是 80，这也是 HTTP 协议默认端口号。使用默认端口号访问 URL 地址时可以不输入端口号直接访问，当使用非默认端口号时，需要在 URL 地址上指明端口号，如：`http://host:8080/index.html` 。该函数只能**用于 WebNet 服务器初始化之前**。
 
-| 参数      | 描述                  |
+|**参数**      | **描述**                  |
 | :------- | :------------------- |
 | port     | 设置的监听套接字端口    |
-| **返回**  | **描述**              |
+| **返回**  | **--**              |
 | 无       | 无                   |
 
 ## 获取监听套接字端口
 
-> int webnet_get_port(void);
+```c
+int webnet_get_port(void);
+```
 
 用于获取当前 WebNet 服务器监听套接字端口号。
 
-| 参数     | 描述             |
+|**参数**     | ****描述****             |
 | :------- | :--------------- |
 | 无       | 无               |
-| **返回** | **描述**         |
+| **返回** | **--**         |
 | >=0      | 监听套接字端口号 |
 
 ## 设置服务器根目录
 
-> void webnet_set_root(const char* webroot_path);
+```c
+void webnet_set_root(const char* webroot_path);
+```
 
 用于设置当前 WebNet 服务器根目录路径，WebNet 服务器默认根目录为 `/webnet`，浏览器和 WebNet 函数中使用或访问的路径都是基于根目录路径。当浏览器访问 `http://host/index.html` 时，会把文件系统中的 `/webnet/index.html` 返回给浏览器。
 
-| 参数         | 描述             |
+|**参数**         | **描述**             |
 | :----------- | :--------------- |
 | webroot_path | 设置的根目录地址 |
-| **返回**     | **描述**         |
+| **返回**     | **--**         |
 | 无           | 无               |
 
 ## 获取服务器根目录
 
-> const char* webnet_get_root(void);
+```c
+const char* webnet_get_root(void);
+```
 
 用于获取当前 WebNet 服务器根目录地址。
 
-| 参数     | 描述       |
+|**参数**     | **描述**       |
 | :------- | :--------- |
 | 无       | 无         |
-| **返回** | **描述**   |
+| **返回** | **--**   |
 | != NULL  | 根目录地址 |
 
 ## 获取请求链接的类型
 
-> const char* mime_get_type(const char* url);
+```c
+const char* mime_get_type(const char* url);
+```
 
 用于获取当前请求 URL 链接的类型，如：网页、图片、文本等。
 
-| 参数     | 描述           |
+|**参数**     | **描述**           |
 | :------- | :------------- |
 | url      | 请求链接的地址 |
-| **返回** | **描述**       |
+| **返回** | **--**       |
 | != NULL  | 请求链接的类型 |
 
 ## 添加 ASP 变量处理方式
 
-> void webnet_asp_add_var(const char* name, void (*handler)(struct webnet_session* session));
+```c
+void webnet_asp_add_var(const char* name, void (*handler)(struct webnet_session* session));
+```
 
 该函数用于添加一个 ASP 变量处理方式，当 ASP 文件中出现添加的 `name` 变量名时，会执行对应的 `handle`  操作。
 
-| 参数                                            | 描述             |
+|**参数**                                            | **描述**             |
 | :---------------------------------------------- | :--------------- |
 | name                                            | ASP 变量名称     |
 | void (*handler)(struct webnet_session* session) | ASP 变量处理方式 |
-| **返回**                                        | **描述**         |
+| **返回**                                        | **--**         |
 | 无                                              | 无               |
 
 ## 添加 CGI 事件处理方式
 
-> void webnet_cgi_register(const char* name, void (*handler)(struct webnet_session* session));
+```c
+void webnet_cgi_register(const char* name, void (*handler)(struct webnet_session* session));
+```
 
 该函数用于注册一个 CGI 事件处理方式，当浏览器请求带有 `name` 名称的 URL 时，会执行相应的 `handle` 操作。
 
-| 参数                                            | 描述             |
+|**参数**                                            | **描述**             |
 | :---------------------------------------------- | :--------------- |
 | name                                            | CGI 事件名称     |
 | void (*handler)(struct webnet_session* session) | CGI 事件处理方式 |
-| **返回**                                        | **描述**         |
+| **返回**                                        | **--**         |
 | 无                                              | 无               |
 
 ## 设置 CGI 事件根目录
 
-> void webnet_cgi_set_root(const char* root);
+```c
+void webnet_cgi_set_root(const char* root);
+```
 
 WebNet 服务器默认的 CGI 事件根目录为`/cgi-bin`，当浏览器请求 `http://host/cgi-bin/test` 地址时，会执行 `test` 名称对应的 CGI 事件处理函数。
 
 该函数用于设置新的 CGI 事件根目录，设置成功之前的 CGI 根目录将不再起作用。
 
-| 参数     | 描述           |
+|**参数**     | **描述**           |
 | :------- | :------------- |
 | root     | CGI 事件根目录 |
-| **返回** | **描述**       |
+| **返回** | **--**       |
 | 无       | 无             |
 
 ## 设置基本认证信息
 
-> void webnet_auth_set(const char* path, const char* username_password);
+```c
+void webnet_auth_set(const char* path, const char* username_password);
+```
 
 用于设置目录访问时的基本认证信息，包括用户名和密码。
 
-| 参数              | 描述                                           |
+|**参数**              | **描述**                                           |
 | :---------------- | :--------------------------------------------- |
 | path              | 需要设置基本认证信息的目录                     |
 | username_password | 设置的用户名和密码，格式为 `username:password` |
-| **返回**          | **描述**                                       |
+| **返回**          | **--**                                       |
 | 无                | 无                                             |
 
 ## 设置目录别名
 
-> void webnet_alias_set(char* old_path, char* new_path);
+```c
+void webnet_alias_set(char* old_path, char* new_path);
+```
 
 用于设置目录的别名，设置成功之后可以使用目录别名访问该目录。
 
-| 参数     | 描述                                     |
+|**参数**     | **描述**                                     |
 | :------- | :--------------------------------------- |
 | old_path | 需要设置别名的目录                       |
 | new_path | 设置的目录别名，一般为服务器中存在的目录 |
-| **返回** | **描述**                                 |
+| **返回** | **--**                                 |
 | 无       | 无                                       |
 
 ## 发送 HTTP 请求头部
 
-> void webnet_session_set_header(struct webnet_session* session, const char* mimetype, int code, const char* title, int length);
+```c
+void webnet_session_set_header(struct webnet_session* session, const char* mimetype, int code, const char* title, int length);
+```
 
 用于拼接并发送头部信息到连接的客户端，一般用于 ASP 变量处理函数和 CGI 事件处理函数中。
 
-| 参数     | 描述                                                         |
+|**参数**     | **描述**                                                         |
 | :------- | :----------------------------------------------------------- |
 | session  | 当前服务器连接的会话                                         |
 | mimetype | 需要发送的响应文件类型（Content-Type），可以使用  `mime_get_type`  函数获取 |
 | code     | 发送的响应状态码，正常为 200                                 |
 | title    | 发送的响应状态类型，正常为 OK                                |
 | length   | 需要发送的响应文件长度（Content-Length）                     |
-| **返回** | **描述**                                                     |
+| **返回** | **--**                                                     |
 | 无       | 无                                                           |
 
 ## 发送 HTTP 响应数据
 
-> int  webnet_session_write(struct webnet_session* session, const rt_uint8_t* data, rt_size_t size);
+```c
+int  webnet_session_write(struct webnet_session* session, const rt_uint8_t* data, rt_size_t size);
+```
 
 用于发送响应数据到客户端，一般用于 ASP 变量处理函数和 CGI 事件处理函数中。
 
-| 参数     | 描述                 |
+|**参数**     | **描述**                 |
 | :------- | :------------------- |
 | session  | 当前服务器连接的会话 |
 | data     | 发送的数据指针       |
 | size     | 发送的数据长度       |
-| **返回** | **描述**             |
+| **返回** | **--**             |
 | 无       | 无                   |
 
 
 ## 发送 HTTP 固定格式响应数据
 
-> void webnet_session_printf(struct webnet_session* session, const char* fmt, ...);
+```c
+void webnet_session_printf(struct webnet_session* session, const char* fmt, ...);
+```
 
 用于发送固定格式的响应数据到客户端，一般用于 ASP 变量处理函数和 CGI 事件处理函数中。
 
-| 参数     | 描述                     |
+|**参数**     | **描述**                     |
 | :------- | :----------------------- |
 | session  | 当前服务器连接的会话     |
 | fmt      | 自定义的输入数据的表达式 |
 | ...      | 输入的参数               |
-| **返回** | **描述**                 |
+| **返回** | **--**                 |
 | 无       | 无                       |
 
 ## 获取上传文件的名称
 
-> const char* webnet_upload_get_filename(struct webnet_session* session);
+```c
+const char* webnet_upload_get_filename(struct webnet_session* session);
+```
 
 获取当前上传文件的名称，用于打开或创建文件。
 
-| 参数     | 描述                 |
+|**参数**     | **描述**                 |
 | :------- | :------------------- |
 | session  | 当前服务器连接的会话 |
-| **返回** | **描述**             |
+| **返回** | **--**             |
 | != NULL  | 当前上传文件的名称   |
 
 ## 获取上传文件的类型
 
-> const char* webnet_upload_get_content_type(struct webnet_session* session);
+```c
+const char* webnet_upload_get_content_type(struct webnet_session* session);
+```
 
 获取当前上传文件的类型。
 
-| 参数     | 描述                 |
+|**参数**     | **描述**                 |
 | :------- | :------------------- |
 | session  | 当前服务器连接的会话 |
-| **返回** | **描述**             |
+| **返回** | **--**             |
 | != NULL  | 当前上传文件的类型   |
 
 ## 获取上传文件参数
 
->  const char* webnet_upload_get_nameentry(struct webnet_session* session, const char* name);
+```c
+const char* webnet_upload_get_nameentry(struct webnet_session* session, const char* name);
+```
 
 获取注册的上传文件的分隔符（HTTP 请求 boundary 参数）。
 
-| 参数     | 描述                 |
+|**参数**     | **描述**                 |
 | :------- | :------------------- |
 | session  | 当前服务器连接的会话 |
 | name     | 上传文件的目录路径   |
-| **返回** | **描述**             |
+| **返回** | **--**             |
 | != NULL  | 当前上传文件的类型   |
 
 ## 获取上传文件打开的文件描述符
 
-> const void* webnet_upload_get_userdata(struct webnet_session* session);
+```c
+const void* webnet_upload_get_userdata(struct webnet_session* session);
+```
 
 获取当前上传文件打开之后生成的文件描述符，用于读写数据到文件中。
 
-| 参数     | 描述                     |
+|**参数**     | **描述**                     |
 | :------- | :----------------------- |
 | session  | 当前服务器连接的会话     |
-| **返回** | **描述**                 |
+| **返回** | **--**                 |
 | != NULL  | 上传文件打开的文件描述符 |

docs/introduction.md

@@ -6,7 +6,7 @@ WebNet 软件包是 RT-Thread 自主研发的，基于 HTTP 协议的 Web 服务
 
 WebClient 软件包目录结构如下所示：
 
-| 名称       | 说明                     |
+| **名称**       | **说明**                     |
 | ---------- | ------------------------ |
 | docs       | 文档目录                 |
 | inc        | 头文件目录               |

docs/samples.md

@@ -4,7 +4,7 @@ WebNet 软件包提供了一个综合的示例页面用于展示软件包的多
 
 **示例文件**
 
-| 示例程序路径                         | 说明  |
+| **示例程序路径**                         | **说明**  |
 | ----                                | ---- |
 | samples/wn_sample.c      | 综合示例代码 |
 | samples/wn_sample_upload.c | 上传文件示例代码 |
@@ -18,11 +18,9 @@ WebNet 软件包提供了一个综合的示例页面用于展示软件包的多
 
 - menuconfig 配置获取软件包和示例代码
 
-    打开 RT-Thread 提供的 ENV 工具，使用 **menuconfig** 配置软件包。
+ 打开 RT-Thread 提供的 Env 工具，使用 **menuconfig** 配置软件包。启用 WebNet 软件包，并配置使能测试例程配置（**Enable webnet samples**），如下所示：
 
-    启用 WebNet 软件包，并配置使能测试例程配置（**Enable webnet samples**），如下所示：
-
-```shell
+```c
 RT-Thread online packages
     IoT - internet of things  --->
     	[*] WebNet: A HTTP Server for RT-Thread
@@ -75,14 +73,14 @@ WebNet 软件包示例中需要获取本地静态页面，需要文件系统的
 
 设备启动，连接网络成功之后，在 Shell 命令行输入 `webnet_test` 命令启动 WebNet 服务器。查看 Shell 命令行，显示如下日志信息，说明 WebNet 服务器初始化成功：
 
-```shell
+```c
 msh />webnet_test
 [I/wn] RT-Thread webnet package (V2.0.0) initialize success.
 ```
 
 然后在 Shell 命令行中使用 `ifconfig` 命令获取本设备 IP地址为 **192.168.12.29**。
 
-```shell
+```c
 msh />ifconfig
 network interface: w0 (Default)
 MTU: 1500

docs/user-guide.md

@@ -4,11 +4,11 @@
 
 ## 准备工作
 
-### ENV 配置说明
+### Env 配置说明
 
-首先需要下载 WebNet 软件包，并将软件包加入到项目中。在 BSP 目录下使用 menuconfig 命令打开 ENV 配置界面，在 `RT-Thread online packages → IoT - internet of things` 中选择 WebNet软件包，具体路径如下：
+首先需要下载 WebNet 软件包，并将软件包加入到项目中。在 BSP 目录下使用 menuconfig 命令打开 Env 配置界面，在 `RT-Thread online packages → IoT - internet of things` 中选择 WebNet软件包，具体路径如下：
 
-```shell
+```c
 RT-Thread online packages
     IoT - internet of things  --->
     	[*] WebNet: A HTTP Server for RT-Thread
@@ -145,7 +145,7 @@ struct webnet_session
 };
 ```
 
-   `webnet_session` 结构体用于存放当前建立的连接会话的部分信息，可用与当前会话连接的整个流程。在进行 HTTP 数据交互之前，需要先创建并初始化该结构体，**新会话的创建已经在 webnet 线程中完成**，如下所示：
+`webnet_session` 结构体用于存放当前建立的连接会话的部分信息，可用与当前会话连接的整个流程。在进行 HTTP 数据交互之前，需要先创建并初始化该结构体，**新会话的创建已经在 webnet 线程中完成**，如下所示：
 
 ```c
 struct webnet_session* accept_session;
@@ -157,6 +157,7 @@ if (accept_session == RT_NULL)
 ```
 
 3. **接收 HTTP 请求数据，解析请求信息**
+
     创建会话结构体成功之后，当连接会话接收到 HTTP 请求后，会对接收的 HTTP 请求进行处理，顺序地解析请求的类型、头部信息及附加参数。大致解析请求信息的流程如下所示：
 
 ```c
@@ -394,6 +395,7 @@ WebNet 服务器初始化成功之后，直接在浏览器中输入设置 IP 地
 - **ALIAS 别名访问功能 **
 
 ALIAS 别名访问功能可以给文件夹设置别名访问。需要在 WebNet 服务器初始化之前设置该文件夹的别名，如下代码所示，调用 `webnet_alias_set` 函数设置 /test 目录的别名为 /admin，浏览器访问 /test 时会跳转访问到 /admin 目录：
+
 ```c
 void webnet_test(void)
 {
@@ -509,13 +511,18 @@ WebNet 服务器预压缩功能，需要在服务器端提前压缩页面资源
 
 ## 常见问题
 
-**1. 浏览器访问设备 IP 地址不显示页面信息**
+### Q: 浏览器访问设备 IP 地址不显示页面信息。
 
-- 原因：设置的根目录地址错误；
+**A:**
+
+- 原因：设置的根目录地址错误。
 
 - 解决方法：确定设置的根目录地址和设备文件系统上创建的目录地址一致，确定根目录下有页面文件。
 
-**2. 设备出现 `out of pbuf` 错误情况**
+### Q: 设备出现 `out of pbuf` 错误情况。
+
+**A:**
+
+- 原因：设备内存不足。
 
-- 原因：设备内存不足；
 - 解决方式： WebNet 软件包上传文件等功能需要额外占用资源空间，建议在资源空间充足的设备上运行，或者在 qemu 上使用。

docs/version.md

@@ -1,6 +1,6 @@
 # 版本和修订
 
-| Date       | Version   |  Author    | Note    |
+| **Date**       | **Version**   |  **Author**    | **Note**    |
 | --------   | :-----:   | :----      | :----   |
 | 2013-05-05 | v1.0.0    | bernard    | 初始版本 |
 | 2018-08-06 | v2.0.0    | chenyong   | 版本更新 |