Documentation

[Sebastian Huber]

Hello,

I tried to find a good place for the user-level profiling documentation and I 
struggled again with the Doxygen vs. Texinfo duplication.  I raised this issue 
several times over the last years, but we cannot carry on with this parallel 
structure forever.  I think it is quite hard to navigate through the HTML 
version of the user guide

http://rtems.org/onlinedocs/doc-current/share/rtems/html/c_user/index.html

and the visual appearance is not state of the art.  So we should convert the 
user guide in the long run to a modern documentation system.  I don't care if 
this is Doxygen or something else, but it must support API documentation 
generation from the sources.  You have for example

http://rtems.org/onlinedocs/doc-current/share/rtems/html/c_user/Event-Manager-Sending-an-Event-Set.html#Event-Manager-Sending-an-Event-Set

and on another page

http://rtems.org/onlinedocs/doc-current/share/rtems/html/c_user/Event-Manager-EVENT_005fSEND-_002d-Send-event-set-to-a-task.html#Event-Manager-EVENT_005fSEND-_002d-Send-event-set-to-a-task

also in Doxygen

http://www.rtems.org/onlinedocs/doxygen/cpukit/html/group__ClassicEvent.html#ga2d31674c165127bc530178d06d557b94

A lot of copy and paste is involved here and writing stuff for the Texinfo is 
always a pleasure.

My proposal is still to use Doxygen simply because we already spent a huge 
amount of work for it and it has from my point of view all features we require 
(in source documentation, book style parts, graphs, formulas, message diagrams, 
HTML and PDF output), e.g.

http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdpage

http://www.rtems.org/onlinedocs/doxygen/cpukit/html/group__ClassicEventTransient.html

http://www.rtems.org/onlinedocs/doxygen/cpukit/html/group__rtems__bdbuf.html#details

I am open for alternatives, but we should really stop using two systems for the 
documentation.

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