On 13/03/2014 10:44 pm, Sebastian Huber wrote:
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.
I agree. This can happen once we have moved to the new server system
because we will be able to have other services running.
We need to keep user and developer documentation separated. We also need
to be mindful of the how we manage all the documentation from user
interfaces as reference material, to the BSPs in a release, BSP on head,
then through to fast changing developer type documentation.
Amar has some views on this so I hope he pops up and comments.
Chris
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.
_______________________________________________
rtems-devel mailing list
rtems-devel@rtems.org
http://www.rtems.org/mailman/listinfo/rtems-devel
