google / google/comprehensive-rust

Use definition lists for glossary?

Open
#2,802 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
33.4k
Forks
2.1k
Avg merge
1d 3h
Merged PRs (30d)
10

Description

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.:

```md
- 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](https://www.markdownguide.org/extended-syntax/#definition-lists).

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

```html


allocate

Dynamic memory allocation on the heap.

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.

```

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

```html

allocate

Dynamic memory allocation on the heap.

```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.