[PATCH 0/1] c-user: Generate I/O Manager documentation
chrisj at rtems.org
Thu Oct 1 04:11:17 UTC 2020
On 30/9/20 12:59 am, Sebastian Huber wrote:
> This is the first generated documentation of a manager. For the PDF
> output please have a look at:
> Please review the layout. I changed the layout to use definition lists
> instead of tables. The benefit of definition lists is that the layout
> of longer text paragraphs is much nicer compared to tables (at least for
> the PDF output).
> Sebastian Huber (1):
> c-user: Generate I/O Manager documentation
> c-user/io/directives.rst | 550 ++++++++++++++++++-------------------
> c-user/io/introduction.rst | 37 ++-
> 2 files changed, 295 insertions(+), 292 deletions(-)
My comments are only about the PDF. I would like to see the HTML as well if that
Where is the source of this generated documentation? I would like to review that
side of things and how it is generated before I am OK with this change.
The headings have changed. For example:
20.4.1 IO_REGISTER_DRIVER - Register a device driver
I am OK with the change as the bookmarks are much more useful but I think Joel
needs to say this is OK. These names go back a long way and carry a lot of history.
The order the directives are in has changed. The IO Manager's directives are
currently in order of use by a user. What defines the order now?
The formatting around 'DIRECTIVE RETURN VALUES:' needs fixing. There is vertical
space after the heading but not before. It looks to me like the heading type is
broken as 'CALLING SEQUENCE:' etc also appears to have the same vertical spacing.
Why change 'DIRECTIVE STATUS CODES:' to 'DIRECTIVE RETURN VALUES:'?
There is description text after the directive section heading and then there is
a 'DESCRIPTION: section. This seems wrong to me. The change from the status code
table to the list is welcome, those tables were a pain to get right but the
description now looks lost after them. I do not know what would work here as the
call sequence at the start is something I like. Is it OK to have the call seq
then the description then the args and return values? I do not know as a long
description moves the call seq away from the top. Do the 'NOTES:' follow the
There needs to be a page break after each directive. That is a new directive
should start on a new page in the PDF format. I think there is a piece of Tex
inserted to do this.
More information about the devel