security: Roundhouse kick on some grammar stuff

[s-hemer]

Mostly related to english grammar/sentence, yet sometimes I also refined some sentences as a whole. Commit by file as it is hard to read through and correct stuff in a "topic"-wise manor...

[mschwan-phytec]

Thank you for the fixes!

There are some small issues still, before I would merge this.

[s-hemer]

I have several general formatting issues where I need your opinions:

• (k/Kernel) fitImage/FIT image/FIT-image -> one of the latter two should IMHO be used
• Device Tree/device tree/devicetree/device-tree -> I think the first one should be always used
• in-text (Yocto) variable with `` or w/o
• highlight inline filenames/paths: ``, * or nothing?

[mschwan-phytec]

I have several general formatting issues where I need your opinions:

Okay, here we go... (nerd-mode is on) 🙂

* (kernel) fitImage/FIT image/FIT-image -> one of the latter two should IMHO be used

It depends on what the text is describing exactly:

• "fitImage" is used for the kernel image filename, as is used for "zImage" and "Image". This is an actual file on the disk.
• "FIT image" or "FIT-image" don't make much sense. These dissolve to "Flattened Image Tree image", which contains one "image" too much at the end. If you want to be precise, and describe the image tree, use either just "FIT", "Flattened Image Tree" or "image tree" depending on the context. See below on device trees, for an analog explanation.

* Device Tree/device tree/devicetree -> I think the first one should be always used

Again, it depends. See https://www.kernel.org/doc/html/latest/devicetree/usage-model.html for some examples.

• "Open Firmware Device Tree" or "Devicetree" is used in the context of the official name of the specification, or when describing acronyms, such as "Device Tree Binary (dtb)".
• "device tree" is used when we want to refer to the tree structure of file containing the information/source code. This is probably what you are using for describing your specific device tree in the kernel or bootloader 99% of the time, outside of any introductory text or specification.

* in-text (Yocto) variable with `` or w/o

Bitbake variables should use the inline code styling ``, as this is considered source code.

* highlight inline filenames/paths: ``, * or nothing?

Historically, in our Word-based manuals from ten years (and earlier) ago, we used italics to emphasize inline filenames and paths. However, with the availability of more advanced documentation tools, such as Sphinx with reStructuredText syntax, we are better off using inline code styling `` to highlight these. This makes it more distinguishable from regular text and actual emphasizes.

[s-hemer]

@motto-phytec Which chapter is meant here?

[s-hemer]

I have several general formatting issues where I need your opinions:

Okay, here we go... (nerd-mode is on) 🙂

* (kernel) fitImage/FIT image/FIT-image -> one of the latter two should IMHO be used

It depends on what the text is describing exactly:

* "fitImage" is used for the kernel image filename, as is used for "zImage" and "Image". This is an actual file on the disk.

* "FIT image" or "FIT-image" don't make much sense. These dissolve to "Flattened Image Tree image", which contains one "image" too much at the end. If you want to be precise, and describe the image tree, use either just "FIT", "Flattened Image Tree" or "image tree" depending on the context. See below on device trees, for an analog explanation.

The question arises from the principle inconsistencies throughout our docu and that I came across several of those here in the security part -> we should document that in the CONTRIBUTING readme.
In principle, your explanations confirm what I already thought, yet especially the FIT topic is a tough one: even the Yocto classes are called "fitimage". For a first step, I would vote for a consistent use of i.e. "FIT image" (if we refer to the Kernel binary file "fitImage" then it should go in `` anyways).

[mschwan-phytec]

The question arises from the principle inconsistencies throughout our docu and that I came across several of those here in the security part -> we should document that in the CONTRIBUTING readme. In principle, your explanations confirm what I already thought, yet especially the FIT topic is a tough one: even the Yocto classes are called "fitimage". For a first step, I would vote for a consistent use of i.e. "FIT image" (if we refer to the Kernel binary file "fitImage" then it should go in `` anyways).

I totally agree with you. There are many inconsistencies in our documentation and even in other projects.

I'm fine with using "FIT image" for the mentioned purposes.

I've put the CONTRIBUTION.md changes on my to-do list. That's definitely something we should do and I had the same thoughts during writing.