[PATCH 0/1] c-user: Generate I/O Manager documentation

[Chris Johns]

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:
> 
> https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf
> 
> 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
is OK?

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

to:

20.4.1  rtems_io_close()

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
description around?

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.

Chris