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 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
