Guidance on naming - when to say "Amaranth HDL" versus just "Amaranth".

[martinling]

It would be useful to have some guidance on preferred usage of the project's new name.

The full title of the project is now "Amaranth HDL", but in most instances within the documentation it is referred to simply as "Amaranth".

For updating existing references in comments and documentation, simply doing a search & replace from "nMigen" to "Amaranth HDL" generates some usage that feels awkward to me, and is inconsistent with the project's own usage. Yet in some instances it must be correct to use the full title.

I have just reviewed https://github.com/greatscottgadgets/luna/pull/156 on this point, and I'd like to know if my intuition on usage was correct there.

Whatever the answer, it would be great to put some explicit guidance on usage in the Amaranth documentation.

[whitequark]

The Amaranth project consists of a hardware definition language, a toolchain that processes it, and other associated libraries of code, such as the board definitions, the SoC toolkit, and so on. Roughly, the Amaranth project is what lives in the https://github.com/amaranth-lang organization.

"Amaranth HDL" refers more specifically to the language and the core toolchain (which, due to its design, are essentially the same entity). Roughly, the Amaranth HDL is what lives in the module you use when you import amaranth. This repository could have been called amaranth-hdl, though it isn't.

The documentation refers to the "Amaranth language", "Amaranth standard library", "Amaranth simulator", "Amaranth build system" and so on. These are all parts of "Amaranth HDL"; the language syntax, the standard library, and the rest of the components are designed and built together, but it can be useful to refer to them individually.

"Amaranth SoC" refers to the module you get when you import amaranth_soc, which lives in the amaranth-soc repository. The same applies to the other associated projects.

Of course, colloquial language being what it is, people use "Amaranth" to refer to the project as a whole, to the code in this repository, or to the language syntax in particular. And that's fine! You can always use the more specific terms to disambiguate, and really as long as it's clear what's being talked about.

---

In your PR you've been using the terms that feel the most clear in the context, and I think we're on the same page, there.

[Lunaphied]

We've been using Amaranth specifically on it's own to refer to the language in general. It amounts to a shorthand for the language itself. We've ended up using Amaranth HDL to refer to the overall entity of the combined sum of parts. This isn't perfectly in alignment with what you've said @whitequark, I wonder if that convention is close enough to feel comfortable to you.

[martinling]

In your PR you've been using the terms that feel the most clear in the context, and I think we're on the same page, there.

That's good to know, thanks. It seemed like the right approach but I wanted to confirm.

I think it could be helpful for others to add something about this to the documentation - just putting more or less what you wrote above in a section of the introduction would suffice.

[diegoherranz]

"Amaranth HDL" refers more specifically to the language and the core toolchain (which, due to its design, are essentially the same entity)

Just to make my mind clear, that's what was called FHDL for Migen? Thanks!

[whitequark]

I don't draw any particular parallels with Migen; most of the architectural decisions that remain derived from it (e.g. everything related to fragments) are liabilities anyway.

[diegoherranz]

OK, thanks.

[whitequark]

Keeping this issue open until we have something on this topic in the documentation.