Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: first cut of command_reference refactor #3848

Merged
merged 9 commits into from
Jul 13, 2023
Merged

docs: first cut of command_reference refactor #3848

merged 9 commits into from
Jul 13, 2023

Conversation

timfeirg
Copy link
Contributor

@timfeirg timfeirg commented Jun 25, 2023

这个 pr 包含:

  • command_reference 采用企业版文档相同的表格样式
  • 大量共享参数的命令,不重复罗列,比如 webdav, gateway 就有大量参数同 mount,这种情况就不再一一列举
  • 将“语法”更名为“概要”,不仅描述命令格式,还直接在代码块里罗列常用示范,更加一目了然
  • 半角括号改为全角,每个选项描述末尾都以句点结尾
  • 如果存在与之高度相关的章节,在选项描述中予以引用
  • 抛弃 --option value 的写法,这里的 value 不提供有效信息,将其改为其默认值来提供更好的描述性
  • 不再用“(默认:x)”的方式来描述默认值,先前的参数描述都偏简单,可以采用同一的格式。但描述文字多了以后,经常有其他文字也需要使用括号来承载,为了避免括号过多,也允许更自由的行文,取消掉固定的括号默认值写法。但由于工作量大,本 pr 不会通篇修改,而是随着迭代逐渐修改

这个 pr 不会包含:

  • 不会撰写全新的内容,缩小 review 范畴
  • 不会修改功能描述相关文档,缩小 review 范畴

这个 pr 依赖:#3875

@timfeirg
Copy link
Contributor Author

考虑到修改量大,先修改了一小节,review 通过后再将改动施加到所有命令 @xiaogaozi @zhijian-pro @SandyXSD

@timfeirg timfeirg marked this pull request as draft June 25, 2023 08:28
@xiaogaozi
Copy link
Member

LGTM, please continue to complete the remaining work.

docs/zh_cn/reference/command_reference.md Outdated Show resolved Hide resolved
docs/zh_cn/reference/command_reference.md Show resolved Hide resolved
@SandyXSD
Copy link
Contributor

You may address the comments above in another PR. Others LGTM.

@timfeirg
Copy link
Contributor Author

chinese part is finished, review and I'll continue to apply the changes on the english part @xiaogaozi

@xiaogaozi xiaogaozi self-requested a review June 29, 2023 08:07
@timfeirg
Copy link
Contributor Author

timfeirg commented Jul 4, 2023

translation done, #3875 must precede this pr for CI to pass @xiaogaozi

@xiaogaozi xiaogaozi self-requested a review July 5, 2023 10:56
@timfeirg timfeirg marked this pull request as ready for review July 12, 2023 16:05
@timfeirg
Copy link
Contributor Author

conflicts resolved, commence final review @xiaogaozi

@timfeirg timfeirg merged commit 54b3081 into main Jul 13, 2023
@timfeirg timfeirg deleted the docs/reference branch July 13, 2023 08:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants