On 14/1/19 5:36 pm, Sebastian Huber wrote: > I added a build of the partially restructured user manual here: > > https://ftp.rtems.org/pub/rtems/people/sebh/user.pdf >
Any HTML? As an aside in the copyright block I wrote of lot of initial parts of this manual and then have been adding pieces most years including 2018. How do the year lists work? > 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. > Yes I agree and also each major section should have something. >> >> 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. Nice and yes I agree. > >> >> 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? Yeah good question. A "tool chain" seems to have a meaning, a compile etc, a "tool set" is an RSB based term and "tools" is overloaded with the rtems-tools. I suppose to have a host tool suite? For example, the first sentence from the Installation section: "This section details how to set up and install the RTEMS Ecosystem. You will create a tools suite for your host compiler and an RTEMS kernel for your selected Board Support Package (BSP)." > >> >> 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. Sure. > >> >> 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. > Great. >> >> 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. Hmm I am not sure, for some reason it looks and feel incomplete, needing more work because the heading are not formal. For example 'i386' would look better under Intel. > >> >> 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. I suspect your texlive has a working xindy which is better than mine. I have emailed the tex port maintainer and heard nothing back and the tex port lists seem dormant. The FreeBSD Tex on 12-RELEASE is 2015 and that verison pre-dates the xindy command. It is a bit of a mess. Chris _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel