[150] 优化指令参数说明的格式

[Xiangze-Li]

Originally posted by @fy0 in #842 (comment)

按照群内讨论，我认为可以借鉴文档中所示的这一规则：

5. [关键字1|关键字2] 的方括号 [] 搭配竖线 | 表示可以在所列各项中选择一个，或不选择此项。

即 [A|B] = ([A] | [B])

简化 (<角色名>|<序号>) 为 <角色名|序号>
即 <A|B> = (<A>|<B>)

这样的好处为：

1. .pc rename <角色名|序号> <新角色名> 比 .pc rename (<角色名>|<序号>) <新角色名> 更加紧凑
2. 因为同时存在两种括号<(，用户在看到后者时，需要辨析两种括号的区别。但对于前者，即使完全不明白<的含义，只要将其跳过，并将 | 读作“或”，就很容易结合上下文理解。“pc rename 角色名或序号 新角色名”

[Xiangze-Li]

我反对增加语法糖的修改。我的理由是：增加语法糖而不禁止旧的写法只是在增加用户需要记忆的语法规则量。

我希望修改者能按 ta 的想法重新设计语法，为以下各个情况分别定义唯一的写法：

1. 单个字面量
2. 单个变量
3. 可省略的单个字面量
4. 可省略的单个变量
5. 多选一的多个字面量
6. 多选一的多个变量
7. 可省略的多选一的多个字面量
8. 可省略的多选一的多个变量
9. (可选) 多选一的变量、字面量混合
10. (可选) 可省略的多选一变量、字面量混合

作为参考，在当前语法下，以上 10 种情况分别表述为：

1. literal
2. <variable>
3. [literal]
4. [<variable>]
5. (literal1|literal2)
6. (<variable1>|<variable2>)
7. [literal1|literal2]
8. [<variable1>|<variable2>]
9. (literal|<variable>)
10. [literal|<variable>]

[fy0]

我认为这一糖是对已经存在的规则5的延伸，如果认为5的 [A|B] 能展开是自然的，那 <A|B> 不予展开与否就有些奇怪？
编程语言中语法糖的结果往往是自然的替换了旧的写法。用户也不会在每次用的时候脑袋里展开成旧的，甚至渐渐就忘了旧写法

[Xiangze-Li]

我认为这一糖是对已经存在的规则5的延伸，如果认为5的 [A|B] 能展开是自然的，那 <A|B> 不予展开与否就有些奇怪？

在当前规范中，[A|B] 的展开并不侵入 A 或 B 的内部。A 或 B 代指的项目是字面量或变量，在展开后仍然是字面量或变量。

编程语言中语法糖的结果往往是自然的替换了旧的写法。用户也不会在每次用的时候脑袋里展开成旧的，甚至渐渐就忘了旧写法

那么我希望你能做到一步到位地替换旧写法，不要让两种写法共存，以免增加记忆成本

[JustAnotherID]

认可同一个含义不应该存在两种表达。
如果觉得旧写法不够紧凑，最好是统一 替换，而不是 增加 一种写法。

[fy0]

E <- ((expr / or / wrap / orExt / replacedExt) sp)+ // 入口

identifier <- ... // 总之就是非符号unicode字符串

replacedName <- '<' identifier '>'
keywords <- identifier // 具体在指令中就是参数名 例如 list rename rm 等等

expr <- replacedName / keywords

or <- '[' expr ']'
wrap <- '(' expr ')'

orExt <- '[' (expr '|')+ ']'
replacedExt <- '<' (identifier '|')+ '>'

sp <- ' ' // 空格

[fy0]

认可同一个含义不应该存在两种表达。 如果觉得旧写法不够紧凑，最好是统一 替换，而不是 增加 一种写法。

最终在文档和帮助中，只会看到一种写法。只是恰好与旧语法没有语义冲突。

作为参考，在当前语法下，以上 10 种情况分别表述为：

1. literal
2. <variable>
3. [literal]
4. [<variable>]
5. (literal1|literal2)
6. (<variable1>|<variable2>) ---> <variable1|variable2>
7. [literal1|literal2]
8. [<variable1>|<variable2>] ---> [<variable1|variable2>]
9. (literal|<variable>)
10. [literal|<variable>]

只有6和8写法变化了。

[fy0]

结论：
sealdice/sealdice-manual-next#209

[Xiangze-Li]

对立解决方案：如果在下个版本发版前仍没有将使用现行规范的说明统一修改为新提议规范（包括 sealdice/sealdice-manual-next#209，以及截至发表此评论仍暂缺的 core 中指令帮助修改，后者可以参照 #841），则应该视为该新提议是难以实行的，建议将 #842 (comment) 中被标记的位置视为格式不符合现行规范，采纳建议的修改