Documentation

[Chris Johns]

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