Re: [PATCH 6/7] docs: add a glossary

[Pierrick Bouvier <pierrick.bouvier@linaro.org>]

On 12/3/24 10:10, Alex Bennée wrote:
> Peter Maydell <peter.maydell@linaro.org> writes:
> 
>> On Mon, 18 Nov 2024 at 17:24, Pierrick Bouvier
>> <pierrick.bouvier@linaro.org> wrote:
>>>
>>> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
>>> ---
>>>   docs/devel/control-flow-integrity.rst |   2 +
>>>   docs/devel/multi-thread-tcg.rst       |   2 +
>>>   docs/glossary/index.rst               | 238 ++++++++++++++++++++++++++
>>>   docs/index.rst                        |   1 +
>>>   docs/system/arm/virt.rst              |   2 +
>>>   docs/system/images.rst                |   2 +
>>>   docs/tools/qemu-nbd.rst               |   2 +
>>>   7 files changed, 249 insertions(+)
>>>   create mode 100644 docs/glossary/index.rst
>>
>> I think this is a good idea; we've had at least one bug
>> report from a user pointing out that we had a term in
>> our docs which we didn't define ("block driver"):
>> https://gitlab.com/qemu-project/qemu/-/issues/2611
>> I have some comments on specific entries below.
>>
>>> diff --git a/docs/devel/control-flow-integrity.rst b/docs/devel/control-flow-integrity.rst
>>> index e6b73a4fe1a..3d5702fa4cc 100644
>>> --- a/docs/devel/control-flow-integrity.rst
> <snip>
>>> +
>>> +Device
>>> +------
>>> +
>>> +QEMU is able to emulate a CPU, and all the hardware interacting with it,
>>> +including many devices. When QEMU runs a virtual machine using a hardware-based
>>> +accelerator, it is responsible for emulating, using software, all devices.
>>
>> This definition doesn't actually define what a device is :-)
> 
> Also we can xref to:
> 
>    https://qemu.readthedocs.io/en/v9.1.0/system/device-emulation.html
> 
> where we go into a bit more detail about what a device, bus, frontend
> and backend are.
> 

Good point, I'll add it.

>>
>>> +
>>> +EDK2
>>> +----
>>> +
>>> +EDK2, as known as `TianoCore <https://www.tianocore.org/>`_, is an open source
>>> +implementation of UEFI standard. It's ran by QEMU to support UEFI for virtual
>>> +machines.
>>
>> Replace last sentence with
>> "QEMU virtual machines that boot a UEFI BIOS usually use EDK2."
>> ?
>>
> <snip>
>