You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by GitBox <gi...@apache.org> on 2022/10/09 02:11:49 UTC
[GitHub] [shardingsphere] lanchengx opened a new issue, #15604: Plans to refactor DistSQL documents
lanchengx opened a new issue, #15604:
URL: https://github.com/apache/shardingsphere/issues/15604
**Current status**
```shell
├── _index.cn.md
├── _index.en.md
├── ral
│ ├── _index.cn.md
│ └── _index.en.md
├── rdl
│ ├── _index.cn.md
│ ├── _index.en.md
│ ├── resource-definition.cn.md
│ ├── resource-definition.en.md
│ └── rule-definition
│ ├── _index.cn.md
│ ├── _index.en.md
│ ├── db-discovery.cn.md
│ ├── db-discovery.en.md
│ ├── encrypt.cn.md
│ ├── encrypt.en.md
│ ├── readwrite-splitting.cn.md
│ ├── readwrite-splitting.en.md
│ ├── shadow.cn.md
│ ├── shadow.en.md
│ ├── sharding.cn.md
│ ├── sharding.en.md
│ ├── single-table.cn.md
│ └── single-table.en.md
└── rql
├── _index.cn.md
├── _index.en.md
├── resource-query.cn.md
├── resource-query.en.md
└── rule-query
├── _index.cn.md
├── _index.en.md
├── db-discovery.cn.md
├── db-discovery.en.md
├── encrypt.cn.md
├── encrypt.en.md
├── readwrite-splitting.cn.md
├── readwrite-splitting.en.md
├── shadow.cn.md
├── shadow.en.md
├── sharding.cn.md
├── sharding.en.md
├── single-table.cn.md
└── single-table.en.md
```
Related links: [Directory tree](https://github.com/apache/shardingsphere/tree/master/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax)
**Disadvantages:**
1. Inconvenient to find
There is no complete list, users need to know which category the target sentence belongs to, and then go to find the page of the category
2. Too much syntax on a single page
For example, the RDL of sharding is all on one page, which is inconvenient to view
3. Example confusion
- Some grammars have multiple usages, which are not described in detail
- Difficulty understanding different uses of the same syntax in one example, such as [sharding](https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-proxy/distsql/syntax/rdl/rule-definition/sharding/)
**Refactoring suggestion:**
1. Keep the categories the same, split multiple syntax from a single page, and provide descriptions for statement definitions
2. Provide more detailed special instructions, including precautions during execution, execution results, and exceptions that occur
3. Provide associative links when there are dependencies between different syntax
**Example of refactored directory structure:**
```shell
├── _index.cn.md
├── _index.en.md
├── ral
│ ├── ......
│ └── ......
├── rdl
│ ├── _index.cn.md
│ ├── _index.en.md
│ ├── resource-definition
│ │ ├── _index.cn.md
│ │ ├── _index.cn.md
│ │ ├── add-resource.cn.md
│ │ ├── drop-resource.cn.md
│ │ ├── alter-resource.cn.md
│ │ └── ......
│ └── rule-definition
│ ├── _index.cn.md
│ ├── _index.en.md
│ ├── encrypt
│ │ └── ......
│ ├── sharding
│ │ ├── _index.cn.md
│ │ ├── _index.en.md
│ │ ├── create-shariding-algorithm.cn.md
│ │ ├── create-shariding-strategy.cn.md
│ │ ├── create-shariding-key-generator.cn.md
│ │ ├── create-shariding-table-rule.cn.md
│ │ ├── create-shariding-binding-table_rule.cn.md
│ │ ├── create-shariding-broadcast-table-rule.cn.md
│ │ ├── create-shariding-table-rule.cn.md
│ │ └── ......
│ └── ......
└── rql
├── ......
├── ......
└── rule-query
├── ......
├── ......
├── ......
└── ......
```
**Example of refactored file structure:**
1. Syntax name
2. Function
3. Syntax Definition
4. Syntax examples (including all usages of the grammar)
5. Special instructions (including keyword description, exception explanation, precautions)
6. Related links (related syntaxes appearing in the example)
_Reference: [PostgreSQL](https://www.postgresql.org/docs/14/sql-createrole.html) and [MySQL](https://dev.mysql.com/doc/refman/8.0/en/create-role.html)_
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@shardingsphere.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [shardingsphere] RaigorJiang closed issue #15604: Plans to refactor DistSQL documents
Posted by GitBox <gi...@apache.org>.
RaigorJiang closed issue #15604: Plans to refactor DistSQL documents
URL: https://github.com/apache/shardingsphere/issues/15604
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@shardingsphere.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [shardingsphere] RaigorJiang commented on issue #15604: Plans to refactor DistSQL documents
Posted by GitBox <gi...@apache.org>.
RaigorJiang commented on issue #15604:
URL: https://github.com/apache/shardingsphere/issues/15604#issuecomment-1383186644
Completed, thank you!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@shardingsphere.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [shardingsphere] github-actions[bot] commented on issue #15604: Plans to refactor DistSQL documents
Posted by GitBox <gi...@apache.org>.
github-actions[bot] commented on issue #15604:
URL: https://github.com/apache/shardingsphere/issues/15604#issuecomment-1272350335
Hello , this issue has not received a reply for several days.
This issue is supposed to be closed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@shardingsphere.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [shardingsphere] github-actions[bot] closed issue #15604: Plans to refactor DistSQL documents
Posted by GitBox <gi...@apache.org>.
github-actions[bot] closed issue #15604: Plans to refactor DistSQL documents
URL: https://github.com/apache/shardingsphere/issues/15604
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@shardingsphere.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [shardingsphere] RaigorJiang commented on issue #15604: Plans to refactor DistSQL documents
Posted by GitBox <gi...@apache.org>.
RaigorJiang commented on issue #15604:
URL: https://github.com/apache/shardingsphere/issues/15604#issuecomment-1272432991
Not completed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@shardingsphere.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org