Re: [PATCH v2] HID: Add introduction about HID for non-kernel programmers

[Peter Hutterer <peter.hutterer@who-t.net>]

On Thu, Jul 13, 2023 at 04:36:18PM +0200, Marco Morandini wrote:
> 
> The current version is with a unique code block, and renders like this
> 
> https://home.aero.polimi.it/morandini/Downloads/Screenshot_20230712_185907.png
> 
> With a unique code block but a newline in between the report and the
> explanation I get
> 
> https://home.aero.polimi.it/morandini/Downloads/Screenshot_20230712_190335.png
> 
> that I find somewhat more dispersive.
> 
> If I interpose multiple code blocks and explanations (as text) unfortunately
> spynx add a colon at the end of every paragraph, as if the text was the explanation of the
> code block below, and not above:
> 
> https://home.aero.polimi.it/morandini/Downloads/Screenshot_20230712_190656.png
> 
> I've not understood how to get rid of that colon, and I would prefer to leave the
> explanation _after_ the corresponding code block, and not move it before.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks

This suggests that if you write it as "what follows is a button ::"
(i.e. space before ::) that should render it without a colon.

[...]

> >> +This Report Descriptor tells us that the mouse input will be
> >> +transmitted using four bytes: the first one for the buttons (three
> >> +bits used, five for padding), the last three for the mouse X, Y and
> >> +wheel changes, respectively.
> > 
> > I wonder if here we should mention something like:
> > "This particular device only has one HID report so it may (and does)
> > omit the Report ID. Devices that can send multiple different HID reports
> > must send the Report ID as the first byte of each report."
> 
> The problem is that, with the current document structure,
> Report IDs are introduced later, in section
> "Collections, Report IDs and Evdev events".
> There we have the sentence "A device with only one supporteHID report 
> (like the mouse example above) may omit the report ID."
> 
> Before that section the reader does not know what
> a Report ID is.
> 
> Thus, I could add the sentence you are suggesting, but
> changing it into something like
> 
> This particular device only has one HID report so it may (and does)
> omit the Report ID (see Section "Collections, Report IDs and Evdev events"). 
> Devices that can send multiple different HID reports
> must send the Report ID as the first byte of each report.
> 
> I don't know whether we are clarifying of confusing the matter,
> and I propose to leave things as they are now.

sure, that's fine

Cheers,
  Peter