[PATCH] doc improvements
Chris Johns
chrisj at rtems.org
Wed Dec 2 20:58:18 UTC 2020
On 3/12/20 4:09 am, Gedare Bloom wrote:
> A significant challenge with the version numbers arises during the release
> process. I will leave all these doc patches for Chris to review/feedback, but
> the concern is that when a release is cut all the version numbers need to be
> injected to the release and then updated for the main branch.
The version number in a formal sense is managed. In the documentation the
support is in common/version.py.
The complicated part is in the examples and commands because there is no easy
way in Sphinx to make them programmable. At various points in time I have
invested time in a solution and got no where. I consider pre-processing the
source with macros but changing a version number is only part of what is needed.
Newer versions of tools often have different output and we need to keep that
updated. A simple example is the version number of gcc.
As a result we either remove example output or we have to maintain the documents.
Chris
>
> On Wed, Dec 2, 2020 at 6:23 AM Robin Müller <robin.mueller.m at gmail.com
> <mailto:robin.mueller.m at gmail.com>> wrote:
>
> I will provide another patch with version numbers corrected.
>
> Kind Regards
> Robin
>
> On Wed, 2 Dec 2020 at 14:19, Robin Müller <robin.mueller.m at gmail.com
> <mailto:robin.mueller.m at gmail.com>> wrote:
>
> Actually, I just saw that when switching to the 5 branch for the RTEMS
> sources, there is no waf tool (at least I can't run it) so later parts
> of the QuickStart guide won't work..
> I could just leave it like that, but then RTEMS 6 is built and all
> version numbers would have to be corrected..
>
> KInd Regards
> Robin
>
> On Wed, 2 Dec 2020 at 13:59, Sebastian Huber
> <sebastian.huber at embedded-brains.de
> <mailto:sebastian.huber at embedded-brains.de>> wrote:
>
> Hello Robin,
>
> On 02/12/2020 13:46, Robin Mueller wrote:
> > ---
> > user/start/sources.rst | 9 +++++++++
> > user/start/tools.rst | 9 ++++++++-
> > 2 files changed, 17 insertions(+), 1 deletion(-)
> >
> > diff --git a/user/start/sources.rst b/user/start/sources.rst
> > index 8c40aa0..fddc439 100644
> > --- a/user/start/sources.rst
> > +++ b/user/start/sources.rst
> > @@ -86,12 +86,21 @@ You can clone the Git repository to get all
> versions of RTEMS including the
> > development head. Release branches in Git are kept stable
> however they may
> > differ from a release's source archive.
> >
> > +For this Quick Start guide, we will switch to the RTEMS 5
> branches because the
> > +master branch does not contain the version 5 `rtems-sparc` build set.
> > +If you wich to build with the master branch instead, it is
> recommended to
> > +replace the version number 5 with version 6 everywhere it is used
> in the Quick Start guide.
> the documentation for the master branch should not refer to the RTEMS 5
> release. So, the right fix is to replace '5' with '6' if needed.
> > +
> > .. code-block:: none
> >
> > mkdir -p $HOME/quick-start/src
> > cd $HOME/quick-start/src
> > git clone git://git.rtems.org/rtems-source-builder.git
> <http://git.rtems.org/rtems-source-builder.git> rsb
> > + git checkout origin/5
> > + git checkout -b 5
> > git clone git://git.rtems.org/rtems.git
> <http://git.rtems.org/rtems.git>
> > + git checkout origin/5
> > + git checkout -b 5
> >
> > The :file:`rsb` repository clone contains the :ref:`RTEMS Source
> Builder (RSB)
> > <RSB>`. We clone it into :file:`rsb` to get shorter paths
> during the tool
> > diff --git a/user/start/tools.rst b/user/start/tools.rst
> > index baa2387..e0fe10d 100644
> > --- a/user/start/tools.rst
> > +++ b/user/start/tools.rst
> > @@ -20,7 +20,14 @@ The tool suite for RTEMS and the RTEMS sources
> are tightly coupled. For
> > example, do not use a RTEMS version 5 tool suite with RTEMS
> version 4.11
> > sources and vice versa.
> >
> > -Build and install the tool suite:
> > +The available build sets can be displayed with:
> > +
> > +.. code-block:: none
> > +
> > + cd $HOME/quick-start/src/rsb/rtems
> > + ../source-builder/sb-set-builder --list-bsets
> > +
> > +Build and install the version 5 tool suite for the SPARC
> architecture:
> >
> > .. code-block:: none
> This part looks good to me.
>
> --
> embedded brains GmbH
> Herr Sebastian HUBER
> Dornierstr. 4
> 82178 Puchheim
> Germany
> email: sebastian.hubere at embedded-brains.de
> <mailto:sebastian.hubere at embedded-brains.de>
> phone: +49-89-18 94 741 - 16
> fax: +49-89-18 94 741 - 08
>
> Registergericht: Amtsgericht München
> Registernummer: HRB 157899
> Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
> Unsere Datenschutzerklärung finden Sie hier:
> https://embedded-brains.de/datenschutzerklaerung/
> <https://embedded-brains.de/datenschutzerklaerung/>
>
> _______________________________________________
> devel mailing list
> devel at rtems.org <mailto:devel at rtems.org>
> http://lists.rtems.org/mailman/listinfo/devel
> <http://lists.rtems.org/mailman/listinfo/devel>
>
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
More information about the devel
mailing list