update syntax docs

4 files changed, 378 insertions, 7 deletions

diff --git a/guide/faq.md b/guide/faq.md
index 0afdabfe..fc6223d2 100644
--- a/guide/faq.md
+++ b/guide/faq.md
@@ -60,7 +60,7 @@ $ xmake -v --backtrace
 $ xmake [-w|--warning] 
 ```
 
-## How to scan source code and generate xmake.lua automaticlly
+## How to scan source code and generate xmake.lua automaticlly?
 
 You only need run the following command:
 
@@ -84,3 +84,10 @@ $ xmake f -y
 
 If you want to known more information please see [Scan source codes and build project without makefile](https://tboox.org/2017/01/07/build-without-makefile/)
 
+## Why is xmake.lua being executed multiple times?
+
+Xmake.lua is divided into description fields and script fields. In the description field, various configuration fields are parsed multiple times in stages, and it is possible to execute multiple times. Therefore, do not write complex scripts in the description field.
+
+If you want to write a variety of complex scripts, please configure them in the script domain. The script domain of `target/on_load` can also flexibly configure various target related settings and provide more powerful lua script module support.
+
+See: [Description of Syntax Description](/guide/syntax_description) for more details.
diff --git a/guide/syntax_description.md b/guide/syntax_description.md
index 66e96dcc..63bd8373 100644
--- a/guide/syntax_description.md
+++ b/guide/syntax_description.md
@@ -9,6 +9,187 @@ target("test")
     add_files("src/*.c")
 ```
 
