乐伦。1 月 24 日。2022 年 13:32，Steffen Möller @ .*** a écrit：

开发人员手册描述了 C++ 编码风格，我非常希望看到 asciidoc 文件的模拟。这里的想法是，一旦我们就函数的描述应该如何看或表格和图形应该如何描述/引用、翻译什么和不翻译什么达成一致，那么这可能会对文档的外观和接受度有很大帮助LinuxCNC 对于决定采用该技术的人。

非常同意这个提议，因为它将解决几天前在#linuxcnc-devel 上表达的一系列担忧！
从我的头顶，我会补充说：

• 标题标签块，如 toc 等
• 标题和其他块的锚点
• 标题和其他块的索引条目
• 列表格式 * 列表与标题的用法
• 使用粗体和斜体
• 结构/页面拆分指南（2k+ 行页面对我来说不太好看）
• 脚注
• 注释

我自愿成为提出骨架和一些关于我希望如何显示表格的详细信息的人。

那副骷髅肯定价值连城！+1
因为我已经在努力完成法语文档的重组，所以我不会提供帮助来编写这些文档，

我不知何故感觉到你已经想出了一个相当漂亮的骨架。

但很乐意与开发人员一起讨论和评论……实际上，我已经考虑过使用 Asciidoc 查看其他重要项目，看看他们如何使用它以及他们是否有这样的文档可以派生……我认为进一步推动它我们应该讨论采用https://antora.org/来管理我们的各种版本，

看起来很整洁，不知道它。不过，不要认为这项技术可以解决我们眼前的“问题”。首先，这些并不是真正的问题，它更像是 LinuxCNC 中所有好的部分与笨拙（正在寻找一个结合了“陡峭”和“不平滑”的词）之间的唠叨差异，它呈现给自己它的用户。有些部分很棒。其他人不是。

并最终像 MK 已经完成的那样为项目代码重组做好准备。

甚至 MK 似乎也不想拆分我们现在的单体 git 存储库。那是另一回事。也许我们如此渴望重组一切，因为我们无法理解 LinuxCNC 构建块，并希望任何此类重组能够帮助部分征服 LinuxCNC。更好的文档可能会带来一些额外的想法。

https://github.com/owncloud/docs/blob/master/docs/best-practices.md可能也值得一读。

我知道这仍在进行中，这只是部分相关，但我注意到我们有几个与代码风格和贡献相关的文件。其中一些文件埋藏得很深，很难找到。当我们构建和生成文档时，这一切都很好，但是当您只想创建一个简单的 PR 时。我认为这些文件的访问权限不够。

CONTRIBUTING.adoc能不能在根目录有个叫的文件，把相关文件缝进去？
如果您 fork 并下载 repo，这将使从 GitHub 和您的文件系统中发现变得容易得多。

到目前为止我见过的潜在候选文件：

src/CodingStyle
docs/src/code/style-guide.adoc
docs/src/code/contributing-to-linuxcnc.adoc

docs/src/code/building-linuxcnc.adoc也是一个可以更容易访问的文件。

对于文件src/CodingStyle和docs/src/code/style-guide.adoc，它们包含相同的信息。

添加一个链接怎么 docs/src/code/contributing-to-linuxcnc.adoc样docs/src/code/style-guide.adoc？因为贡献给出了更一般的概述。

src/CodingStyle可以删除，是的。

我想知道如果代码风格指南变得太长，我们是否应该为文档风格指南创建一个单独的文件。

就像我认为投稿页面应该是介绍性的，并
包含这部分的 ToC。

是的好主意:-)

为 LinuxCNC 做贡献

介绍

…

代码风格

文档风格

我从没想过一个好的文档需要这么多?

我建议我们从它开始。任何此类文件都不会完成，所以我们不应该等待。也宁愿将其视为我们在讨论文档 PR 时所做决策的结构化文档。

我刚刚看到我提出了这个问题，有点震惊。@silopolis，请将您自己视为此问题的所有者。

试图赶上，只是略读。
如果这提到“不超过三层标题”，否则构建日志最终会充满错误。
（可能是 4 层。问题是在文档组装期间添加了顶层，这会破坏 adoc，因为它只支持有限数量的标题层。