TWiL 23 and more

README.en.md

@@ -19,7 +19,7 @@
     - [x] Homepage
     - [ ] I18n
 * [x] GHA workflow
-* [ ] Contributor guide
+* [x] Contributor guide
 
 ### License
 
@@ -28,11 +28,11 @@ A copy of the license is [available locally](./LICENSE) too.
 
 ### Local Development
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator.
 
 ```
 $ yarn  # install/upgrade deps if needed
-$ yarn make-plugins  # if src/plugins/awly-data-plugin is touched
+$ yarn build-helpers  # if scripts/asmdb is touched
 $ yarn start
 ```
 

README.md

@@ -19,7 +19,7 @@
     - [x] 首页
     - [ ] 国际化
 * [x] GHA 工作流
-* [ ] 贡献者指南
+* [x] 贡献者指南
 
 ### 许可证
 
@@ -28,11 +28,11 @@
 
 ### 本地开发
 
-本站以 [Docusaurus 2](https://docusaurus.io/)，一款现代化的静态网站生成器构建。
+本站以 [Docusaurus 3](https://docusaurus.io/)，一款现代化的静态网站生成器构建。
 
 ```
 $ yarn  # 如果需要的话，安装或升级依赖
-$ yarn make-plugins  # 如果变更了 src/plugins/awly-data-plugin 的话
+$ yarn build-helpers  # 如果变更了 scripts/asmdb 的话
 $ yarn start
 ```
 

docs/contrib/basics.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 1
+---
+
+# 基本参与方法
+
+:::warning 施工现场！
+本文目前尚不完整。维护者想起来更新或被催更，则会更新；否则请不要认为所有相关的规范都完整记录了。
+:::
+
+本站本质上是个 [Docusaurus 3](https://docusaurus.io/) 文档站，
+所以在动手码字<small>儿</small>之前，最好读一下 Docusaurus 的文档。
+
+对不写代码<small>儿</small>的文字工作者而言，
+Docusaurus 的 [Markdown 特性支持](https://docusaurus.io/docs/markdown-features)文档也会有帮助——Docusaurus
+Markdown 能用的特性跟 CommonMark、GitHub Flavored Markdown、MDX 都不太一样！
+
+对于工作量小的变更（diff 不超过 10 行<small>儿</small>或者两三个文件，就能搞定的那种），
+可以做了直接提上来；
+否则建议先来[上游](https://github.com/loongson-community/areweloongyet)开个 issue 讨论下，有了共识再着手做。
+这是为了防止出现做了一大堆，投入许多时间和精力，结果维护者不需要，弄得大家都不愉快的情况。
+
+本站仓库的提交说明采用 [Conventional Commits](https://www.conventionalcommits.org) 风格。
+如果不太清楚，可以 `git log` 看下你要改的文件先前的变更，提交说明都是什么风格。

docs/contrib/index.md

@@ -0,0 +1,10 @@
+---
+sidebar_position: 100
+---
+
+# 参与本站开发
+
+这里的资料，主要是主创团队维护本站这些日子以来，脑内守则的文字化：
+如果现在以及未来的贡献者们都能大致遵循它们，
+那么所有提交本站的内容都能符合一贯的风格、质量要求，
+而沟通成本、来回次数等等都可以得到优化了。

docs/contrib/natlang-style-guide.md

@@ -0,0 +1,213 @@
+---
+sidebar_position: 2
+---
+
+# 《咱龙了吗？》自然语言风格指南
+
+:::warning 施工现场！
+本文目前尚不完整。维护者想起来更新或被催更，则会更新；否则请不要认为所有相关的规范都完整记录了。
+
+由于本站的 i18n 工作仍未完成，本文目前只覆盖汉语文本。
+后续适用于英语文本的内容仍待记录。
+:::
+
+随着龙架构®的生态成熟、市场份额扩张，先前一般被认为不会接触此技术的用户也纷至沓来。
+这一般是好事<small>儿</small>，但不巧的是：
+此架构先天带有一些非中立的色彩[^politics]——
+这使得先后「入坑」的龙架构&reg;开发者，乃至无技术背景的最终用户群体，具有了明显的异质性。
+根据笔者亲身经历，这种异质性在不受尊重、管控的情况下，将会并且已经造成了一些社区裂痕：
+《咱龙了吗？》作为意在团结社区而成立的项目，自然不可能置身事外，或者添油加醋。
+
+:::info 笔者思考：为何明知龙架构非中立，还有必要使本站保持中立？
+龙架构&reg;至今未完整开放授权，且其立场先天不中立；
+这些特点是如此明显，至少近（2022~2023）年在中文互联网上对龙芯&reg;有所粗浅了解的网友应该都会清楚。
+
+因此，我们应能够假定一位来自中文互联网的网友，只要 tā 对龙架构发表了建设性的内容，
+那么该网友对龙架构应该持整体正面看法——
+
+* 要么完全赞同其发展方针、具体执行等，
+* 要么对其一部分规划或做法持保留意见但整体上仍然乐见其成功。
+
+但同质性仅限于此：由于这些网友的年代、身份、阶层、教育、政治背景可能迥异，
+对龙架构下的许多具体话题或事务，后一部分人是会与前一部分人产生龃龉乃至冲突的。
+甚至生活方式、文字表达习惯等等的细枝末节，
+在具体语境下，差异可能也会被放大，导致上述的问题。
+
+因此为了利用这仅有的同质性，广泛团结这部分社会力量，
+笔者不认同将这些「对龙架构持整体正面看法」的网友视作某种「政党」或「社会团体」这种相对同质的群体，
+而只能视作「统一战线」——多么恰当的称呼啊。
+:::
+
+[^politics]: 假如没有发生先前的 MIPS&reg; 授权风波，或者假如在 2018~2020 的时间节点龙芯公司得以反客为主接管 MIPS 公司在桌面、服务器端的上游主导权，那么龙芯公司决策者们对「自主可控」的理解大概率不会是今天的形态，龙架构&reg;也将不会发生。
+
+## 简而言之
+
+* 尊重他者，
+* 尽量从客观角度中立陈述，
+* 避免非必要的情感表达或主观臆断。
+
+## 立场
+
+本站与龙芯公司或任何其他商业公司都利益无关，
+但这不代表本站必然站在龙芯公司或这些其他公司的对立面。
+具体来讲：
+
+* 对于来自商业公司的明显宣传性质或立场偏颇的文字，必须以明显方式将其区分于本站其他正文。
+
+  例如：使用直接引语而非间接引语；使用 Markdown 块<small>儿</small>引用。
+
+* 注意避免「诉诸权威」逻辑陷阱。
+
+  一个命题，并不因其出自龙芯、龙芯的「友商」、其他无关公司、老胡、笔者、其他吃瓜群众之口，便自动是对的或错的。
+  需要避免将这种论述不带论据或限定地加以引用。——如果加够了限定成分，倒是没问题：
+  表意清晰了那怎么引都没问题。
+
+* 谨慎使用带感情色彩的词语、修辞、句式等。
+
+  汉语是个爱憎分明的语言，很多词甚至句式都自带褒贬色彩，当我们谈论工程技术时需要避免使用。
+  请注意：对任何外物的，任何无铺垫/佐证的评价，都不应带感情色彩。
+
+* 对一件事，如要做非技术方面评论，则必须作善意推定，且体现换位思考；且如有必要则应提醒读者注意。
+
+  如[《每周一龙》第 14 期的 Linux 部分报道](/newsletter/this-week-in-loongarch-14/#linux)，当时有个瓜。
+  「有变量未被初始化即被使用」是客观事实；从客观事实引申出感情色彩非中立的评价，可行。
+  即便如此，也不能做「XXX 好/坏」「XXX 公司好/坏」的引申：一方面世界不是非黑即白的，另一方面也轮不着我们评价。
+
+## 中西混排
+
+中日韩文字与西文混排时，应在其间加空格<small>儿</small>。
+但西文与中日韩全角标点<small>儿</small>相邻则不用空格<small>儿</small>。
+
+## 标点符号<small>儿</small>
+
+整体上请遵循《标点符号用法》（[国家标准 GB/T 15834-2011](http://www.moe.gov.cn/jyb_sjzl/ziliao/A19/201001/W020190128580990138234.pdf)）。
+但：
+
+* 由于纯粹视觉设计方面的原因，本站更倾向于使用竖排引号<small>儿</small>（形如“「」”的引号<small>儿</small>）。
+  现有很多文章对引号<small>儿</small>形状的使用不一致，后续都要改掉的。
+
+## 儿化标记
+
+本站的多数文章都多多少少有些趣味<small>儿</small>性。
+由于笔者和他的许多朋友都操北方方言，他们的口语多少带点<small>儿</small>儿化；
+为了忠实记录这种轻松的口语氛围，我们争取把所有儿化音都标出来。
+
+按照《现代汉语词典》（如果没记错的话）的体例，
+表示儿化的「儿」字要比正文略小一号<small>儿</small>——就像这样。
+然而这种用法没有专用的 Unicode 码点（即便有，输入法也不支持），
+我们目前也没做自定义的 Markdown 语法来简化书写，
+因此现在你只好用比较冗长的下边<small>儿</small>这个写法<small>儿</small>。
+
+```md
+<small>儿</small>
+```
+
+## 「的地得」
+
+为避免歧义、方便读者，请严格按照语法功能区分使用「的地得」。复习一遍：
+
+* 修饰体词性短语（自己是定语），用「的」；
+* 修饰谓词性短语（自己是状语），用「地」；
+* 后接加词性短语（补语），用「得」。
+
+## 人称代词
+
+使用人称代词指代某人时，除非你能确认被称呼人的个人意愿或偏好，否则一律使用 `tā`；
+使用人称代词指代某群人时，除非你能确认该群体所有个体都同意你拟采用的称呼，
+否则一律使用 `tā 们`。
+
+虽然目前本站并未涉及到相关风波，且「他」字历史上大部分时间都不表示或暗示性别，
+但目前中文互联网上客观存在这么一批人不认为「他」字性别中立，
+且现代汉语书面语也确实无法用一个字表达性别未知的第三人称。
+为了规避这方面风险[^risk]，
+也鉴于 2022 年前后的网络汉语已经无法用「他」字简短、精确、中立地传达第三人称的性别信息，
+我们为了简短、精确、中立地表示「我们不清楚对方的代词为何」这一信息，
+就只能使用汉语拼音了——至少汉语普通话的「tā」这个读音在可预见的将来都不会带有性别暗示。
+
+[^risk]: 本站迟早被冲，但笔者个人不希望是因为这原因——好歹也基于技术原因来冲吧……
+
+## Markdown 链接
+
+所有可被链接内容佐证的材料，都应伴以链接。
+
+优先使相关句子的中心动词成为链接：
+「几月几日，谁<a>提交了</a>什么」，让「提交了」三个字链接到 tā 提交的东西。
+
+当不方便这么做，或者这样做表意不最佳的时候，基本是因为被链接的内容不对应中心动词：
+此时改为使相关的短语成为链接。
+例如：
+
+* 「XXX <a>开心地</a>回复道：……」，重点在开心，那么应以「开心地」三个字为链接。
+* 「XXX 搞了一系列修复：<a>补丁一</a>、<a>补丁二</a>、<a>补丁三</a>」，三个修复共用一个中心动词，那么应以三个「补丁X」短语为链接。
+
+不要使用「点击这里怎么怎么样」或类似的表达。
+例如，不要写「点击<a>这里</a>查看活动详细信息」，
+而用「活动详情请见<a>主办方页面</a>」「活动主办方也<a>设置了</a>详细信息页面」等更加描述式的写法。
+
+## 句式（尤指话题句）
+
+除非当前行文、上下文风格很明显能将读者引向当前句子的某种特定理解（话题句与否），
+否则请尽量避免话题句。
+这意味着基本只有在口语化特征非常明显的段落，才可以使用话题句，
+
+汉语缺乏提示语法成分的助词，而全靠语序和「常识」。
+如果在同一段话中混杂使用口语的话题句与常规书面表达方式，
+将给部分读者[^why-this-is-unconditionally-bad]造成你始料未及的歧义——下文即介绍了一例。
+因为我们不能假定读者具备怎样的文化背景，
+自然也就不方便预判读者；
+因此，还请作者们默认尽量采用偏书面甚至「欧化」的表达方式，
+尽量不要做话题提前、省略连词等「汉语特色」的表达。
+
+[^why-this-is-unconditionally-bad]: 当然，能「跟上趟<small>儿</small>」或者说「跟上作者脑回路」的读者，确实没被歧义坑到就是了；但也不要忽视这些读者为了「跟上作者脑回路」而在脑内遍历所有句子结构，所不得不做的额外努力、消耗的额外能量。何况这种努力还未必 100% 成功。因此混用口语/话题句表达与书面表达，几乎一定是件坏事<small>儿</small>，请不要这样做。
+
+<details>
+<summary>经典案例分析（摘自《龙芯架构参考手册》卷一 2.2.7.1 节）</summary>
+
+:::info 原文
+`AM*` 原子访存指令如果 `rd` 和 `rj` 的寄存器号相同，则触发指令不存在例外。
+:::
+
+笔者印象中 2022 年以来，至少有 3 位开发者没看懂这句话：如果「触发（的）指令」「不存在」例外，那哪些指令存在呢？
+
+对比《手册》英文版对这句话的翻译（有删改；[原文](https://github.com/loongson/LoongArch-Documentation/blob/f05f84435aca5e4d166ed0f147d8e9e9cb30911c/docs/LoongArch-Vol1-EN/basic-integer-instructions/overview-of-basic-integer-instructions/atomic-memory-access-instructions.adoc#L74)有语法错误）：
+
+:::info 译文
+If the `AM*` atomic memory access instruction has an `rd` equal to `rj`,
+an Instruction Non-defined Exception will be triggered.
+:::
+
+哦哦，这是断句问题：「指令不存在例外」是个专有名词。
+问问题的同学当时不熟悉龙架构，不知道这回事<small>儿</small>——
+可能他们跳着看《手册》，没发现第 2.1.4 节明确规定了「触发……例外」这个词组的含义，
+还介绍了「指令不存在例外」这个概念——
+但这个句子本身也并非毫无问题。
+
+它的前半句「……指令如果……寄存器号相同」，其正式书面表达应该是「如果……指令的……寄存器号相同」：
+由于作者写作时心里重点在「指令」，这部分便被倒装到话题位置了。
+这使读者不自觉地进入口语话题句的「句法解析模式」，
+以至于不熟悉专有名词的同学更容易把后半部分理解成「则……不存在例外」了。
+
+:::tip 排版也能帮上忙<small>儿</small>！
+在上例中，英文表述没有理解障碍的原因有两方面：
+
+* 能标记中心动词：
+  英文版中「指令不存在例外」很明显是一个整体的名词短语，因为「non-define*d*」一眼就不是中心动词。
+  显然，汉语没有类似的语法手段可用，本例的情况下虚词也没合适的。
+
+  在汉语表达中，如果一个句子不被按照话题句式理解，那么本例的问题大概不会出现。
+  不巧的是，本例整句的正确理解，只有前半部分是话题句——既无法用语法构造提醒读者，中文书写上也不分词，
+  于是没有任何其他手段能标记「指令不存在例外」是个整体了，
+  总之在读者缺乏先验知识的前提下，用《手册》的原句表达方式是不可能消解歧义了。
+* 能通过大小写等方式传达额外信息：`INE` 作为这个例外的规范、标识符命名，在行文中，其全称也受到了首字母大写的待遇。
+
+  中文虽然没有大小写，但也存在换字体、加粗、下划线等类似手段，而《手册》原文没有使用。
+
+在汉语写作中，虽然我们没得格属标记、非主要动词这些手段用，
+但作为排版手段丰富的技术文档，
+我们完全也能通过直观、清晰的排版差异来弥补单纯文字表达在语法结构传达方面的不足。
+恰好 Docusaurus 3 允许我们借助 [`remark-directive`](https://github.com/remarkjs/remark-directive)
+给 Markdown 添加自定义标签了；
+只要有人肯贡献代码，这应该是相对更优的解决办法。
+:::
+
+</details>

newsletter/2023-08-28-this-week-in-loongarch-13.md → newsletter/2023-08-28-this-week-in-loongarch-13.mdx

@@ -8,7 +8,7 @@ tags: [每周一龙]
 
 每周一都为大家报道 LoongArch® 社区最前线的第一手新鲜资讯！
 
-<!-- truncate -->
+{/* truncate */}
 
 如无特别说明，文中提及的日期、时间都为北京时间（UTC+8）。
 
@@ -45,8 +45,9 @@ Linux 上游社区不仅维护内核，也包括许多 Linux 的周边软件、
 除以上变更之外，还有许多同等重要的缺陷修复、代码重构等工作值得褒扬。
 这个版本动过龙芯相关代码的所有开发者们（按字母顺序排序，以 Git 提交记录中的作者字段为准）：
 
-<div style={{columns: "3 auto"}}>
+import ColumnedList from '@site/src/components/ColumnedList'
 
+<ColumnedList columns={3}>
 * Andy Shevchenko
 * Arnaldo Carvalho de Melo
 * Arnd Bergmann
@@ -85,8 +86,7 @@ Linux 上游社区不仅维护内核，也包括许多 Linux 的周边软件、
 * YingKun Meng
 * Youling Tang
 * Zhihong Dong
-
-</div>
+</ColumnedList>
 
 当你使用龙架构 Linux 6.5 时，别忘了向 tā 们表达一声感谢！
 

newsletter/2023-09-04-this-week-in-loongarch-14.md

@@ -16,7 +16,7 @@ tags: [每周一龙]
 
 本栏目的内容具有一定延续性，将持续追踪报道 LoongArch® 领域的重要或长期项目（坑）。
 
-### Linux
+### Linux {#linux-6.6-loongarch-changes}
 
 截至发稿时，Linux 6.6 的合并窗口工作正风生水起，子系统维护者们都在忙着整理代码、提交 <ruby>PR<rt>拉取请求</rt></ruby>。
 合并窗口预计在美西时间的本周日下午（9 月 10 日；中国时间 9 月 11 日）关闭；

newsletter/2023-10-30-this-week-in-loongarch-22.md

@@ -14,7 +14,7 @@ tags: [每周一龙]
 
 如无特别说明，文中提及的日期、时间都为北京时间（UTC+8）。
 
-## 要闻速递：千呼万唤始出来，龙架构®上新了！
+## 要闻速递：千呼万唤始出来，龙架构®上新了！ {#loongarch-r1p10}
 
 10 月 23 日，龙芯中科将《龙芯架构参考手册》更新到了 LoongArch® v1.10[^注一] 版本。
 这一修订版主要是将 LA664 微架构（对应 3A6000 型号）的新增、变更特性落成文档了。