+## Configuration Separation
+
+Xmake.lua uses the 28th principle to implement a two-layer separate configuration of the description domain and the script domain.
+
+What is the 28th principle? In short, most of the project configuration, 80% of the cases, are basic basic configurations, such as: `add_cxflags`, `add_links`, etc.
+Only less than 20% of the space needs to be extra complex to meet some special configuration needs.
+
+The remaining 20% of the configuration is usually more complicated. if it is directly flooded in the whole xmake.lua, the whole project configuration will be very confusing and very unreadable.
+
+Therefore, xmake isolates 80% of simple configuration and 20% of complex configuration by describing two different configurations of domain and script domain, making the whole xmake.lua look very clear and intuitive, readable and maintainable. Get the best.
+
+### Description Scope
+
+for beginners who are just getting started, or just to maintain some simple small projects, the requirements are fully met by describing the configuration completely. What is the description domain? It looks like this:
+
+```lua
+target("test")
+    set_kind("binary")
+    add_files("src/*.c")
+    add_defines("DEBUG")
+    add_links("pthread", "m", "dl")
+```
+
+At first glance, it is actually a configuration set of `set_xxx`/`add_xxx`. for the novice, you can not use it as a lua script, just as an ordinary, but there are some basic rules configuration files.
+
+if, by looking, there are parentheses, or function calls like scripting languages, then we can also write this (whether with parentheses to see personal preferences):
+
+```lua
+target "test"
+    set_kind "binary"
+    add_files "src/*.c"
+    add_defines "DEBUG"
+    add_links "pthread", "m", "dl"
+```
+
+Is this looking more like a profile? In fact, the description field is a configuration file, similar to the configuration of keys/values such as json, so even if you are not a newcomer to lua, you can quickly get started.
+
+Moreover, for the usual projects, only the various settings of the project are configured by `set_xxx/add_xxx`, which has fully met the requirements.
+
+This is what I said at the beginning: 80% of the time, you can use the simplest configuration rules to simplify the configuration of the project, improve readability and maintainability, so that users and developers will be very friendly and more intuitive.
+
+What if we want to make some conditional judgments for different platforms and architectures? It doesn't matter, the description field is in addition to the basic configuration, it also supports conditional judgment, as well as the for loop:
+
+```lua
+target("test")
+    set_kind("binary")
+    add_files("src/*.c")
+    add_defines("DEBUG")
+    if is_plat("linux", "macosx") then
+        add_links("pthread", "m", "dl")
+    end
+```
+
+```lua
+target("test")
+    set_kind("binary")
+    add_files("src/*.c")
+    add_defines("DEBUG")
+    for _, name in ipairs({"pthread", "m", "dl"}) do
+        add_links(name)
+    end
+```
+
+Is this looking a bit like lua? Although, it can usually be regarded as a common configuration problem, but xmake is based on lua after all, so the description domain still supports the basic language features of lua.
+
+!> However, it should be noted that although the description field supports lua script syntax, try not to write too complicated lua scripts in the description field, such as some time-consuming function calls and for loops.
+
+And in the description field, the main purpose is to set the configuration item, so xmake does not completely open all module interfaces, many interfaces are forbidden to be called in the description field.
+Even open callable interfaces are completely read-only, and time-consuming security interfaces such as `os.getenv()` read some general system information for configuration logic control.
+
+!> Also note that xmake.lua is parsed multiple times to resolve different configuration fields at different stages: for example: `option()`, `target()`, etc.
+
+So, don't think about writing complex lua scripts in the description field of xmake.lua, and don't call print in the description field to display the information, because it will be executed multiple times, remember: it will be executed multiple times! ! !
+
+### Script Scope
+
+Restrict the description field to write complex lua, all kinds of lua modules and interfaces are not used? How to do? This time is the time for the script domain to appear.
+
+if the user is already fully familiar with xmake's description domain configuration and feels that some of the special configuration maintenance on the project is not met, then we can do more complex configuration logic in the script domain:
+
+```lua
+target("test")
+    set_kind("binary")
+    add_files("src/*.c")
+    on_load(function (target)
+        if is_plat("linux", "macosx") then
+            target:add("links", "pthread", "m", "dl")
+        end
+    end)
+    after_build(function (target)
+        Import("core.project.config")
+        Local targetfile = target:targetfile()
+        Os.cp(targetfile, path.join(config.buildir(), path.filename(targetfile)))
+        Print("build %s", targetfile)
+    end)
+```
+
+As long as it is similar: `on_xxx`, `after_xxx`, `before_xxx`, etc. The script inside the function body belongs to the script field.
+
+In the script domain, the user can do anything, xmake provides an import interface to import various lua modules built into xmake, and can also import user-supplied lua scripts.
+
+We can implement any function you want to implement in the script domain, even if you write a separate project.
+
+for some script fragments, it is not very bloated, such as the above built-in writing is enough, if you need to implement more complex scripts, do not want to be filled in a xmake.lua, you can separate the script into a separate lua file for maintenance.
+
+E.g:
+
+```lua
+target("test")
+    set_kind("binary")
+    add_files("src/*.c")
+    on_load("modules.test.load")
+    on_install("modules.test.install")
+```
+
+We can place the custom scripts in the corresponding directory of xmake.lua, and maintain them independently in `modules/test/load.lua` and `modules/test/install.lua`.
+
+In these independent lua scripts, we can also import various built-in modules and custom modules through [import](/zh-cn/manual/builtin_modules?id=import), just like to write lua, java is no different. .
+
+for the different stages of the script's domain, `on_load` is mainly used for target loading, do some dynamic configuration, not like the description field, it will only be executed once!!!
+
+In other stages, there are many, such as: `on/after/before`_`build/install/package/run`, etc. See the target api manual section later, so I won’t go into details here.
+
+## Configuration Type
+
+In the description domain configuration, you can configure the configuration fields and configuration items. In the configuration domain, you can configure various configuration items through the interface of `set_xxx`/`add_xxx`.
+
+```lua
+target("test1")
+    set_kind("binary")
+    add_files("src/*.c")
+
+target("test2")
+    set_kind("binary")
+    add_files("src/*.c")
+```
+
+In the above configuration, the target belongs to the configuration domain, and all the `set_xx`/`add_xxx` interface configurations below it belong to the configuration item, which is partially effective for this target.
+
+We can understand it as a local scope, similar to the block block in c:
+
+```
+target("test1")
+{
+    set_kind("binary")
+    add_files("src/*.c")
+}
+target("test2")
+{
+    set_kind("binary")
+    add_files("src/*.c")
+}
+```
+
+However, in order to simplify the writing, xmake stipulates that each newly defined target field starts, and the last configuration field ends automatically. Of course, if the user feels troubled, you can manually configure the leaving domain:
+
+
+```lua
+target("test1")
+    set_kind("binary")
+    add_files("src/*.c")
+target_end()
+
+target("test2")
+    set_kind("binary")
+    add_files("src/*.c")
+target_end()
+```
+
+### Configuration Scope
+
+Currently available configuration scopes are: `target()`, `option()`, `task()`, `package()`
+
+for a detailed description of each domain, see: [API Manual](/manual/project_target)
+
+### Configuration Item
+
+As long as the configuration with the words `set_xxx` and `add_xxx` is a configuration item, multiple configuration items can be set in one configuration field.
+
+for a description of the configuration items, see: [Interface Specifications](/manual/specification)
+
 ## Scope
 
 The description syntax of xmake is divided by scope, which is mainly divided into:
