[PATCH rtems-docs v3 1/6] prefixes: Update installation prefix

[Chris Johns]

On 23/3/21 4:41 am, Gedare Bloom wrote:> I wonder what is your opinion, should
we bump these tutorials with
> every version? And, is the find/replace of the commands the best way
> to do this?
> 
> I feel like this topic comes up now and again. Maintaining these
> examples is a little fragile.

It is fragile and I have in the past invested some time looking for a way to
automatically manage these version based blocks of documentation however subtle
change happen so making it automatic is difficult. Arguments to commands change
and if there is captured output it needs to change.

> @Ida: Thanks for the patches,

Yes, thank you. The patches are great.

> now we'll need to determine if we want
> to bump these examples like this, and whether we should consider a
> better way to maintain this stuff in the future.

I am open to solutions. A few ideas are:

1. Group commands we consider as stable interfaces and see if the RTEMS version
can be supplied via a conf variable passed in by waf. This would lower the
number of changes.

2. Tag version specific blocks with something in a comment. Making a change is
part of the solution however I find knowing there is a change to make is harder.
If we can grep the sources we could see. For example:

.. rtems-version-block: 5

The version number is updated when changed so we can see what needs to be done.
This would be helpful when making releases.

3. Other ideas ...

Chris