RE: [PATCH] docs: Format (void *) to fix reStructuredText emphasis warnings

[Bernhard Kaindl <bernhard.kaindl@xxxxxxxxxx>]

Nicola Vetrini <nicola.vetrini@xxxxxxxxxxx> wrote:

> Reviewed-by: Nicola Vetrini <nicola.vetrini@xxxxxxxxxxx>

Thanks!

> 
> See nit below
[...]
> 
> There are further instance below which should similarly be rendered with
> a monospaced font, as they are code
> 
> e.g.
> 
> The conversion from ‘void noreturn (*)(…)’ to ‘void (*)(…)’ is safe
> because the semantics of the ‘noreturn’ attribute

Correct, those would be further TODOs, but they don't cause warnings.

> Perhaps those don't cause warnings, but if we want to visualize this as
> code in a monospaced font, then it probably should be uniformly used in
> the document. We haven't been 100% consistent when writing these
> documents originally; partly due to the fact that different people were
> involved, but this could be an occasion to remedy that.
> 
> But perhaps that is best done in a follow-up patch, so feel free to take
> my r-by for this patch.

Yes, they should be follow-ups. I saw this and other further TODOs but think
these are best co-ordinated with you.

There would be a lot that could be done in that way by others (that does not
have to be me) and they are quite simple.

Other reasons why those should be follow-ups are that there is a lot of grey 
zones
after that, e.g. a sentence that mentions 'unsigned long' may be formatted as
``unsigned long`` for consistency with ``void noreturn (*)(…)`` (and so on).

Bernhard

PS: All combined, that could make for a very nice, improved document, but that
should ideally be done by someone who cares for the Misra Documents, or at least
in close cooperation, I think, the effort/time spent is merged in the end.

I just submitted small set of improvements for code blocks and formatting 
literals
for demonstrating what can be improved in this direction:

https://patchwork.kernel.org/project/xen-devel/list/?series=1087288