@@ -200,7 +381,7 @@ target_end()
 
 Call `option_end()`, `target_end()` to explicitly leave the current target/option field setting.
 
-### Scope indentation
+### Scope Indentation
 
 Indentation in xmake.lua is just a specification for more clear distinction. The current setting is for that scope, although it is ok even if it is not indented, but it is not very readable. .
 
@@ -226,6 +407,66 @@ Therefore, proper indentation helps to better maintain xmake.lua
 
 Finally attached, tbox's [xmake.lua](https://github.com/tboox/tbox/blob/master/src/tbox/xmake.lua) description, for reference only. .
 
+## Multi-level Configuration
+
+In the script field we can import various rich extension modules by import, and in the description field we can introduce the project subdirectory through the [includes](/#/zh-cn/manual/global_interfaces?id=includes) interface. The xmake.lua configuration.
+
+Remember: xmake's includes handles the configuration relationship according to the tree structure. The target configuration in xmake.lua in the subdirectory inherits the root domain configuration in the parent xmake.lua, for example:
+
+Currently there are the following project structures:
+
+```
+Projectdir
+    - xmake.lua
+    - src
+      - xmake.lua
+```
+
+`projectdir/xmake.lua` is the project's root xmake.lua configuration, and `src/xmake.lua` is a sub-configuration of the project.
+
+`projectdir/xmake.lua` content:
+
+```lua
+add_defines("ROOT")
+
+target("test1")
+    set_kind("binary")
+    add_files("src/*.c")
+    add_defines("TEST1")
+
+target("test2")
+    set_kind("binary")
+    add_files("src/*.c")
+    add_defines("TEST2")
+
+Includes("src")
+```
+
+The global root domain is configured with `add_defines("ROOT")`, which affects all target configurations below, including all target configurations in the sub-xmake.lua of includes, so this is the global total configuration.
+
+The `add_defines("TEST1")` and `add_defines("TEST2")` in test1/test2 belong to the local configuration and only take effect on the current target.
+
+`src/xmake.lua` content:
+
+```lua
+add_defines("ROOT2")
+
+target("test3")
+    set_kind("binary")
+    add_files("src/*.c")
+    add_defines("TEST3")
+```
+
+In the `src/xmake.lua` sub-configuration, there is also a global root domain, configured with `add_defines("ROOT2")`, which belongs to the sub-configuration root domain and only takes effect on all targets in the current sub-xmake.lua. For the target xmake.lua in the lower level includes the target, because previously said, xmake is the configuration inheritance relationship of the tree structure.
+
+Therefore, the final configuration results of these targets are:
+
+```
+target("test1"): -DROOT -DTEST1
+target("test2"): -DROOT -DTEST2
+target("test3"): -DROOT -DROOT2 -DTEST3
+```
+
 ## Syntax simplification
 
 The configuration field syntax of xmake.lua is very flexible and can be used in a variety of complex and flexible configurations in the relevant domain, but for many streamlined small block configurations, this time is slightly redundant:
diff --git a/zh-cn/guide/faq.md b/zh-cn/guide/faq.md
index fa71cf9b..c48695e2 100644
--- a/zh-cn/guide/faq.md
+++ b/zh-cn/guide/faq.md
@@ -62,7 +62,7 @@ $ xmake -v --backtrace
 $ xmake [-w|--warning] 
 ```
 
-## 怎样基于源码自动生成xmake.lua
+## 怎样基于源码自动生成xmake.lua？
 
 如果你想临时写一两个测试代码、或者手上有一些移植过来的零散源码想要快速编译运行，可以不用专门xmake.lua，直接运行：
 
@@ -86,3 +86,10 @@ $ xmake f -y
 
 更多相关介绍，请参考文章：[xmake新增智能代码扫描编译模式，无需手写任何make文件](https://tboox.org/cn/2017/01/07/build-without-makefile/)
 
+## 为什么xmake.lua会被执行多遍？
+
+xmake.lua里面分描述域和脚本域，在描述域里面会对各种配置域进行分阶段多次解析，有可能会执行多遍，因此不要在描述域写复杂的脚本。
+
+如果要写各种复杂脚本，请在脚本域内进行配置，`target/on_load`的脚本域里面同样可以灵活配置各种target相关设置，并且提供更强大的lua脚本模块支持。
+
+更多细节见：[描述语法说明](/zh-cn/guide/syntax_description)
diff --git a/zh-cn/guide/syntax_description.md b/zh-cn/guide/syntax_description.md
index cd814bdd..41aaad96 100644
--- a/zh-cn/guide/syntax_description.md
+++ b/zh-cn/guide/syntax_description.md
@@ -9,7 +9,7 @@ target("test")
     add_files("src/*.c")
 ```
 
-## 配置域
+## 配置分离
 
 xmake.lua采用二八原则实现了描述域、脚本域两层分离式配置。
 
@@ -126,12 +126,70 @@ target("test")
 
 我们可以吧自定义的脚本放置到xmake.lua对应目录下，`modules/test/load.lua`和`modules/test/install.lua`中独立维护。
 
-这些独立的lua脚本里面，我们还可以通过import导入各种内置模块和自定义模块进来使用，就跟平常写lua, java没啥区别。
+这些独立的lua脚本里面，我们还可以通过[import](/zh-cn/manual/builtin_modules?id=import)导入各种内置模块和自定义模块进来使用，就跟平常写lua, java没啥区别。
 
 而对于脚本的域的不同阶段，`on_load`主要用于target加载时候，做一些动态化的配置，这里不像描述域，只会执行一遍哦!!!
 
 其他阶段，还有很多，比如：`on/after/before`_`build/install/package/run`等，具体看下后面的target api手册部分吧，这里就不细说了。
 
+## 配置类型
+
+在描述域配置中，分配置域和配置项，配置域里面可以通过`set_xxx`/`add_xxx`的接口，配置各种配置项。
+
+```lua
+target("test1")
+    set_kind("binary")
+    add_files("src/*.c")
+
+target("test2")
+    set_kind("binary")
+    add_files("src/*.c")
+```
+
+像上述配置中，target就属于配置域，它下面的所有`set_xx`/`add_xxx`接口配置都属于配置项，对这个target局部生效。
+
+我们可以把它理解成局部作用域，类似c里面的block块：
+
+```
+target("test1")
+{
+    set_kind("binary")
+    add_files("src/*.c")
+}
+target("test2")
+{
+    set_kind("binary")
+    add_files("src/*.c")
+}
+```
+
+不过，为了简化写法，xmake约定每个新定义的target域开始，上一个配置域就自动结束了，当然，如果这样用户觉得有困扰，也可以手动配置离开域：
+
+
+```lua
+target("test1")
+    set_kind("binary")
+    add_files("src/*.c")
+target_end()
+
+target("test2")
+    set_kind("binary")
+    add_files("src/*.c")
+target_end()
+```
+
+### 配置域
+
+目前提供的配置域有：`target()`, `option()`, `task()`, `package()`
+
+每个域的详细说明，见：[API手册](/zh-cn/manual/project_target)
+
+### 配置项
+
+只要是带有`set_xxx`和`add_xxx`字样的配置，都属于配置项，一个配置域里面可以设置多个配置项。
+
+关于配置项的规范说明，见：[接口规范](/zh-cn/manual/specification)
+
 ## 作用域
 
 xmake的描述语法是按作用域划分的，主要分为：
@@ -202,7 +260,7 @@ target("demo")
 - print
 - os
 
-当然虽然内置lua api提供不多，但xmake还提供了很多扩展api，像描述api就不多说，详细可参考：[API手册](/zh-cn/manual)
+当然虽然内置lua api提供不多，但xmake还提供了很多扩展api，像描述api就不多说，详细可参考：[API手册](/zh-cn/manual/builtin_modules)
 
 还有些辅助api，例如：
 
@@ -349,7 +407,65 @@ add_files("*.c")
 
 最后附上，tbox的[xmake.lua](https://github.com/tboox/tbox/blob/master/src/tbox/xmake.lua)描述，仅供参考。。
 
-## 配置结构
+## 多级配置
+
+在脚本域我们可以通过import导入各种丰富的扩展模块来使用，而在描述域我们可以通过[includes](/#/zh-cn/manual/global_interfaces?id=includes)接口，来引入项目子目录下的xmake.lua配置。
+
+记住：xmake的includes是按照tree结构来处理配置关系的，子目录下的xmake.lua里面的target配置会继承父xmake.lua中的根域配置，例如：
+
+目前有如下项目结构：
+
+```
+projectdir
+    - xmake.lua
+    - src
+      - xmake.lua
+```
+
+`projectdir/xmake.lua`是项目的根xmake.lua配置，而`src/xmake.lua`是项目的子配置。
+
+`projectdir/xmake.lua`内容：
+
+```lua
+add_defines("ROOT")
+
+target("test1")
+    set_kind("binary")
+    add_files("src/*.c")
+    add_defines("TEST1")
+
+target("test2")
+    set_kind("binary")
+    add_files("src/*.c")
+    add_defines("TEST2")
+
+includes("src")
+```
+
+里面全局根域配置了`add_defines("ROOT")`，会影响下面的所有target配置，包括includes里面子xmake.lua中的所有target配置，所以这个是全局总配置。
+
+而在test1/test2里面的`add_defines("TEST1")`和`add_defines("TEST2")`属于局部配置，只对当前target生效。
+
+`src/xmake.lua`内容：
+
+```lua
+add_defines("ROOT2")
+
+target("test3")
+    set_kind("binary")
+    add_files("src/*.c")
+    add_defines("TEST3")
+```
+
+在`src/xmake.lua`子配置中，也有个全局根域，配置了`add_defines("ROOT2")`，这个属于子配置根域，只对当前子xmake.lua里面所有target生效，也会对下级includes里面的子xmake.lua中target生效，因为之前说了，xmake是tree状结构的配置继承关系。
+
+所以，这几个target的最终配置结果依次是：
+
+```
+target("test1"): -DROOT -DTEST1
+target("test2"): -DROOT -DTEST2
+target("test3"): -DROOT -DROOT2 -DTEST3
+```
 
 ## 语法简化