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
