Use definition lists for glossary?

未关闭
  • 哪里不对？
#2,802 2 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 17 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
28/100
Issue 类型
文档
描述清晰度
需要澄清
活跃度
停滞
技术栈
html, markdown
领域
documentation

调研方向

定位术语表源文件，并检查仓库的 Markdown 处理器或配置，以确定是否支持定义列表语法。将当前标记与提议的

/
/
形式进行比较，并验证生成的链接和锚点；完成的标准是有一项记录在案的决定，并且如果接受该方案，术语表已完成一致的转换。

由索引模型根据 Issue 内容生成。

描述

Perhaps this is somewhat pedantic, but I wonder whether we should be move from an unordered list of terms to a definition list for the glossary?

This would be more semantically correct and would allow us to avoid manual hard breaks in our current source text, e.g.:

- allocate:\
  Dynamic memory allocation on [the heap](memory-management/review.md).
- argument:\
  Information that is passed into a function or method.
- associated type:\
  A type associated with a specific trait. Useful for defining the relationship
  between types.

Unfortunately, it looks as though current markdown processor does not support the extended syntax for dl, dt and dd tags.

That would mean that we would be required to hand-write HTML:

<dl>
  <dt>allocate</dt>
  <dd>Dynamic memory allocation on <a href="memory-management/review.html">the heap</a>.</dd>

  <dt>argument</dt>
  <dd>Information that is passed into a function or method.</dd>
  
  <dt>associated type</dt>
  <dd>A type associated with a specific trait. Useful for defining the relationship between types.</dd>

…which would unlock the ability to refer to the glossary from other parts of the course.

  <dt id="allocate">allocate</dt>
  <dd>Dynamic memory allocation on <a href="memory-management/review.html">the heap</a>.</dd>
主要语言
Rust
星标
33.5k
派生
2.1k
平均合并
16 天 20 小时
30 天内合并 PR
1

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

google/comprehensive-rust 的其他 Issue

查看 google/comprehensive-rust 的全部 Issue

相似的 Issue

更多 Rust Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。