RSB documentation

[Sebastian Huber]

I added a build of the partially restructured user manual here:

https://ftp.rtems.org/pub/rtems/people/sebh/user.pdf

On 13/01/2019 23:03, Chris Johns wrote:
> On 11/1/19 8:13 pm, Sebastian Huber wrote:
>> At which position in the manual should it be placed? I think we should organize the chapters according to the relevance for new users and how the are used later during application development. I would use the RSB chapter as a reference chapter containing all the details and cover the common case in the Quick Start chapter. So, I would move the RSB chapter to the end after the Host Tools.
> The place the RSB moves to could depend on where some others get moved too. A
> review of the sections follows.
>
> Do we need a "How to use this manual?" section in the Introduction? It could
> also have a "What to read before starting" part.

I think this should go into Introduction -> Overview.

>
> The manual is organised as:
>
>   Introduction
>    Overview, features, what a real-time and what a real-time kernel is.
>
>   Ecosystem
>    Rational, open source and deployment. This is to explain what we
>    call the host side tools, commands, and configuration. Maybe we
>    need to explain RTEMS is only run on targets and is not self
>    hosting so the ecosystem provides a consistent host side
>    environment.
>
>    This section needs to be enhanced to cover the RSB, RTEMS Tools
>    and what ever else we want to include. The deployment section's
>    building binary tools can be moved to some where else, that is
>    an advanced topic.

I moved the Ecosystem into Introduction, since it introduces the RTEMS 
world. I think it fits quite well here.

>
>   Quick Start
>    I think we need to keep a top level section called "Quick Start"
>    because it is easy for a new user to see and click on. The sidebar
>    on the html output is collapsed and searching for a quick start or
>    something like it is awkward. Links to other sections should aim to
>    provide launch sites to more detail.

Yes, this is now the second chapter. I would like to use the following 
sections:

"Host Computer Setup"
"Prefixes"
"RTEMS Repository Clone"
"RTEMS Tool Set Installation"
"RTEMS Source Bootstrap"
"BSP Configuration and Installation"
"Example Application"

Do we want to use "tool chain" or "tool set" or "tools" for the RTEMS 
things running on the host computer?

>
>   Host Computer
>    Should this be placed under Ecosystem?
>
>    This needs to be before the RSB section so the correct packages are
>    present on the host for the RSB.

I think this should remain a separate chapter. It is one of the first 
things you have to deal with as a new user.

>
>   Installation
>    This explains the environment. Is this also part of the Ecosystem?

The installation of things running on the host and the installation of 
an RTEMS BSP should be in separate chapters.

>
>   Hardware
>    A discussion about the way RTEMS views hardware, architectures and
>    BSPs. This is about the RTEMS side of things rather than the
>    host and the ecosystem.
>
>   Board Support Packages
>    The BSPs. I have been wondering if the BSP names are suitable
>    heading or do we want something more formal if that is even
>    possible?

The heading is now "<BSP family directory name> (<product marketing 
name>)". This should make it easy to find.

>
>   Executables
>    This is the first section I have added that starts with something
>    about the section and what to expect. I think this is a good
>    practice to do.
>
>    I am planning to add a section on libdl and applications for it
>    once the rtl-archive and rtl-ctor-dtor branches in
>    https://git.rtems.org/chrisj/rtems.git/ are merged.
>
>   Testing
>    Using the rtems-test and rtems-run interface to run code.
>
>   Tracing
>    The tracing support for RTEMS. This is the last in a progression
>    from a host, tools, kernel, testing the kernel, to runtime performance.
>
>   Host Tools
>    The published interface to the tools we support. In effect the interface
>    users can depend on across releases.
>
> I hope this helps.
>
> Note: I see the index is broken with the online builds. I suspect the
> genindex.rst removal I did is the cause and I also suspect there is an issue
> between versions of sphinx-build being used. My development version is newer
> than the online builder but we cannot update that version until the xindy issue
> on FreeBSD is resolved and even with upstream FreeBSD fixing the port getting it
> into the version 10 we run is problematic.

It is also broken on my host. I use sphinx-build 1.8.1.

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