我同意 HAL 组件文档应该以结构化的方式列出每个组件。
如果能找到某种方法来显示来自主文档的联机帮助页信息，那就更好了。显而易见的方法是链接到联机联机帮助页。（但这不能离线工作）

联机帮助页由 halcompile 自动生成，这就是为什么它们只是按字母顺序组合在一起的原因。很难以任何其他方式做到这一点。

特别考虑到 demux，似乎由于某种原因，三重引号的两行描述被分成了概要：https ://github.com/LinuxCNC/linuxcnc/blob/2.8/src/hal/components/demux .comp
这可能是一个简单的修复，但也意味着有一种方法可以解决http://linuxcnc.org/docs/2.8/html/man/man9/bldc.9.html中不整洁的双重概要

也许可以从联机帮助页生成或扩展 html？然后它可以离线使用
但是首先，你能解释一下 的html代码是如何生成的吗？

目前我们不分发离线 html 文档。文档包仅包含 PDF。
但是，我认为正在查看离线 html。（我听说过提到“狮身人面像”，但我能找到的只是https://forum.linuxcnc.org/32-documents/38889-survey-the-state-of-the-documentations-and-ways-to-improve -it#164933所以我可能在传递 IRC 时看到了它）

文档生成过程几乎与魔术没有区别:-)

大部分工作由 docs submakefile完成，它以我并不真正遵循的方式
使用docbook和A2X 。
Google 找到了很多从 Asciidoc 制作联机帮助页的方法，但在逆向过程中却很少，而这正是 LinuxCNC 在某些地方所做的。
我认为还有一个 XML 层，也是为了好玩。

也许我们可以为每个 hal 组件添加一个类别。
然后我们就可以在这些分类中显示hal组件列表了。那行得通吗？
如果有单独的详细信息页面，我们可以在描述栏中添加指向该页面的链接。
因此，总会有所有可用组件的完整列表。如果组件没有类别，它会显示在“其他”下方。
它可能看起来像这样：

从“组件”行开始的一行描述应该是一个相对容易的更改，因为信息存在于手册页中。
向 comps（和手写的联机帮助页）添加一个额外的标签会需要更多的工作，但似乎并非不可能。

问题是将列表放在哪里。让它在手册页部分，或者移动到 HAL 部分。
我们可以突出显示此版本中的新组件?

是否可以创建一个我有权推送的分支？如果是，我将不胜感激能够在创建拉取请求之前看到更改。

编辑：但是文档不能在每个分支的网络服务器上访问，不是吗？

是否可以创建一个我有权推送的分支？

这样做的方法是创建 LinuxCNC 的“分支”（LinuxCNC 的副本在您自己的 Github 存储库中），然后将其克隆到您的 PC 中与 linuxcnc-dev 目录不同的目录中。当您对更改感到满意时，您可以从您的分叉存储库向 LinuxCNC 发出“拉取请求”。
（而且，因为它是您自己的存储库，所以您可以犯任意多的错误，而且没有人知道）

有一些内务处理，您需要使用 LinuxCNC 使您的分支保持最新，这不是自动的，您可能希望将所有提交“压缩”为一个（或少量）以保持历史简单。

是的，正如你所知，我这样做是因为你合并了我的拉取请求
但是如何通过这些更改访问网络服务器？
例如：#993如何在网络服务器上查看此版本？
http://linuxcnc.org/docs/ <branch?> 我猜只适用于主要分支……

很抱歉这么久才回复，我错过了问题部分。

要查看新版本的文档，您需要在您的 PC 上编译它们并查看本地版本。

cd linuxcnc-dev/src
./autogen.sh
./configure –enable-build-documentation=pdf,html
制作

将构建两组文档（构建文档有很多依赖项，准备安装一些包，如 asciidoc）

生成的文档最终会出现在 linuxcnc-dev/docs 的顶层

谢谢，当我通过构建系统设置时，我会尝试。

我得到它的工作，谢谢！
一个新的想法出现在我的脑海中。如何美化手册页的 html 表示？
我将 doc 样式表添加到手册页生成中，并想出了如何将图片添加到仅用于 html 生成的手册页中。
与单独的文档页面相比，优势在于您可以将所有信息捆绑在一处。
但它不是那么舒服，你没有太多的可能性在 groff 中格式化文档页面。
因此，如果有一个复杂的 hal 组件需要更多文档，可以在手册页或概述页中添加指向单独页面的链接。

在这里，您可以看到手册页与样式表的外观，我向 toggle2nist 组件添加了一张图片，例如：master...Hans470:2.8-restructure-hal-doc
无需编译即可快速查看，请参见此处：example.zip

因此，如果您同意这一点，那么只剩下分类任务了。
有一个定义组件类别的分配表怎么样？
因此不需要向 hal comps 添加额外的参数。如果没有定义类别，例如新组件，它将显示在未分类/其他下方。

是的，带样式的 html 肯定更好。

我仍然无法决定该类别是否应该存储在联机帮助页中（手动存储，或从 .comp 中的标签存储），或者最好是单独的表格。
我认为，该表也可能是 submakefile 中的硬编码语句。当可以直接编码时，解析 makefile 中的表可能没有意义。编辑内容的人应该是同一个人。

嗯，我建议完成http://linuxcnc.org/docs/2.8/html/hal/components.html中的列表，并添加指向手册页的链接，因为我对 makefile 不是很熟悉。
像这样：

@jethornton你对此有什么想法吗？

因为目前我无事可做，所以我将我的更改推到现在为止：#1052

是时候继续这个话题了:)

我想在文档的 HAL 部分（http://linuxcnc.org/docs/devel/html/hal/components.html ）生成所有 HAL 组件的列表（基于 man9 文件夹中的所有文件）。

例如，它看起来像这样：

对于类别，我可以想象为每个手册页添加一个名为“CATEGORY”的标题。该类别将用于上述分组。这也将显示在手册页中，但我认为这不会惹恼：（
如果有人对此感到恼火，我想我们会找到一个看不见的解决方案）

但这给 PDF 文档带来了一个问题：因为手册页是一个额外的文档，所以 HAL 部分中的链接在 PDF 中不起作用。
解决方案可能是：

• 将 HAL-pdf 添加到 main-doc-pdf
• 将分类的 HAl-list 移动到手册页部分和 man-pdf

你对此有何看法？

此外 – 提供完整的压缩 HTML 文档作为下载怎么样？

我认为必须手动完成 HAL 组件的分类列表（只是为了正确分类）。
我可能是编译它的合乎逻辑的选择之一，因为我比大多数人更了解 HAL。

可下载的 HTML 文档可能是个好主意。我往往会忘记有些人可能不会一直在线。

是的，当然必须手动选择类别。
但我们通常有三种选择：

• 完成当前静态分类列表
• 根据手册页中的类别条目生成列表
• 生成一个列表，其中包含一个数据字典，指定哪个组件属于哪个类别

(1) 现在可以了，但是如果添加了新组件，它们可能会忘记添加到列表中。
这就是查看目录的生成列表的想法。所有新组件都可以显示在“其他”或“未分类”下。但这并没有解决 PDF 问题。

可下载的 HTML 文档可能是个好主意。我往往会忘记有些人可能不会一直在线。

我认为这就是我们拥有 PDF 版本的原因