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

[Gedare Bloom]

On Mon, Mar 22, 2021 at 3:12 PM Chris Johns <chrisj at rtems.org> wrote:
>
> 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:
>
I like tagging.

> .. 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 ...
>
A script/tutorial to regenerate these parts could work also. Kind of a
guide how to update for a new version, and what needs to be
run/captured as output examples.

> Chris