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

[Sebastian Huber]

On 01/10/2020 06:11, Chris Johns wrote:
> 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?

I will upload the HTML for the v2 of the patch.

> 
> 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 documentation source for the IO Manager is here:

https://git.rtems.org/rtems-central/tree/spec/rtems/io/if

> 
> 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.

I think this makes it easer to find the directive documentation.

> 
> 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 order is now alphabetical. I think this is a bit easier for 
newcomers which know the alphabet but not necessarily the usual use by a 
user order.

> 
> 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:'?

This is a more general term, for example here status code doesn't fit well:

https://docs.rtems.org/branches/master/c-user/scheduling-concepts/directives.html#scheduler-get-processor-maximum-get-processor-maximum

> 
> There is description text after the directive section heading and then there is
> a 'DESCRIPTION: section. This seems wrong to me. 

After the section heading is the brief description (in Doxygen @brief) 
in the DESCRIPTION section is the long description.

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

No problem, it just have to exchange a couple of lines in the generator 
script.

> I do not know as a long
> description moves the call seq away from the top. Do the 'NOTES:' follow the
> description around?

What do you mean with "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.

Ok, I can add this in v2.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.